Main help output doesn't show custom usage of commands

[yume-chan]

Version: "commander": "^10.0.1",

There are several cases I'm using the .usage() option:

• When a command only has limited number of options, I want to display all of them in usage, instead of [options]

  program
      .command("devices")
      .usage("[-l]")
      .option("-l", "long output", false)

• When a command requires -- before arguments because otherwise commander parses them as options

  program
      .command("shell [args...]")
      .description(
          "run remote shell command (interactive shell if no command given). `--` is required before command name."
      )
      .usage("[options] [-- <args...>]")

It's working in each command's individual help message, like

> node .\esm\index.js help devices
Usage: tango-cli devices [-l]

Options:
  -l          long output (default: false)
  -h, --help  display help for command

But not in the main help

> node .\esm\index.js help
Usage: tango-cli [options] [command]

Options:
  -H <host>                  name of adb server host (default: "127.0.0.1")
  -P <port>                  port of adb server (default: 5037)
  -h, --help                 display help for command

Commands:
  devices [options]
  shell [options] [args...]  run remote shell command (interactive shell if no       
                             command given). `--` is required before command name.   
  help [command]             display help for command

In particular the second case might confuse the users if they don't know help [command] will display a different usage.

[shadowspawn]

There was a PR recently to show the custom usage in the list of subcommands (#1853). I was concerned the custom help might be long if displaying all the options, and not work well in the list of subcommands.

Interestingly, you qualified your description with "When a command only has limited number of options, I want to display all of them in usage, instead of [options]" so would probably work fine for you.

You can modify the behaviour yourself to use the custom usage by customising the help:
#1853 (comment)

[shadowspawn]

On a separate but related note, for your shell subcommand, you might be interested in .passThroughOptions() which is intended to simply this scenario and remove the need for the end user to use --. You would also need to .enablePositionalOptions() on the program, so it would change where the -H and -P can go on the command-line.

• https://github.com/tj/commander.js#parsing-configuration
• https://github.com/tj/commander.js/blob/master/examples/pass-through-options.js

[yume-chan]

Thank you! Now I'm adding usage to all commands and using subcommandTerm to customize the display.

I have read .passThroughOptions() before, but I don't want .enablePositionalOptions(). Command options shouldn't appear before the command name, but I think it should be fine to pass global options after command name.

EDIT: In my case there is no default command, so global options is more like common options among all commands, so it makes sense to allow them after command name.

[shadowspawn]

It does not require much code to customise the help to show custom usage, but you have to work out the code. e.g.

program.configureHelp({ subcommandTerm: (cmd) => cmd.name() + ' ' + cmd.usage() })

Is it worth supporting directly? Like say:

program.configureHelp({ subcommandStyle: 'usage' });

@yume-chan @hiimjustin000

Edit: I'll probably add some examples for now, and keep monitoring.

[shadowspawn]

Example added in Commander v11.1.0