Allow to provide examples of possible values when required option is not passed

[lcswillems]

Let's say that option --docker-image is required.

The user calls the command without specifying it. Commander.js will say that --docker-image must be provided. However, it might not be obvious for the user what is an example of value that would be accepted by this option.

Would there be a way to give examples of values for required options not passed?

[shadowspawn]

The default error handling shows the flags specified when the option was added. So there is a little information from the text for the option-value.

program.requiredOption('--docker-image <image-name>', 'choose docker image');

% node index.mjs       
error: required option '--docker-image <image-name>' not specified

[shadowspawn]

There isn't a way to attach custom error messages to a particular option.

You could manually override the error message by using a try/catch (and .exitOverride()), or by using .configureOutput() and overriding writeErr. In both cases you would need to inspect the error message string to see which option caused the error. I suspect this is more manual that you are interested in.

[lcswillems]

Thanks for the information! Indeed, seems quite cumbersome to do in that case

[shadowspawn]

Providing extra information for a particular type of error is easier than a custom error per option, like:

program
  .exitOverride()
  .requiredOption('--docker-image <image-name>', 'choose docker image');

try {
  program.parse();
} catch (err) {
  if (err.code === 'commander.missingMandatoryOptionValue') {
    process.stderr.write('Example values for --docker-image are foo, bar\n');
  }
  process.exitCode = 1;
}

% node custom.mjs
error: required option '--docker-image <image-name>' not specified
Example values for --docker-image are foo, bar

[lcswillems]

Interesting! 🙏 But what if I have multiple commands (in my case)?

[shadowspawn]

But what if I have multiple commands (in my case)?

Multiple commands with different required options? Hmmm...

Ok, I think you could override .exitOverride() on each command that has required options, and output an additional message in the callback. Reasonably tidy.

(Want to see an example of that?)

[shadowspawn]

An answer was provided, and no further activity in a month. Closing this as resolved.

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