commander 8.0.0-2 → 8.3.0

package/Readme.md

@@ -93,13 +93,13 @@ import { Command } from 'commander';
 const program = new Command();
 ```
 
-
 ## Options
 
 Options are defined with the `.option()` method, also serving as documentation for the options. Each option can have a short flag (single character) and a long name, separated by a comma or space or vertical bar ('|').
 
 The parsed options can be accessed by calling `.opts()` on a `Command` object, and are passed to the action handler.
-You can also use `.getOptionValue()` and `.setOptionValue()` to work with a single option value.
+(You can also use `.getOptionValue()` and `.setOptionValue()` to work with a single option value,
+and `.getOptionValueSource()` and `.setOptionValueWithSource()` when it matters where the option value came from.)
 
 Multi-word options such as "--template-engine" are camel-cased, becoming `program.opts().templateEngine` etc.
 
@@ -113,7 +113,7 @@ By default options on the command line are not positional, and can be specified
 ### Common option types, boolean and value
 
 The two most used option types are a boolean option, and an option which takes its value
-from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.  
+from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.
 
 Example file: [options-common.js](./examples/options-common.js)
 
@@ -308,13 +308,14 @@ program.version('0.0.1', '-v, --vers', 'output the current version');
 You can add most options using the `.option()` method, but there are some additional features available
 by constructing an `Option` explicitly for less common cases.
 
-Example file: [options-extra.js](./examples/options-extra.js)
+Example files: [options-extra.js](./examples/options-extra.js), [options-env.js](./examples/options-env.js)
 
 ```js
 program
   .addOption(new Option('-s, --secret').hideHelp())
   .addOption(new Option('-t, --timeout <delay>', 'timeout in seconds').default(60, 'one minute'))
-  .addOption(new Option('-d, --drink <size>', 'drink size').choices(['small', 'medium', 'large']));
+  .addOption(new Option('-d, --drink <size>', 'drink size').choices(['small', 'medium', 'large']))
+  .addOption(new Option('-p, --port <number>', 'port number').env('PORT'));
 ```
 
 ```bash
@@ -324,10 +325,14 @@ Usage: help [options]
 Options:
   -t, --timeout <delay>  timeout in seconds (default: one minute)
   -d, --drink <size>     drink cup size (choices: "small", "medium", "large")
+  -p, --port <number>    port number (env: PORT)
   -h, --help             display help for command
 
 $ extra --drink huge
 error: option '-d, --drink <size>' argument 'huge' is invalid. Allowed choices are small, medium, large.
+
+$ PORT=80 extra 
+Options:  { timeout: 60, port: '80' }
 ```
 
 ### Custom option processing
@@ -426,7 +431,7 @@ program
   .addCommand(build.makeBuildCommand());
 ```
 
-Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will 
+Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will
 remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other
 subcommand is specified ([example](./examples/defaultCommand.js)).
 
@@ -436,7 +441,7 @@ For subcommands, you can specify the argument syntax in the call to `.command()`
 is the only method usable for subcommands implemented using a stand-alone executable, but for other subcommands
 you can instead use the following method.
 
-To configure a command, you can use `.argument()` to specify each expected command-argument. 
+To configure a command, you can use `.argument()` to specify each expected command-argument.
 You supply the argument name and an optional description. The argument may be `<required>` or `[optional]`.
 You can specify a default value for an optional command-argument.
 
@@ -513,7 +518,7 @@ program
 ### Action handler
 
 The action handler gets passed a parameter for each command-argument you declared, and two additional parameters
-which are the parsed options and the command object itself. 
+which are the parsed options and the command object itself.
 
 Example file: [thank.js](./examples/thank.js)
 
@@ -630,7 +635,7 @@ shell spawn --help
 
 ### Custom help
 
-You can add extra text to be displayed along with the built-in help. 
+You can add extra text to be displayed along with the built-in help.
 
 Example file: [custom-help](./examples/custom-help)
 
@@ -664,7 +669,7 @@ The positions in order displayed are:
 - `after`: display extra information after built-in help
 - `afterAll`: add to the program for a global footer (epilog)
 
-The positions "beforeAll" and "afterAll" apply to the command and all its subcommands. 
+The positions "beforeAll" and "afterAll" apply to the command and all its subcommands.
 
 The second parameter can be a string, or a function returning a string. The function is passed a context object for your convenience. The properties are:
 
@@ -673,7 +678,7 @@ The second parameter can be a string, or a function returning a string. The func
 
 ### Display help after errors
 
-The default behaviour for usage errors is to just display a short error message. 
+The default behaviour for usage errors is to just display a short error message.
 You can change the behaviour to show the full help or a custom help message after an error.
 
 ```js
@@ -688,6 +693,18 @@ error: unknown option '--unknown'
 (add --help for additional information)
 ```
 
+You can also show suggestions after an error for an unknown command or option.
+
+```js
+program.showSuggestionAfterError();
+```
+
+```sh
+$ pizza --hepl
+error: unknown option '--hepl'
+(Did you mean --help?)
+```
+
 ### Display help from code
 
 `.help()`: display help information and exit immediately. You can optionally pass `{ error: true }` to display on stderr and exit with an error status.
@@ -747,7 +764,7 @@ There are methods getting the visible lists of arguments, options, and subcomman
 
 Example file: [configure-help.js](./examples/configure-help.js)
 
