Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Getting --help to print descriptions for arguments #571

Open
reallyroy opened this issue Nov 7, 2017 · 5 comments · May be fixed by #842
Open

Getting --help to print descriptions for arguments #571

reallyroy opened this issue Nov 7, 2017 · 5 comments · May be fixed by #842
Labels
area/lib Methods and functions that exist in the cobra library and consumed by users kind/feature A feature request for cobra; new or enhanced behavior

Comments

@reallyroy
Copy link

reallyroy commented Nov 7, 2017

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!

@n10v n10v added area/lib Methods and functions that exist in the cobra library and consumed by users kind/feature A feature request for cobra; new or enhanced behavior labels Nov 7, 2017
@n10v n10v added this to the 2.0.0 milestone Nov 7, 2017
@eine
Copy link

eine commented Mar 18, 2019

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, " ")

@umarcor umarcor linked a pull request Mar 20, 2019 that will close this issue
4 tasks
hilary pushed a commit to hilary/cobra that referenced this issue Oct 22, 2019
@github-actions
Copy link

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

@eine
Copy link

eine commented Apr 13, 2020

AFAIK, this is not supported yet.

@cben
Copy link

cben commented Oct 12, 2020

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.

cben added a commit to cben/ocm-cli that referenced this issue Oct 13, 2020
Chosen approach explained in spf13/cobra#571 (comment)

Didn't touch the generic REST commands such as `get`, `delete` etc
as I'm confused by them both using `urls.Expand()` to support
`get URL` & `get KIND ID` forms, as well as having some Cobra sub-commands.
@jharshman jharshman removed this from the 2.0.0 milestone Oct 14, 2020
@danielbraun89
Copy link

danielbraun89 commented Aug 20, 2023

This is such a basic behavior, it exists in every other arg parser in any language that I know of. It is baffling that args are treated as a second class citizens compared to flags. If anything it should be the other way around!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area/lib Methods and functions that exist in the cobra library and consumed by users kind/feature A feature request for cobra; new or enhanced behavior
Projects
None yet
Development

Successfully merging a pull request may close this issue.

6 participants