Updating console.error messages suggesting to clients run --help command

[GeorgeGkas]

I post a possible enchantment.

Description

One of the core features of commander.js is the ability to show meaningful error messages to the user. The API provides .on('--help', cb) listener on commands that allow users to add custom help messages (a description, examples, etc). However, to be able someone gets those help information he needs to provide --help argument in the command. For instance, if we have the following command node index.js rm <file> we are able to provide an .on('--help', cb) listener to command('rm <file>').

When new clients want to use our CLI tool will find themselves, most of the time, struggling to figure out how to use a command. For instance, if they forget the <file> argument in rm they'll face the following error message:

error: missing required argument `file'

Our client now needs to go to our API documentation and search what the <file> argument is (a path or name?). For simple commands, such as the above example, this isn't something interesting, but in more sophisticated commands, this actually can add headaches. Of course, the client can always add --help argument to that command and get the appropriate information. But most of the times, he will miss it.

Proposal Fix

I propose to update those error messages by adding one more line that will suggest our client try the --help argument. As such, the above message will be changed to:

error: missing required argument `file'
Try '--help' for more information.

This is something that most UNIX like commands do (check rm, cp, mv, etc) and I believe that increases the User Experience. Of course, we can propose other alternatives as well: Print the whole help page below the error message, but in my opinion, this is something that would add more noise.

A fix like this will not add any break changes to the codebase nor will decrease the test coverage.

If you agree with this idea, I will immediately open a new pull request.

[shazron]

I am interested in this as well. Please send that PR!

[GeorgeGkas]

I'll send the PR ASAP.

[shadowspawn]

For interest, I looked at the suggested unix commands and git and npm and found three behaviours:

• show usage (all the suggested unix commands, none of which have a built-in help)
• suggest --help
• default help

$ mv silly
usage: mv [-f | -i | -n] [-v] source target
       mv [-f | -i | -n] [-v] source ... directory
$ cp silly
usage: cp [-R [-H | -L | -P]] [-fi | -n] [-apvXc] source_file target_file
       cp [-R [-H | -L | -P]] [-fi | -n] [-apvXc] source_file ... target_directory
$ rm
usage: rm [-f | -i] [-dPRrvW] file ...
       unlink file
$ git silly
git: 'silly' is not a git command. See 'git --help'.
$ npm silly

Usage: npm <command>

where <command> is one of:
...
npm <command> -h  quick help on <command>
npm -l            display full usage info
npm help <term>   search for help on <term>
npm help npm      involved overview
...

[shadowspawn]

This issue has not had any activity in over six months. It isn't likely to get acted on due to this report.

Feel free to open a new issue if it comes up again, with new information and renewed interest.

Thank you for your contributions.

[shadowspawn]

Related: .showHelpAfterError() added in prerelease v8.0.0-2 by PR #1534