-```
+```js
 program.configureHelp({
   sortSubcommands: true,
   subcommandTerm: (cmd) => cmd.name() // Just show the name, instead of short usage.
@@ -762,13 +779,6 @@ You can execute custom actions by listening to command and option events.
 program.on('option:verbose', function () {
   process.env.VERBOSE = this.opts().verbose;
 });
-
-program.on('command:*', function (operands) {
-  console.error(`error: unknown command '${operands[0]}'`);
-  const availableCommands = program.commands.map(cmd => cmd.name());
-  mySuggestBestMatch(operands[0], availableCommands);
-  process.exitCode = 1;
-});
 ```
 
 ## Bits and pieces
@@ -809,7 +819,7 @@ program subcommand -b
 
 By default options are recognised before and after command-arguments. To only process options that come
 before the command-arguments, use `.passThroughOptions()`. This lets you pass the  arguments and following options through to another program
-without needing to use `--` to end the option processing. 
+without needing to use `--` to end the option processing.
 To use pass through options in a subcommand, the program needs to enable positional options.
 
 Example file: [pass-through-options.js](./examples/pass-through-options.js)
@@ -826,7 +836,7 @@ By default the option processing shows an error for an unknown option. To have a
 By default the argument processing does not display an error for more command-arguments than expected.
 To display an error for excess arguments, use`.allowExcessArguments(false)`.
 
-### Legacy options as properties 
+### Legacy options as properties
 
 Before Commander 7, the option values were stored as properties on the command.
 This was convenient to code but the downside was possible clashes with
@@ -903,7 +913,6 @@ You can modify this behaviour for custom applications. In addition, you can modi
 
 Example file: [configure-output.js](./examples/configure-output.js)
 
-
 ```js
 function errorColor(str) {
   // Add ANSI escape codes to display text in red.
@@ -986,7 +995,7 @@ Examples:
   $ deploy exec sequential
   $ deploy exec async`
   );
-  
+
 program.parse(process.argv);
 ```
 

package/lib/argument.js

@@ -109,6 +109,22 @@ class Argument {
     };
     return this;
   };
+
+  /**
+   * Make option-argument required.
+   */
+  argRequired() {
+    this.required = true;
+    return this;
+  }
+
+  /**
+   * Make option-argument optional.
+   */
+  argOptional() {
+    this.required = false;
+    return this;
+  }
 }
 
 /**

package/lib/command.js

@@ -7,6 +7,7 @@ const { Argument, humanReadableArgName } = require('./argument.js');
 const { CommanderError } = require('./error.js');
 const { Help } = require('./help.js');
 const { Option, splitOptionFlags } = require('./option.js');
+const { suggestSimilar } = require('./suggestSimilar');
 
 // @ts-check
 
@@ -35,6 +36,7 @@ class Command extends EventEmitter {
     this._scriptPath = null;
     this._name = name || '';
     this._optionValues = {};
+    this._optionValueSources = {}; // default < config < env < cli
     this._storeOptionsAsProperties = false;
     this._actionHandler = null;
     this._executableHandler = false;
@@ -50,6 +52,7 @@ class Command extends EventEmitter {
     this._lifeCycleHooks = {}; // a hash of arrays
     /** @type {boolean | string} */
     this._showHelpAfterError = false;
+    this._showSuggestionAfterError = false;
 
     // see .configureOutput() for docs
     this._outputConfiguration = {
@@ -74,24 +77,53 @@ class Command extends EventEmitter {
   }
 
   /**
-   * Define a command.
+   * Copy settings that are useful to have in common across root command and subcommands.
    *
-   * There are two styles of command: pay attention to where to put the description.
+   * (Used internally when adding a command using `.command()` so subcommands inherit parent settings.)
    *
-   * Examples:
+   * @param {Command} sourceCommand
+   * @return {Command} returns `this` for executable command
+   */
+  copyInheritedSettings(sourceCommand) {
+    this._outputConfiguration = sourceCommand._outputConfiguration;
+    this._hasHelpOption = sourceCommand._hasHelpOption;
+    this._helpFlags = sourceCommand._helpFlags;
+    this._helpDescription = sourceCommand._helpDescription;
+    this._helpShortFlag = sourceCommand._helpShortFlag;
+    this._helpLongFlag = sourceCommand._helpLongFlag;
+    this._helpCommandName = sourceCommand._helpCommandName;
+    this._helpCommandnameAndArgs = sourceCommand._helpCommandnameAndArgs;
+    this._helpCommandDescription = sourceCommand._helpCommandDescription;
+    this._helpConfiguration = sourceCommand._helpConfiguration;
+    this._exitCallback = sourceCommand._exitCallback;
+    this._storeOptionsAsProperties = sourceCommand._storeOptionsAsProperties;
+    this._combineFlagAndOptionalValue = sourceCommand._combineFlagAndOptionalValue;
+    this._allowExcessArguments = sourceCommand._allowExcessArguments;
+    this._enablePositionalOptions = sourceCommand._enablePositionalOptions;
+    this._showHelpAfterError = sourceCommand._showHelpAfterError;
+    this._showSuggestionAfterError = sourceCommand._showSuggestionAfterError;
+
+    return this;
+  }
+
+  /**
+   * Define a command.
    *
-   *      // Command implemented using action handler (description is supplied separately to `.command`)
-   *      program
-   *        .command('clone <source> [destination]')
-   *        .description('clone a repository into a newly created directory')
-   *        .action((source, destination) => {
-   *          console.log('clone command called');
-   *        });
+   * There are two styles of command: pay attention to where to put the description.
    *
-   *      // Command implemented using separate executable file (description is second parameter to `.command`)
-   *      program
-   *        .command('start <service>', 'start named service')
-   *        .command('stop [service]', 'stop named service, or all if no name supplied');
+   * @example
+   * // Command implemented using action handler (description is supplied separately to `.command`)
+   * program
+   *   .command('clone <source> [destination]')
+   *   .description('clone a repository into a newly created directory')
+   *   .action((source, destination) => {
+   *     console.log('clone command called');
+   *   });
+   *
+   * // Command implemented using separate executable file (description is second parameter to `.command`)
+   * program
+   *   .command('start <service>', 'start named service')
+   *   .command('stop [service]', 'stop named service, or all if no name supplied');
    *
    * @param {string} nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...`
    * @param {Object|string} [actionOptsOrExecDesc] - configuration options (for action), or description (for executable)
@@ -108,37 +140,19 @@ class Command extends EventEmitter {
     }
     opts = opts || {};
     const [, name, args] = nameAndArgs.match(/([^ ]+) *(.*)/);
-    const cmd = this.createCommand(name);
 
+    const cmd = this.createCommand(name);
     if (desc) {
       cmd.description(desc);
       cmd._executableHandler = true;
     }
     if (opts.isDefault) this._defaultCommandName = cmd._name;
-
-    cmd._outputConfiguration = this._outputConfiguration;
-
     cmd._hidden = !!(opts.noHelp || opts.hidden); // noHelp is deprecated old name for hidden
-    cmd._hasHelpOption = this._hasHelpOption;
-    cmd._helpFlags = this._helpFlags;
-    cmd._helpDescription = this._helpDescription;
-    cmd._helpShortFlag = this._helpShortFlag;
-    cmd._helpLongFlag = this._helpLongFlag;
-    cmd._helpCommandName = this._helpCommandName;
-    cmd._helpCommandnameAndArgs = this._helpCommandnameAndArgs;
-    cmd._helpCommandDescription = this._helpCommandDescription;
-    cmd._helpConfiguration = this._helpConfiguration;
-    cmd._exitCallback = this._exitCallback;
-    cmd._storeOptionsAsProperties = this._storeOptionsAsProperties;
-    cmd._combineFlagAndOptionalValue = this._combineFlagAndOptionalValue;
-    cmd._allowExcessArguments = this._allowExcessArguments;
-    cmd._enablePositionalOptions = this._enablePositionalOptions;
-    cmd._showHelpAfterError = this._showHelpAfterError;
-
     cmd._executableFile = opts.executableFile || null; // Custom name for executable file, set missing to null to match constructor
     if (args) cmd.arguments(args);
     this.commands.push(cmd);
     cmd.parent = this;
+    cmd.copyInheritedSettings(this);
 
     if (desc) return this;
     return cmd;
@@ -190,14 +204,14 @@ class Command extends EventEmitter {
    *
    * The configuration properties are all functions:
    *
-   *    // functions to change where being written, stdout and stderr
-   *    writeOut(str)
-   *    writeErr(str)
-   *    // matching functions to specify width for wrapping help
-   *    getOutHelpWidth()
-   *    getErrHelpWidth()
-   *    // functions based on what is being written out
-   *    outputError(str, write) // used for displaying errors, and not used for displaying help
+   *     // functions to change where being written, stdout and stderr
+   *     writeOut(str)
+   *     writeErr(str)
+   *     // matching functions to specify width for wrapping help
+   *     getOutHelpWidth()
+   *     getErrHelpWidth()
+   *     // functions based on what is being written out
+   *     outputError(str, write) // used for displaying errors, and not used for displaying help
    *
    * @param {Object} [configuration] - configuration options
    * @return {Command|Object} `this` command for chaining, or stored configuration
@@ -222,6 +236,17 @@ class Command extends EventEmitter {
     return this;
   }
 
+  /**
+   * Display suggestion of similar commands for unknown commands, or options for unknown options.
+   *
+   * @param {boolean} [displaySuggestion]
+   * @return {Command} `this` command for chaining
+   */
+  showSuggestionAfterError(displaySuggestion = true) {
+    this._showSuggestionAfterError = !!displaySuggestion;
+    return this;
+  }
+
   /**
    * Add a prepared subcommand.
    *
@@ -278,9 +303,8 @@ class Command extends EventEmitter {
    * indicate this with <> around the name. Put [] around the name for an optional argument.
    *
    * @example
-   *
-   *     program.argument('<input-file>');
-   *     program.argument('[output-file]');
+   * program.argument('<input-file>');
+   * program.argument('[output-file]');
    *
    * @param {string} name
    * @param {string} [description]
@@ -305,8 +329,7 @@ class Command extends EventEmitter {
    * See also .argument().
    *
    * @example
-   *
-   *     program.arguments('<cmd> [env]');
+   * program.arguments('<cmd> [env]');
    *
    * @param {string} names
    * @return {Command} `this` command for chaining
@@ -438,14 +461,13 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Register callback `fn` for the command.
    *
-   * Examples:
-   *
-   *      program
-   *        .command('help')
-   *        .description('display verbose help')
-   *        .action(function() {
-   *           // output help here
-   *        });
+   * @example
+   * program
+   *   .command('serve')
+   *   .description('start service')
+   *   .action(function() {
+   *      // do work here
+   *   });
    *
    * @param {Function} fn
    * @return {Command} `this` command for chaining
@@ -505,16 +527,16 @@ Expecting one of '${allowedValues.join("', '")}'`);
       }
       // preassign only if we have a default
       if (defaultValue !== undefined) {
-        this.setOptionValue(name, defaultValue);
+        this.setOptionValueWithSource(name, defaultValue, 'default');
       }
     }
 
     // register the option
     this.options.push(option);
 
-    // when it's passed assign the value
-    // and conditionally invoke the callback
-    this.on('option:' + oname, (val) => {
+    // handler for cli and env supplied values
+    const handleOptionValue = (val, invalidValueMessage, valueSource) => {
+      // Note: using closure to access lots of lexical scoped variables.
       const oldValue = this.getOptionValue(name);
 
       // custom processing
@@ -523,7 +545,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           val = option.parseArg(val, oldValue === undefined ? defaultValue : oldValue);
         } catch (err) {
           if (err.code === 'commander.invalidArgument') {
-            const message = `error: option '${option.flags}' argument '${val}' is invalid. ${err.message}`;
+            const message = `${invalidValueMessage} ${err.message}`;
             this._displayError(err.exitCode, err.code, message);
           }
           throw err;
@@ -536,18 +558,28 @@ Expecting one of '${allowedValues.join("', '")}'`);
       if (typeof oldValue === 'boolean' || typeof oldValue === 'undefined') {
         // if no value, negate false, and we have a default, then use it!
         if (val == null) {
-          this.setOptionValue(name, option.negate
-            ? false
-            : defaultValue || true);
+          this.setOptionValueWithSource(name, option.negate ? false : defaultValue || true, valueSource);
         } else {
-          this.setOptionValue(name, val);
+          this.setOptionValueWithSource(name, val, valueSource);
         }
       } else if (val !== null) {
         // reassign
-        this.setOptionValue(name, option.negate ? false : val);
+        this.setOptionValueWithSource(name, option.negate ? false : val, valueSource);
       }
+    };
+
+    this.on('option:' + oname, (val) => {
+      const invalidValueMessage = `error: option '${option.flags}' argument '${val}' is invalid.`;
+      handleOptionValue(val, invalidValueMessage, 'cli');
     });
 
+    if (option.envVar) {
+      this.on('optionEnv:' + oname, (val) => {
+        const invalidValueMessage = `error: option '${option.flags}' value '${val}' from env '${option.envVar}' is invalid.`;
+        handleOptionValue(val, invalidValueMessage, 'env');
+      });
+    }
+
     return this;
   }
 
@@ -584,41 +616,40 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * separated by comma, a pipe or space. The following are all valid
    * all will output this way when `--help` is used.
    *
-   *    "-p, --pepper"
-   *    "-p|--pepper"
-   *    "-p --pepper"
+   *     "-p, --pepper"
+   *     "-p|--pepper"
+   *     "-p --pepper"
    *
-   * Examples:
-   *
-   *     // simple boolean defaulting to undefined
-   *     program.option('-p, --pepper', 'add pepper');
+   * @example
+   * // simple boolean defaulting to undefined
+   * program.option('-p, --pepper', 'add pepper');
    *
-   *     program.pepper
-   *     // => undefined
+   * program.pepper
+   * // => undefined
    *
-   *     --pepper
-   *     program.pepper
-   *     // => true
+   * --pepper
+   * program.pepper
+   * // => true
    *
-   *     // simple boolean defaulting to true (unless non-negated option is also defined)
-   *     program.option('-C, --no-cheese', 'remove cheese');
+   * // simple boolean defaulting to true (unless non-negated option is also defined)
+   * program.option('-C, --no-cheese', 'remove cheese');
    *
-   *     program.cheese
-   *     // => true
+   * program.cheese
+   * // => true
    *
-   *     --no-cheese
-   *     program.cheese
-   *     // => false
+   * --no-cheese
+   * program.cheese
+   * // => false
    *
-   *     // required argument
-   *     program.option('-C, --chdir <path>', 'change the working directory');
+   * // required argument
+   * program.option('-C, --chdir <path>', 'change the working directory');
    *
-   *     --chdir /tmp
-   *     program.chdir
-   *     // => "/tmp"
+   * --chdir /tmp
+   * program.chdir
+   * // => "/tmp"
    *
-   *     // optional argument
-   *     program.option('-c, --cheese [type]', 'add cheese [marble]');
+   * // optional argument
+   * program.option('-c, --cheese [type]', 'add cheese [marble]');
    *
    * @param {string} flags
    * @param {string} [description]
@@ -651,11 +682,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
   /**
    * Alter parsing of short flags with optional values.
    *
-   * Examples:
-   *
-   *    // for `.option('-f,--flag [value]'):
-   *    .combineFlagAndOptionalValue(true)  // `-f80` is treated like `--flag=80`, this is the default behaviour
-   *    .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
+   * @example
+   * // for `.option('-f,--flag [value]'):
+   * program.combineFlagAndOptionalValue(true);  // `-f80` is treated like `--flag=80`, this is the default behaviour
+   * program.combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
    *
    * @param {Boolean} [combine=true] - if `true` or omitted, an optional value can be specified directly after the flag.
    */
@@ -762,6 +792,33 @@ Expecting one of '${allowedValues.join("', '")}'`);
     return this;
   };
 
+  /**
+   * Store option value and where the value came from.
+    *
+    * @param {string} key
+    * @param {Object} value
+    * @param {string} source - expected values are default/config/env/cli
+    * @return {Command} `this` command for chaining
+    */
+
+  setOptionValueWithSource(key, value, source) {
+    this.setOptionValue(key, value);
+    this._optionValueSources[key] = source;
+    return this;
+  }
+
+  /**
+    * Get source of option value.
+    * Expected values are default | config | env | cli
+    *
+    * @param {string} key
+    * @return {string}
+    */
+
+  getOptionValueSource(key) {
+    return this._optionValueSources[key];
+  };
+
   /**
    * Get user arguments implied or explicit arguments.
    * Side-effects: set _scriptPath if args included application, and use that to set implicit command name.
@@ -824,11 +881,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * The default expectation is that the arguments are from node and have the application as argv[0]
    * and the script being run in argv[1], with user parameters after that.
    *
-   * Examples:
-   *
-   *      program.parse(process.argv);
-   *      program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
-   *      program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * @example
+   * program.parse(process.argv);
+   * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
+   * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
    *
    * @param {string[]} [argv] - optional, defaults to process.argv
    * @param {Object} [parseOptions] - optionally specify style of options with from: node/user/electron
@@ -851,11 +907,10 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * The default expectation is that the arguments are from node and have the application as argv[0]
    * and the script being run in argv[1], with user parameters after that.
    *
-   * Examples:
-   *
-   *      await program.parseAsync(process.argv);
-   *      await program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
-   *      await program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * @example
+   * await program.parseAsync(process.argv);
+   * await program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
+   * await program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
    *
    * @param {string[]} [argv]
    * @param {Object} [parseOptions]
@@ -1076,6 +1131,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @param {Promise|undefined} promise
    * @param {Function} fn
    * @return {Promise|undefined}
+   * @api private
    */
 
   _chainOrCall(promise, fn) {
@@ -1128,6 +1184,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   _parseCommand(operands, unknown) {
     const parsed = this.parseOptions(unknown);
+    this._parseOptionsEnv(); // after cli, so parseArg not called on both cli and env
     operands = operands.concat(parsed.operands);
     unknown = parsed.unknown;
     this.args = operands.concat(unknown);
@@ -1190,6 +1247,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._processArguments();
       }
     } else if (this.commands.length) {
+      checkForUnknownOptions();
       // This command has subcommands and nothing hooked up at this level, so display help (and exit).
       this.help({ error: true });
     } else {
@@ -1245,11 +1303,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
    *
    * Examples:
    *
-   *    argv => operands, unknown
-   *    --known kkk op => [op], []
-   *    op --known kkk => [op], []
-   *    sub --unknown uuu op => [sub], [--unknown uuu op]
-   *    sub -- --unknown uuu op => [sub --unknown uuu op], []
+   *     argv => operands, unknown
+   *     --known kkk op => [op], []
+   *     op --known kkk => [op], []
+   *     sub --unknown uuu op => [sub], [--unknown uuu op]
+   *     sub -- --unknown uuu op => [sub --unknown uuu op], []
    *
    * @param {String[]} argv
    * @return {{operands: String[], unknown: String[]}}
@@ -1408,6 +1466,30 @@ Expecting one of '${allowedValues.join("', '")}'`);
     this._exit(exitCode, code, message);
   }
 
