Command

Kind: Class

Source: lib/command.js

Command represents a CLI command and manages its child-command hierarchy, inherited settings, help output, and error behavior. It creates commands and help instances, applies output configuration, and controls help or suggestion display after errors.

Extends: EventEmitter

Methods

Where it refuses work

• Command stops the work with Error when !cmd._name.
• Command stops the work with Error when previousArgument?.variadic.
• Command stops the work with Error when argument.required && argument.defaultValue !== undefined && argument.parseArg === undefin….
• Command stops the work with Error when !allowedValues.includes(event).
• Command stops the work with Error when typeof flags === 'object' && flags instanceof Option — “To add an Option object use addOption() instead of option() or requiredOption()”.
• Command stops the work with Error when this.parent && this._passThroughOptions && !this.parent._enablePositionalOptions.

When something fails

• Command handles failure in 2 places: it logs it and continues in 1, and lets it reach the caller in 1.

Diagram

mermaid
graph LR
  Command -->|command() / addCommand()| ChildCommand
  Command -->|createCommand()| NewCommand
  Command -->|createHelp()| Help
  Command -->|configureHelp()| HelpSettings
  Command -->|configureOutput()| OutputSettings
  Command -->|copyInheritedSettings()| InheritedSettings
  Command -->|showHelpAfterError()| ErrorHelp
  Command -->|showSuggestionAfterError()| ErrorSuggestion
  ChildCommand -->|_getCommandAndAncestors()| CommandHierarchy

Usage

js
import { Command } from 'commander';

const program = new Command();

program
  .name('tool')
  .description('Example command-line tool')
  .configureHelp({
    sortSubcommands: true,
  })
  .configureOutput({
    writeErr: (message) => process.stderr.write(message),
  })
  .showHelpAfterError()
  .showSuggestionAfterError();

program
  .command('serve')
  .description('Start the service')
  .action(() => {
    console.log('Service started');
  });

program.parse();

AI Coding Instructions

• Add subcommands through command() or addCommand() so they are attached to the command hierarchy.
• Override createCommand() when a subclass needs to create a custom command type for child commands.
• Configure help and output behavior before adding child commands when child commands should inherit those settings.
• Treat _getCommandAndAncestors() as an internal helper for hierarchy traversal; avoid calling it from application code.
• Keep showHelpAfterError() and showSuggestionAfterError() aligned with configured output handlers so error messages reach the expected stream.

Relationships

• IMPORTS → Argument
• IMPORTS → humanReadableArgName
• IMPORTS → CommanderError
• IMPORTS → Help
• IMPORTS → Option
• IMPORTS → DualOptions
• IMPORTS → suggestSimilar

Used by

1 reference from 1 file. Each is a place in this repository where the symbol is actually used — go read one rather than trusting an example.

Imported by (1)

• program — index.js:7