cli: conventionalize on <command> in cmd.Use

Unifies the DX around usage across all commands. The convention follows the standards (gh / git CLIs) as well as the defaults from cobra.

The grammar is as follow:
- []: optional
- <>: user input, to differenciate with static args
- ...: one or more

This commit applies it everywhere and unifies according to this grammar.

Another point: [flags] shall always be positioned after the subcommand. Fixes it for the gen subcommand

Signed-off-by: grouville <[email protected]>

cmd/dagger/call.go

@@ -16,7 +16,7 @@ var outputPath string
 var jsonOutput bool
 
 var callCmd = &FuncCommand{
- Name: "call [flags] [FUNCTION]...",
+ Name: "call [flags] [<function> [<child-function>...]]",
  Short: "Call a module function",
  Long: strings.ReplaceAll(`Call a module function and print the result.
 

cmd/dagger/config.go

@@ -82,7 +82,7 @@ dagger config -m github.com/dagger/hello-dagger
 }
 
 var configViewsCmd = configSubcmd{
- Use: "views [name]",
+ Use: "views [flags] [<name>]",
  Short: "Get or set the views of a Dagger module",
  Long: "Get or set the views of a Dagger module. By default, print the views of the specified module.",
  PersistentFlags: func(fs *pflag.FlagSet) {
@@ -120,7 +120,7 @@ dagger config views -n my-view
  return fmt.Errorf("failed to get view patterns: %w", err)
  }
  viewMap[name] = patterns
- viewStrs = append(viewStrs, fmt.Sprintf("%s\n%s\n",
+ viewStrs = append(viewStrs, fmt.Sprintf("%s\n<%s>\n",
  termenv.String(fmt.Sprintf("%q", name)).Bold().Underline(),
  strings.Join(patterns, "\n"),
  ))

cmd/dagger/functions.go

@@ -43,7 +43,7 @@ var funcCmds = FuncCommands{
 }
 
 var funcListCmd = &FuncCommand{
- Name: "functions [flags] [FUNCTION]...",
+ Name: "functions [flags] [<function> [<child-function>...]]",
  Short: `List available functions`,
  Long: strings.ReplaceAll(`List available functions in a module.
 

cmd/dagger/gen.go

@@ -19,7 +19,7 @@ func newGenCmd() *cobra.Command {
  )
 
  var cmd = &cobra.Command{
- Use: "gen FILE",
+ Use: "gen [flags] <file>",
  Short: "Generate CLI reference documentation",
  Long: "Generate CLI reference documentation in the given file path.",
  Args: cobra.NoArgs,

cmd/dagger/main.go

@@ -340,7 +340,7 @@ const usageTemplate = `{{ "Usage" | toUpperBold }}
  {{.UseLine}}
 {{- end}}
 {{- if .HasAvailableSubCommands}}
- {{ .CommandPath}}{{ if .HasAvailableFlags}} [flags]{{end}} [command]
+ {{ .CommandPath}}{{ if .HasAvailableFlags}} [flags]{{end}} [<command>]
 {{- end}}
 
 {{- if gt (len .Aliases) 0}}
@@ -424,6 +424,6 @@ const usageTemplate = `{{ "Usage" | toUpperBold }}
 
 {{- if .HasAvailableSubCommands }}
 
-Use "{{.CommandPath}} [command] --help" for more information about a command.
+Use "{{.CommandPath}} [<command>] --help" for more information about a command.
 {{- end}}
 `

cmd/dagger/module.go

@@ -78,7 +78,7 @@ func init() {
 }
 
 var moduleInitCmd = &cobra.Command{
- Use: "init [flags] [PATH]",
+ Use: "init [flags] [<path>]",
  Short: "Initialize a new Dagger module",
  Long: `Initialize a new Dagger module in a local directory.
 By default, create a new dagger.json configuration in the current working directory. If the positional argument PATH is provided, create the module in that directory instead.
@@ -173,7 +173,7 @@ The "--source" flag allows controlling the directory in which the actual module
 }
 
 var moduleInstallCmd = &cobra.Command{
- Use: "install [flags] MODULE",
+ Use: "install [flags] <module>",
  Aliases: []string{"use"},
  Short: "Add a new dependency to a Dagger module",
  Long: "Add a Dagger module as a dependency of a local module.",

cmd/dagger/query.go

@@ -22,7 +22,7 @@ var (
 )
 
 var queryCmd = &cobra.Command{
- Use: "query [flags] [OPERATION]",
+ Use: "query [flags] [<operation>]",
  Aliases: []string{"q"},
  Short: "Send API queries to a dagger engine",
  Long: `Send API queries to a dagger engine.

cmd/dagger/run.go

@@ -20,7 +20,7 @@ import (
 )
 
 var runCmd = &cobra.Command{
- Use: "run [flags] COMMAND",
+ Use: "run [flags] <command>",
  Aliases: []string{"r"},
  Short: "Run a command in a Dagger session",
  Long: strings.ReplaceAll(

cmd/dagger/watch.go

@@ -10,7 +10,7 @@ import (
 )
 
 var watchCmd = &cobra.Command{
- Use: "watch [flags] COMMAND",
+ Use: "watch [flags] <command>",
  Hidden: true,
  Annotations: map[string]string{
  "experimental": "true",