+  /**
+   * Apply any option related environment variables, if option does
+   * not have a value from cli or client code.
+   *
+   * @api private
+   */
+  _parseOptionsEnv() {
+    this.options.forEach((option) => {
+      if (option.envVar && option.envVar in process.env) {
+        const optionKey = option.attributeName();
+        // Priority check. Do not overwrite cli or options from unknown source (client-code).
+        if (this.getOptionValue(optionKey) === undefined || ['default', 'config', 'env'].includes(this.getOptionValueSource(optionKey))) {
+          if (option.required || option.optional) { // option can take a value
+            // keep very simple, optional always takes value
+            this.emit(`optionEnv:${option.name()}`, process.env[option.envVar]);
+          } else { // boolean
+            // keep very simple, only care that envVar defined and not the value
+            this.emit(`optionEnv:${option.name()}`);
+          }
+        }
+      }
+    });
+  }
+
   /**
    * Argument `name` is missing.
    *
@@ -1453,7 +1535,23 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
   unknownOption(flag) {
     if (this._allowUnknownOption) return;
-    const message = `error: unknown option '${flag}'`;
+    let suggestion = '';
+
+    if (flag.startsWith('--') && this._showSuggestionAfterError) {
+      // Looping to pick up the global options too
+      let candidateFlags = [];
+      let command = this;
+      do {
+        const moreFlags = command.createHelp().visibleOptions(command)
+          .filter(option => option.long)
+          .map(option => option.long);
+        candidateFlags = candidateFlags.concat(moreFlags);
+        command = command.parent;
+      } while (command && !command._enablePositionalOptions);
+      suggestion = suggestSimilar(flag, candidateFlags);
+    }
+
+    const message = `error: unknown option '${flag}'${suggestion}`;
     this._displayError(1, 'commander.unknownOption', message);
   };
 
@@ -1481,7 +1579,20 @@ Expecting one of '${allowedValues.join("', '")}'`);
    */
 
   unknownCommand() {
-    const message = `error: unknown command '${this.args[0]}'`;
+    const unknownName = this.args[0];
+    let suggestion = '';
+
+    if (this._showSuggestionAfterError) {
+      const candidateNames = [];
+      this.createHelp().visibleCommands(this).forEach((command) => {
+        candidateNames.push(command.name());
+        // just visible alias
+        if (command.alias()) candidateNames.push(command.alias());
+      });
+      suggestion = suggestSimilar(unknownName, candidateNames);
+    }
+
+    const message = `error: unknown command '${unknownName}'${suggestion}`;
     this._displayError(1, 'commander.unknownCommand', message);
   };
 
