Getting --help to print descriptions for arguments

[reallyroy]

Just wanted to check if there is a way to get Cobra to print help text for ARGS.

Say I have a CLI whose usage is:
do [SOMETHING]

I was wondering if it was possible to get do --help to print:

Usage:
    do [SOMETHING]
    [SOMETHING]: Allowed values are laundry, dishes or dinner

Flags:
   ....

The readme doesn't mention anything like this, and there are no examples on SetHelpTemplate, so I'm unsure if that is what needs to be used here. Would someone be able clarify if this is possible? And if not, are there any other options?

Thanks!

[eine]

Hi @reallyroy I think that this is not supported yet. In #395 it was suggested to edit the Use field of the command. So, something like this is possible:

Use: "build ['" + strings.Join([]string{"arg1", "arg2", "arg3"}, "'] ['") + "']",

which will produce:

Usage:
  build ['arg1'] ['arg2'] ['arg3'] [flags]

However, I think that this should be better tackled together with #838, to produce the following output:

#NoArgs

Usage:
  build [flags]

#ArbitraryArgs

Usage:
  build [flags] [args]

#MinimumNArgs(x)

Usage (NArgs>x):
  build [flags] args

#MaximumNArgs(x)

Usage (NArgs<x):
  build [flags] [args]

#ExactArgs(x)

Usage (NArgs=x):
  build [flags] args

#RangeArgs(x, y)

Usage (x<NArgs<y):
  build [flags] args

In any of the cases above, if ValidArgs is defined, a line should be added below:

Usage:
  build [flags] [args]

Allowed flag values are: strings.Join(ValidArgs, " ")

[github-actions]

This issue is being marked as stale due to a long period of inactivity

[eine]

AFAIK, this is not supported yet.

[cben]

For now, the best set of workarounds I found: (building on kofalt's example)

&cobra.Command{
	Use: "clone [flags] URL [DIRECTORY]",
	Long: "Clone a git repo from given URL into a new directory.\n" +
                "\n" +
		"URL can use git://, https://, ssh:// schemes.\n"
		"Directory defaults to last component of URL under current directory.",
	Args: func(cmd *cobra.Command, args []string) error {
		if len(args) < 1 {
			return fmt.Errorf("Repository URL is required")
		}
		if len(args) > 2 {
			return fmt.Errorf("Unexpected positional arguments after URL DIRECTORY: %s", )
		}
		return nil
	},

1. Setting Use lets you fully control the usage line.

   Including [flags] is optional, it's appended at the end if omitted and there are any flags. Personally I like it to make it clearer the words after it are placeholders for positional arguments (vs literal command names). I also use all caps.
   Reasons to keep it at end: (1) in actual usage it's frequently more convenient to pass flags after positional arguments. This is allowed in nearly all CLI tools since GNU getopt, but not enough people know it works, so putting [flags] at end can be educational. (2) If you're not careful to put [flags] before positional args in all your commands, you'll get a mixture.

2. Explain the meaning of positional arguments in Long, after a blank line. This appears before Usage, idealy would appear after, but for now the alternative of SetUsageTemplate is prohibitively complex

3. Do not use cobra.RangeArgs(1, 2) and similar, as their error messages are too generic e.g.:

   $ example clone foo bar baz
   Error: accepts between 1 and 2 arg(s), received 3
   $
   

   => Using a custom Args function lets you write much better messages. Or just move validation into your RunE function.

   EDIT: this is the only output with SilenceUsage: true; by default you'll also get a full UsageString() printed. That's too verbose for my taste (see also Usage() prints too much, how to get just one usage line? #1252), but if you like it, then cobra.RangeArgs and friends are probably fine for you.

I think cobra could do better on last part in future; it's pretty standard to at least print a "Usage: ..." line by default on wrong invocations.