Additional custom sections for organizing flags in help text

[divyenduz]

Is your feature request related to a problem? Please describe.
I am writing a CLI with 6 global flags. This works well as I can just create an object and share it in commands. However, this makes the generated help section difficult to read.

Describe the solution you'd like
Is it possible to split the flags into global flags and command specific flags? Then in help show only the command flags under FLAGS heading and add a new heading "GLOBAL FLAGS" for other flags.

[molisani]

Apologies, this issue slipped under my radar until now. I think I have a "workaround" that might work for you, but then if that doesn't work I could imagine a feature proposal that might make sense instead.

What kind of flags are these global flags? If they're optional then you could consider making them hidden so that they don't show up for run cmd --help but do show up for run cmd --helpAll.

Beyond that, I could imagine a "section" feature for flags where an additional property on the flag specification indicates that it should be printed under a separate section. I'm not exactly sure what the API for that would look like, but that would allow for the best-case solution that you've described. It would be worth some exploration, if the "hidden" option wouldn't work well for you.

[divyenduz]

All of these flags are optional, however, I would still like the users of the CLI to know that they exist. In fact, I am currently using onlyRequiredInUsageLine: true as the workaround to hide them. But then the CLI user won't know that they are available. I am afraid a separate section is what I need. Maybe it doesn't need to be a custom section (undefined) but we can have something like marking a flag as global (common in CLIs) and that shows up in its own hardcoded GLOBAL FLAGS section?

[molisani]

Understood, if all of these flags are optional then they definitely need to appear in the default help text. However, I think custom sections would be a much more powerful way of addressing this issue, rather than only supporting a new "global" section. For example, imagine that you had a set of flags that weren't global to all commands but only to a set of commands in a sub-route. It might make sense to display them in their own section, but the section name "GLOBAL FLAGS" would no longer apply.

What would you think about an API similar to this one?

    flags: {
        foo: {
            ...
        },
        bar: {
            ...
            section: "GLOBAL"
        },
        baz: {
            ...
            section: "PROJECT"
        },
    },

FLAGS
  --foo   Some brief about the foo flag

GLOBAL FLAGS
  --bar   Some brief about the bar flag

PROJECT FLAGS
  --baz   Some brief about the baz flag

We would need to make some consideration for the i18n interface, but this shouldn't be too hard to implement.

[divyenduz]

Section API is indeed more powerful and the example you suggested would work pretty well for me ✅