@@ -1659,14 +1770,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
     }
     const context = this._getHelpContext(contextOptions);
 
-    const groupListeners = [];
-    let command = this;
-    while (command) {
-      groupListeners.push(command); // ordered from current command to root
-      command = command.parent;
-    }
-
-    groupListeners.slice().reverse().forEach(command => command.emit('beforeAllHelp', context));
+    getCommandAndParents(this).reverse().forEach(command => command.emit('beforeAllHelp', context));
     this.emit('beforeHelp', context);
 
     let helpInformation = this.helpInformation(context);
@@ -1680,7 +1784,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
 
     this.emit(this._helpLongFlag); // deprecated
     this.emit('afterHelp', context);
-    groupListeners.forEach(command => command.emit('afterAllHelp', context));
+    getCommandAndParents(this).forEach(command => command.emit('afterAllHelp', context));
   };
 
   /**

package/lib/help.js

@@ -234,21 +234,24 @@ class Help {
    */
 
   optionDescription(option) {
-    if (option.negate) {
-      return option.description;
-    }
     const extraInfo = [];
-    if (option.argChoices) {
+    // Some of these do not make sense for negated boolean and suppress for backwards compatibility.
+
+    if (option.argChoices && !option.negate) {
       extraInfo.push(
         // use stringify to match the display of the default value
         `choices: ${option.argChoices.map((choice) => JSON.stringify(choice)).join(', ')}`);
     }
-    if (option.defaultValue !== undefined) {
+    if (option.defaultValue !== undefined && !option.negate) {
       extraInfo.push(`default: ${option.defaultValueDescription || JSON.stringify(option.defaultValue)}`);
     }
+    if (option.envVar !== undefined) {
+      extraInfo.push(`env: ${option.envVar}`);
+    }
     if (extraInfo.length > 0) {
       return `${option.description} (${extraInfo.join(', ')})`;
     }
+
     return option.description;
   };
 

package/lib/option.js

@@ -28,6 +28,7 @@ class Option {
     }
     this.defaultValue = undefined;
     this.defaultValueDescription = undefined;
+    this.envVar = undefined;
     this.parseArg = undefined;
     this.hidden = false;
     this.argChoices = undefined;
@@ -47,6 +48,19 @@ class Option {
     return this;
   };
 
+  /**
+   * Set environment variable to check for option value.
+   * Priority order of option values is default < env < cli
+   *
+   * @param {string} name
+   * @return {Option}
+   */
+
+  env(name) {
+    this.envVar = name;
+    return this;
+  };
+
   /**
    * Set the custom handler for processing CLI option arguments into option values.
    *

package/lib/suggestSimilar.js

@@ -0,0 +1,100 @@
+const maxDistance = 3;
+
+function editDistance(a, b) {
+  // https://en.wikipedia.org/wiki/Damerau–Levenshtein_distance
+  // Calculating optimal string alignment distance, no substring is edited more than once.
+  // (Simple implementation.)
+
+  // Quick early exit, return worst case.
+  if (Math.abs(a.length - b.length) > maxDistance) return Math.max(a.length, b.length);
+
+  // distance between prefix substrings of a and b
+  const d = [];
+
+  // pure deletions turn a into empty string
+  for (let i = 0; i <= a.length; i++) {
+    d[i] = [i];
+  }
+  // pure insertions turn empty string into b
+  for (let j = 0; j <= b.length; j++) {
+    d[0][j] = j;
+  }
+
+  // fill matrix
+  for (let j = 1; j <= b.length; j++) {
+    for (let i = 1; i <= a.length; i++) {
+      let cost = 1;
+      if (a[i - 1] === b[j - 1]) {
+        cost = 0;
+      } else {
+        cost = 1;
+      }
+      d[i][j] = Math.min(
+        d[i - 1][j] + 1, // deletion
+        d[i][j - 1] + 1, // insertion
+        d[i - 1][j - 1] + cost // substitution
+      );
+      // transposition
+      if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+        d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+      }
+    }
+  }
+
+  return d[a.length][b.length];
+}
+
+/**
+ * Find close matches, restricted to same number of edits.
+ *
+ * @param {string} word
+ * @param {string[]} candidates
+ * @returns {string}
+ */
+
+function suggestSimilar(word, candidates) {
+  if (!candidates || candidates.length === 0) return '';
+  // remove possible duplicates
+  candidates = Array.from(new Set(candidates));
+
+  const searchingOptions = word.startsWith('--');
+  if (searchingOptions) {
+    word = word.slice(2);
+    candidates = candidates.map(candidate => candidate.slice(2));
+  }
+
+  let similar = [];
+  let bestDistance = maxDistance;
+  const minSimilarity = 0.4;
+  candidates.forEach((candidate) => {
+    if (candidate.length <= 1) return; // no one character guesses
+
+    const distance = editDistance(word, candidate);
+    const length = Math.max(word.length, candidate.length);
+    const similarity = (length - distance) / length;
+    if (similarity > minSimilarity) {
+      if (distance < bestDistance) {
+        // better edit distance, throw away previous worse matches
+        bestDistance = distance;
+        similar = [candidate];
+      } else if (distance === bestDistance) {
+        similar.push(candidate);
+      }
+    }
+  });
+
+  similar.sort((a, b) => a.localeCompare(b));
+  if (searchingOptions) {
+    similar = similar.map(candidate => `--${candidate}`);
+  }
+
+  if (similar.length > 1) {
+    return `\n(Did you mean one of ${similar.join(', ')}?)`;
+  }
+  if (similar.length === 1) {
+    return `\n(Did you mean ${similar[0]}?)`;
+  }
+  return '';
+}
+
+exports.suggestSimilar = suggestSimilar;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "8.0.0-2",
+  "version": "8.3.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -39,17 +39,17 @@
   "dependencies": {},
   "devDependencies": {
     "@types/jest": "^26.0.23",
-    "@types/node": "^14.17.1",
-    "@typescript-eslint/eslint-plugin": "^4.25.0",
-    "@typescript-eslint/parser": "^4.25.0",
-    "eslint": "^7.27.0",
+    "@types/node": "^14.17.3",
+    "@typescript-eslint/eslint-plugin": "^4.27.0",
+    "@typescript-eslint/parser": "^4.27.0",
+    "eslint": "^7.29.0",
     "eslint-config-standard": "^16.0.3",
     "eslint-plugin-jest": "^24.3.6",
-    "jest": "^27.0.1",
+    "jest": "^27.0.4",
     "standard": "^16.0.3",
-    "ts-jest": "^27.0.1",
-    "tsd": "^0.16.0",
-    "typescript": "^4.3.2"
+    "ts-jest": "^27.0.3",
+    "tsd": "^0.17.0",
+    "typescript": "^4.3.4"
   },
   "types": "typings/index.d.ts",
   "jest": {

package/typings/index.d.ts

@@ -13,9 +13,9 @@ export class CommanderError extends Error {
 
   /**
    * Constructs the CommanderError class
-   * @param {number} exitCode suggested exit code which could be used with process.exit
-   * @param {string} code an id string representing the error
-   * @param {string} message human-readable description of the error
+   * @param exitCode - suggested exit code which could be used with process.exit
+   * @param code - an id string representing the error
+   * @param message - human-readable description of the error
    * @constructor
    */
   constructor(exitCode: number, code: string, message: string);
@@ -24,7 +24,7 @@ export class CommanderError extends Error {
 export class InvalidArgumentError extends CommanderError {
   /**
    * Constructs the InvalidArgumentError class
-   * @param {string} [message] explanation of why argument is invalid
+   * @param message - explanation of why argument is invalid
    * @constructor
    */
   constructor(message: string);
@@ -40,32 +40,38 @@ export class Argument {
    * Initialize a new command argument with the given name and description.
    * The default is that the argument is required, and you can explicitly
    * indicate this with <> around the name. Put [] around the name for an optional argument.
-   *
-   * @param {string} name
-   * @param {string} [description]
    */
   constructor(arg: string, description?: string);
 
   /**
-  * Return argument name.
-  */
+   * Return argument name.
+   */
   name(): string;
 
   /**
    * Set the default value, and optionally supply the description to be displayed in the help.
    */
-   default(value: unknown, description?: string): this;
+  default(value: unknown, description?: string): this;
 
   /**
    * Set the custom handler for processing CLI command arguments into argument values.
    */
-   argParser<T>(fn: (value: string, previous: T) => T): this;
+  argParser<T>(fn: (value: string, previous: T) => T): this;
 
   /**
    * Only allow argument value to be one of choices.
    */
-   choices(values: string[]): this;
+  choices(values: string[]): this;
+
+  /**
+   * Make option-argument required.
+   */
+  argRequired(): this;
 
+  /**
+   * Make option-argument optional.
+   */
+  argOptional(): this;
   }
 
 export class Option {
@@ -93,6 +99,12 @@ export class Option {
    */
   default(value: unknown, description?: string): this;
 
+  /**
+   * Set environment variable to check for option value.
+   * Priority order of option values is default < env < cli
+   */
+  env(name: string): this;
+
   /**
    * Calculate the full description, including defaultValue etc.
    */
@@ -113,12 +125,6 @@ export class Option {
    */
   hideHelp(hide?: boolean): this;
 
-  /**
-   * Validation of option argument failed.
-   * Intended for use from custom argument processing functions.
-   */
-  argumentRejected(messsage: string): never;
-
   /**
    * Only allow option value to be one of choices.
    */
@@ -208,8 +214,9 @@ export interface OutputConfiguration {
 
 }
 
-type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
-type HookEvent = 'preAction' | 'postAction';
+export type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
+export type HookEvent = 'preAction' | 'postAction';
+export type OptionValueSource = 'default' | 'env' | 'config' | 'cli';
 
 export interface OptionValues {
   [key: string]: any;
@@ -241,12 +248,12 @@ export class Command {
    *
    * @example
    * ```ts
-   *  program
-   *    .command('clone <source> [destination]')
-   *    .description('clone a repository into a newly created directory')
-   *    .action((source, destination) => {
-   *      console.log('clone command called');
-   *    });
+   * program
+   *   .command('clone <source> [destination]')
+   *   .description('clone a repository into a newly created directory')
+   *   .action((source, destination) => {
+   *     console.log('clone command called');
+   *   });
    * ```
    *
    * @param nameAndArgs - command name and arguments, args are  `<required>` or `[optional]` and last may also be `variadic...`
@@ -306,9 +313,10 @@ export class Command {
    * indicate this with <> around the name. Put [] around the name for an optional argument.
    *
    * @example
-   *
-   *     program.argument('<input-file>');
-   *     program.argument('[output-file]');
+   * ```
+   * program.argument('<input-file>');
+   * program.argument('[output-file]');
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -328,8 +336,9 @@ export class Command {
    * See also .argument().
    *
    * @example
-   *
-   *     program.arguments('<cmd> [env]');
+   * ```
+   * program.arguments('<cmd> [env]');
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -338,9 +347,12 @@ export class Command {
   /**
    * Override default decision whether to add implicit help command.
    *
-   *    addHelpCommand() // force on
-   *    addHelpCommand(false); // force off
-   *    addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details
+   * @example
+   * ```
+   * addHelpCommand() // force on
+   * addHelpCommand(false); // force off
+   * addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -375,35 +387,50 @@ export class Command {
    * applications. You can also customise the display of errors by overriding outputError.
    *
    * The configuration properties are all functions:
-   *
-   *    // functions to change where being written, stdout and stderr
-   *    writeOut(str)
-   *    writeErr(str)
-   *    // matching functions to specify width for wrapping help
-   *    getOutHelpWidth()
-   *    getErrHelpWidth()
-   *    // functions based on what is being written out
-   *    outputError(str, write) // used for displaying errors, and not used for displaying help
+   * ```
+   * // functions to change where being written, stdout and stderr
+   * writeOut(str)
+   * writeErr(str)
+   * // matching functions to specify width for wrapping help
+   * getOutHelpWidth()
+   * getErrHelpWidth()
+   * // functions based on what is being written out
+   * outputError(str, write) // used for displaying errors, and not used for displaying help
+   * ```
    */
   configureOutput(configuration: OutputConfiguration): this;
   /** Get configuration */
   configureOutput(): OutputConfiguration;
 
+  /**
+   * Copy settings that are useful to have in common across root command and subcommands.
+   *
+   * (Used internally when adding a command using `.command()` so subcommands inherit parent settings.)
+   */
+  copyInheritedSettings(sourceCommand: Command): this;
+
   /**
    * Display the help or a custom message after an error occurs.
    */
   showHelpAfterError(displayHelp?: boolean | string): this;
 
   /**
+   * Display suggestion of similar commands for unknown commands, or options for unknown options.
+   */
+  showSuggestionAfterError(displaySuggestion?: boolean): this;
+
+   /**
    * Register callback `fn` for the command.
    *
    * @example
-   *      program
-   *        .command('help')
-   *        .description('display verbose help')
-   *        .action(function() {
-   *           // output help here
-   *        });
+   * ```
+   * program
+   *   .command('serve')
+   *   .description('start service')
+   *   .action(function() {
+   *     // do work here
+   *   });
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -417,37 +444,39 @@ export class Command {
    * separated by comma, a pipe or space. The following are all valid
    * all will output this way when `--help` is used.
    *
-   *    "-p, --pepper"
-   *    "-p|--pepper"
-   *    "-p --pepper"
+   *     "-p, --pepper"
+   *     "-p|--pepper"
+   *     "-p --pepper"
    *
    * @example
-   *     // simple boolean defaulting to false
-   *     program.option('-p, --pepper', 'add pepper');
+   * ```
+   * // simple boolean defaulting to false
+   *  program.option('-p, --pepper', 'add pepper');
    *
-   *     --pepper
-   *     program.pepper
-   *     // => Boolean
+   *  --pepper
+   *  program.pepper
+   *  // => Boolean
    *
-   *     // simple boolean defaulting to true
-   *     program.option('-C, --no-cheese', 'remove cheese');
+   *  // simple boolean defaulting to true
+   *  program.option('-C, --no-cheese', 'remove cheese');
    *
-   *     program.cheese
-   *     // => true
+   *  program.cheese
+   *  // => true
    *
-   *     --no-cheese
-   *     program.cheese
-   *     // => false
+   *  --no-cheese
+   *  program.cheese
+   *  // => false
    *
-   *     // required argument
-   *     program.option('-C, --chdir <path>', 'change the working directory');
+   *  // required argument
+   *  program.option('-C, --chdir <path>', 'change the working directory');
    *
-   *     --chdir /tmp
-   *     program.chdir
-   *     // => "/tmp"
+   *  --chdir /tmp
+   *  program.chdir
+   *  // => "/tmp"
    *
-   *     // optional argument
-   *     program.option('-c, --cheese [type]', 'add cheese [marble]');
+   *  // optional argument
+   *  program.option('-c, --cheese [type]', 'add cheese [marble]');
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -498,18 +527,30 @@ export class Command {
    */
   getOptionValue(key: string): any;
 
-   /**
+  /**
    * Store option value.
    */
   setOptionValue(key: string, value: unknown): this;
 
   /**
+   * Store option value and where the value came from.
+   */
+  setOptionValueWithSource(key: string, value: unknown, source: OptionValueSource): this;
+
+  /**
+   * Retrieve option value source.
+   */
+  getOptionValueSource(key: string): OptionValueSource;
+
+   /**
    * Alter parsing of short flags with optional values.
    *
    * @example
-   *    // for `.option('-f,--flag [value]'):
-   *   .combineFlagAndOptionalValue(true)  // `-f80` is treated like `--flag=80`, this is the default behaviour
-   *   .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
+   * ```
+   * // for `.option('-f,--flag [value]'):
+   * .combineFlagAndOptionalValue(true)  // `-f80` is treated like `--flag=80`, this is the default behaviour
+   * .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -556,11 +597,12 @@ export class Command {
    * The default expectation is that the arguments are from node and have the application as argv[0]
    * and the script being run in argv[1], with user parameters after that.
    *
-   * Examples:
-   *
-   *      program.parse(process.argv);
-   *      program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
-   *      program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * @example
+   * ```
+   * program.parse(process.argv);
+   * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions
+   * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * ```
    *
    * @returns `this` command for chaining
    */
@@ -574,11 +616,12 @@ export class Command {
    * The default expectation is that the arguments are from node and have the application as argv[0]
    * and the script being run in argv[1], with user parameters after that.
    *
-   * Examples:
-   *
-   *      program.parseAsync(process.argv);
-   *      program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
-   *      program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * @example
+   * ```
+   * program.parseAsync(process.argv);
+   * program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions
+   * program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * ```
    *
    * @returns Promise
    */
@@ -588,12 +631,11 @@ export class Command {
    * Parse options from `argv` removing known options,
    * and return argv split into operands and unknown arguments.
    *
-   * @example
-   *    argv => operands, unknown
-   *    --known kkk op => [op], []
-   *    op --known kkk => [op], []
-   *    sub --unknown uuu op => [sub], [--unknown uuu op]
-   *    sub -- --unknown uuu op => [sub --unknown uuu op], []
+   *     argv => operands, unknown
+   *     --known kkk op => [op], []
+   *     op --known kkk => [op], []
+   *     sub --unknown uuu op => [sub], [--unknown uuu op]
+   *     sub -- --unknown uuu op => [sub --unknown uuu op], []
    */
   parseOptions(argv: string[]): ParseOptionsResult;