Class CliCommand

args

Readonlycommands

Readonlyoptions

parent

processedArgs

ReadonlyregisteredArguments

action

• action(fn: (...args: any[]) => void | Promise<void>): this

  Register callback fn for the command.

  Parameters

  • fn: (...args: any[]) => void | Promise<void>

  Returns this

  this command for chaining

  Example

  program
    .command('serve')
    .description('start service')
    .action(function() {
      // do work here
    });
  Copy

addArgument

• addArgument(arg: Argument): this

  Define argument syntax for command, adding a prepared argument.

  Parameters

  • arg: Argument

  Returns this

  this command for chaining

addCommand

• addCommand(cmd: Command, opts?: CommandOptions): this

  Add a prepared subcommand.

  See .command() for creating an attached subcommand which inherits settings from its parent.

  Parameters

  • cmd: Command
  • Optionalopts: CommandOptions

  Returns this

  this command for chaining

addHelpCommand

• addHelpCommand(
      enableOrNameAndArgs?: string | boolean,
      description?: string,
  ): this

  Override default decision whether to add implicit help command.

  Parameters

  • OptionalenableOrNameAndArgs: string | boolean
  • Optionaldescription: string

  Returns this

  this command for chaining

  Example

  addHelpCommand() // force on
  addHelpCommand(false); // force off
  addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details
  Copy

addHelpText

• addHelpText(position: AddHelpTextPosition, text: string): this

  Add additional text to be displayed with the built-in help.

  Position is 'before' or 'after' to affect just this command, and 'beforeAll' or 'afterAll' to affect this command and all its subcommands.

  Parameters

  • position: AddHelpTextPosition
  • text: string

  Returns this

• addHelpText(
      position: AddHelpTextPosition,
      text: (context: AddHelpTextContext) => string,
  ): this

  Add additional text to be displayed with the built-in help.

  Position is 'before' or 'after' to affect just this command, and 'beforeAll' or 'afterAll' to affect this command and all its subcommands.

  Parameters

  • position: AddHelpTextPosition
  • text: (context: AddHelpTextContext) => string

  Returns this

addOption

• addOption(option: Option): this

  Add a prepared Option.

  See .option() and .requiredOption() for creating and attaching an option in a single call.

  Parameters

  • option: Option

  Returns this

alias

• alias(alias: string): this

  Set an alias for the command.

  You may call more than once to add multiple aliases. Only the first alias is shown in the auto-generated help.

  Parameters

  • alias: string

  Returns this

  this command for chaining

• alias(): string

  Get alias for the command.

  Returns string

aliases

• aliases(aliases: readonly string[]): this

  Set aliases for the command.

  Only the first alias is shown in the auto-generated help.

  Parameters

  • aliases: readonly string[]

  Returns this

  this command for chaining

• aliases(): string[]

  Get aliases for the command.

  Returns string[]

allowExcessArguments

• allowExcessArguments(allowExcess?: boolean): this

  Allow excess command-arguments on the command line. Pass false to make excess arguments an error.

  Parameters

  • OptionalallowExcess: boolean

  Returns this

  this command for chaining

allowUnknownOption

• allowUnknownOption(allowUnknown?: boolean): this

  Allow unknown options on the command line.

  Parameters

  • OptionalallowUnknown: boolean

  Returns this

  this command for chaining

argument

• argument<T>(
      flags: string,
      description: string,
      fn: (value: string, previous: T) => T,
      defaultValue?: T,
  ): this

  Define argument syntax for command.

  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.

  Type Parameters

  • T

  Parameters

  • flags: string
  • description: string
  • fn: (value: string, previous: T) => T
  • OptionaldefaultValue: T

  Returns this

  this command for chaining

  Example

  program.argument('<input-file>');
  program.argument('[output-file]');
  Copy

• argument(name: string, description?: string, defaultValue?: unknown): this

  Define argument syntax for command.

  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.

  Parameters

  • name: string
  • Optionaldescription: string
  • OptionaldefaultValue: unknown

  Returns this

  this command for chaining

  Example

  program.argument('<input-file>');
  program.argument('[output-file]');
  Copy

arguments

• arguments(names: string): this

  Define argument syntax for command, adding multiple at once (without descriptions).

  See also .argument().

  Parameters

  • names: string

  Returns this

  this command for chaining

  Example

  program.arguments('<cmd> [env]');
  Copy

combineFlagAndOptionalValue

• combineFlagAndOptionalValue(combine?: boolean): this

  Alter parsing of short flags with optional values.

  Parameters

  • Optionalcombine: boolean

  Returns this

  this command for chaining

  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`
  Copy

command

• command(nameAndArgs: string, opts?: CommandOptions): Command

  Define a command, implemented using an action handler.

  Parameters

  • nameAndArgs: string

    command name and arguments, args are <required> or [optional] and last may also be variadic...

  • Optionalopts: CommandOptions

    configuration options

  Returns Command

  new command

  Remarks

  The command description is supplied using .description, not as a parameter to .command.

  Example

  program
    .command('clone <source> [destination]')
    .description('clone a repository into a newly created directory')
    .action((source, destination) => {
      console.log('clone command called');
    });
  Copy

• command(
      nameAndArgs: string,
      description: string,
      opts?: ExecutableCommandOptions,
  ): this

  Define a command, implemented in a separate executable file.

  Parameters

  • nameAndArgs: string

    command name and arguments, args are <required> or [optional] and last may also be variadic...

  • description: string

    description of executable command

  • Optionalopts: ExecutableCommandOptions

    configuration options

  Returns this

  this command for chaining

  Remarks

  The command description is supplied as the second parameter to .command.

  Example

   program
     .command('start <service>', 'start named service')
     .command('stop [service]', 'stop named service, or all if no name supplied');
  Copy

configureHelp

• configureHelp(configuration: HelpConfiguration): this

  You can customise the help by overriding Help properties using configureHelp(), or with a subclass of Help by overriding createHelp().

  Parameters

  • configuration: HelpConfiguration

  Returns this

• configureHelp(): HelpConfiguration

  Get configuration

  Returns HelpConfiguration

configureOutput

• configureOutput(configuration: OutputConfiguration): this

  The default output goes to stdout and stderr. You can customise this for special 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
  Copy

  Parameters

  • configuration: OutputConfiguration

  Returns this

• configureOutput(): OutputConfiguration

  Get configuration

  Returns OutputConfiguration

copyInheritedSettings

• copyInheritedSettings(sourceCommand: Command): this

  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.)

  Parameters

  • sourceCommand: Command

  Returns this

createArgument

• createArgument(name: string, description?: string): Argument

  Factory routine to create a new unattached argument.

  See .argument() for creating an attached argument, which uses this routine to create the argument. You can override createArgument to return a custom argument.

  Parameters

  • name: string
  • Optionaldescription: string

  Returns Argument

createCommand

• createCommand(name?: string): Command

  Factory routine to create a new unattached command.

  See .command() for creating an attached subcommand, which uses this routine to create the command. You can override createCommand to customise subcommands.

  Parameters

  • Optionalname: string

  Returns Command

createHelp

• createHelp(): Help

  You can customise the help with a subclass of Help by overriding createHelp, or by overriding Help properties using configureHelp().

  Returns Help

createOption

• createOption(flags: string, description?: string): Option

  Factory routine to create a new unattached option.

  See .option() for creating an attached option, which uses this routine to create the option. You can override createOption to return a custom option.

  Parameters

  • flags: string
  • Optionaldescription: string

  Returns Option

description

• description(str: string): this

  Set the description.

  Parameters

  • str: string

  Returns this

  this command for chaining

• description(str: string, argsDescription: Record<string, string>): this

  Parameters

  • str: string
  • argsDescription: Record<string, string>

  Returns this

  Deprecated

  since v8, instead use .argument to add command argument with description

• description(): string

  Get the description.

  Returns string

enablePositionalOptions

• enablePositionalOptions(positional?: boolean): this

  Enable positional options. Positional means global options are specified before subcommands which lets subcommands reuse the same option names, and also enables subcommands to turn on passThroughOptions.

  The default behaviour is non-positional and global options may appear anywhere on the command line.

  Parameters

  • Optionalpositional: boolean

  Returns this

  this command for chaining

error

• error(message: string, errorOptions?: ErrorOptions): never

  Display error message and exit (or call exitOverride).

  Parameters

  • message: string
  • OptionalerrorOptions: ErrorOptions

  Returns never

executableDir

• executableDir(path: string): this

  Set the directory for searching for executable subcommands of this command.

  Parameters

  • path: string

  Returns this

  this command for chaining

  Example

  program.executableDir(__dirname);
  // or
  program.executableDir('subcommands');
  Copy

• executableDir(): string | null

  Get the executable search directory.

  Returns string | null

exitOverride

• exitOverride(callback?: (err: CommanderError) => void): this

  Register callback to use as replacement for calling process.exit.

  Parameters

  • Optionalcallback: (err: CommanderError) => void

  Returns this

getOptionValue

• getOptionValue(key: string): any

  Retrieve option value.

  Parameters

  • key: string

  Returns any

getOptionValueSource

• getOptionValueSource(key: string): OptionValueSource

  Get source of option value.

  Parameters

  • key: string

  Returns OptionValueSource

getOptionValueSourceWithGlobals

• getOptionValueSourceWithGlobals(key: string): OptionValueSource

  Get source of option value. See also .optsWithGlobals().

  Parameters

  • key: string

  Returns OptionValueSource

help

• help(context?: HelpContext): never

  Output help information and exit.

  Outputs built-in help, and custom text added using .addHelpText().

  Parameters

  • Optionalcontext: HelpContext

  Returns never

• help(cb?: (str: string) => string): never

  Parameters

  • Optionalcb: (str: string) => string

  Returns never

  Deprecated

  since v7

helpInformation

• helpInformation(context?: HelpContext): string

  Return command help documentation.

  Parameters

  • Optionalcontext: HelpContext

  Returns string

helpOption

• helpOption(flags?: string | boolean, description?: string): this

  You can pass in flags and a description to override the help flags and help description for your command. Pass in false to disable the built-in help option.

  Parameters

  • Optionalflags: string | boolean
  • Optionaldescription: string

  Returns this

hook

• hook(
      event: HookEvent,
      listener: (
          thisCommand: Command,
          actionCommand: Command,
      ) => void | Promise<void>,
  ): this

  Add hook for life cycle event.

  Parameters

  • event: HookEvent
  • listener: (thisCommand: Command, actionCommand: Command) => void | Promise<void>

  Returns this

name

• name(str: string): this

  Set the name of the command.

  Parameters

  • str: string

  Returns this

  this command for chaining

• name(): string

  Get the name of the command.

  Returns string

nameFromFilename

• nameFromFilename(filename: string): this

  Set the name of the command from script filename, such as process.argv[1], or require.main.filename, or __filename.

  (Used internally and public although not documented in README.)

  Parameters

  • filename: string

  Returns this

  this command for chaining

  Example

  program.nameFromFilename(require.main.filename);
  Copy

on

• on(event: string | symbol, listener: (...args: any[]) => void): this

  Add a listener (callback) for when events occur. (Implemented using EventEmitter.)

  Parameters

  • event: string | symbol
  • listener: (...args: any[]) => void

  Returns this

option

• option(
      flags: string,
      description?: string,
      defaultValue?: string | boolean | string[],
  ): this

  Define option with flags, description, and optional argument parsing function or defaultValue or both.

  The flags string contains the short and/or long flags, separated by comma, a pipe or space. A required option-argument is indicated by <> and an optional option-argument by [].

  See the README for more details, and see also addOption() and requiredOption().

  Parameters

  • flags: string
  • Optionaldescription: string
  • OptionaldefaultValue: string | boolean | string[]

  Returns this

  this command for chaining

  Example

  program
      .option('-p, --pepper', 'add pepper')
      .option('-p, --pizza-type <TYPE>', 'type of pizza') // required option-argument
      .option('-c, --cheese [CHEESE]', 'add extra cheese', 'mozzarella') // optional option-argument with default
      .option('-t, --tip <VALUE>', 'add tip to purchase cost', parseFloat) // custom parse function
  Copy

• option<T>(
      flags: string,
      description: string,
      parseArg: (value: string, previous: T) => T,
      defaultValue?: T,
  ): this

  Define option with flags, description, and optional argument parsing function or defaultValue or both.

  The flags string contains the short and/or long flags, separated by comma, a pipe or space. A required option-argument is indicated by <> and an optional option-argument by [].

  See the README for more details, and see also addOption() and requiredOption().

  Type Parameters

  • T

  Parameters

  • flags: string
  • description: string
  • parseArg: (value: string, previous: T) => T
  • OptionaldefaultValue: T

  Returns this

  this command for chaining

  Example

  program
      .option('-p, --pepper', 'add pepper')
      .option('-p, --pizza-type <TYPE>', 'type of pizza') // required option-argument
      .option('-c, --cheese [CHEESE]', 'add extra cheese', 'mozzarella') // optional option-argument with default
      .option('-t, --tip <VALUE>', 'add tip to purchase cost', parseFloat) // custom parse function
  Copy

• option(
      flags: string,
      description: string,
      regexp: RegExp,
      defaultValue?: string | boolean | string[],
  ): this

  Parameters

  • flags: string
  • description: string
  • regexp: RegExp
  • OptionaldefaultValue: string | boolean | string[]

  Returns this

  Deprecated

  since v7, instead use choices or a custom function

opts

• opts<T extends OptionValues>(): T

  Return an object containing local option values as key-value pairs

  Type Parameters

  • T extends OptionValues

  Returns T

optsWithGlobals

• optsWithGlobals<T extends OptionValues>(): T

  Return an object containing merged local and global option values as key-value pairs.

  Type Parameters

  • T extends OptionValues

  Returns T

outputHelp

• outputHelp(context?: HelpContext): void

  Output help information for this command.

  Outputs built-in help, and custom text added using .addHelpText().

  Parameters

  • Optionalcontext: HelpContext

  Returns void

• outputHelp(cb?: (str: string) => string): void

  Parameters

  • Optionalcb: (str: string) => string

  Returns void

  Deprecated

  since v7

parse

• parse(argv?: readonly string[], options?: ParseOptions): this

  Parse argv, setting options and invoking commands when defined.

  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.

  Parameters

  • Optionalargv: readonly string[]
  • Optionaloptions: ParseOptions

  Returns this

  this command for chaining

  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]
  Copy

parseAsync

• parseAsync(
      argv?: readonly string[],
      options?: ParseOptions,
  ): Promise<CliCommand>

  Parse argv, setting options and invoking commands when defined.

  Use parseAsync instead of parse if any of your action handlers are async. Returns a Promise.

  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.

  Parameters

  • Optionalargv: readonly string[]
  • Optionaloptions: ParseOptions

  Returns Promise<CliCommand>

  Promise

  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]
  Copy

parseOptions

• parseOptions(argv: string[]): ParseOptionsResult

  Parse options from argv removing known options, and return argv split into operands and unknown arguments.

  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], []
  

  Parameters

  • argv: string[]

  Returns ParseOptionsResult

passThroughOptions

• passThroughOptions(passThrough?: boolean): this

  Pass through options that come after command-arguments rather than treat them as command-options, so actual command-options come before command-arguments. Turning this on for a subcommand requires positional options to have been enabled on the program (parent commands).

  The default behaviour is non-positional and options may appear before or after command-arguments.

  Parameters

  • OptionalpassThrough: boolean

  Returns this

  this command for chaining

requiredOption

• requiredOption(
      flags: string,
      description?: string,
      defaultValue?: string | boolean | string[],
  ): this

  Define a required option, which must have a value after parsing. This usually means the option must be specified on the command line. (Otherwise the same as .option().)

  The flags string contains the short and/or long flags, separated by comma, a pipe or space.

  Parameters

  • flags: string
  • Optionaldescription: string
  • OptionaldefaultValue: string | boolean | string[]

  Returns this

• requiredOption<T>(
      flags: string,
      description: string,
      parseArg: (value: string, previous: T) => T,
      defaultValue?: T,
  ): this

  Define a required option, which must have a value after parsing. This usually means the option must be specified on the command line. (Otherwise the same as .option().)

  The flags string contains the short and/or long flags, separated by comma, a pipe or space.

  Type Parameters

  • T

  Parameters

  • flags: string
  • description: string
  • parseArg: (value: string, previous: T) => T
  • OptionaldefaultValue: T

  Returns this

• requiredOption(
      flags: string,
      description: string,
      regexp: RegExp,
      defaultValue?: string | boolean | string[],
  ): this

  Parameters

  • flags: string
  • description: string
  • regexp: RegExp
  • OptionaldefaultValue: string | boolean | string[]

  Returns this

  Deprecated

  since v7, instead use choices or a custom function

setOptionValue

• setOptionValue(key: string, value: unknown): this

  Store option value.

  Parameters

  • key: string
  • value: unknown

  Returns this

setOptionValueWithSource

• setOptionValueWithSource(
      key: string,
      value: unknown,
      source: OptionValueSource,
  ): this

  Store option value and where the value came from.

  Parameters

  • key: string
  • value: unknown
  • source: OptionValueSource

  Returns this

showHelpAfterError

• showHelpAfterError(displayHelp?: string | boolean): this

  Display the help or a custom message after an error occurs.

  Parameters

  • OptionaldisplayHelp: string | boolean

  Returns this

showSuggestionAfterError

• showSuggestionAfterError(displaySuggestion?: boolean): this

  Display suggestion of similar commands for unknown commands, or options for unknown options.

  Parameters

  • OptionaldisplaySuggestion: boolean

  Returns this

storeOptionsAsProperties

• storeOptionsAsProperties<T extends OptionValues>(): CliCommand & T

  Whether to store option values as properties on command object, or store separately (specify false). In both cases the option values can be accessed using .opts().

  Type Parameters

  • T extends OptionValues

  Returns CliCommand & T

  this command for chaining

• storeOptionsAsProperties<T extends OptionValues>(
      storeAsProperties: true,
  ): CliCommand & T

  Whether to store option values as properties on command object, or store separately (specify false). In both cases the option values can be accessed using .opts().

  Type Parameters

  • T extends OptionValues

  Parameters

  • storeAsProperties: true

  Returns CliCommand & T

  this command for chaining

• storeOptionsAsProperties(storeAsProperties?: boolean): this

  Whether to store option values as properties on command object, or store separately (specify false). In both cases the option values can be accessed using .opts().

  Parameters

  • OptionalstoreAsProperties: boolean

  Returns this

  this command for chaining

summary

• summary(str: string): this

  Set the summary. Used when listed as subcommand of parent.

  Parameters

  • str: string

  Returns this

  this command for chaining

• summary(): string

  Get the summary.

  Returns string

usage

• usage(str: string): this

  Set the command usage.

  Parameters

  • str: string

  Returns this

  this command for chaining

• usage(): string

  Get the command usage.

  Returns string

version

• version(str: string, flags?: string, description?: string): this

  Set the program version to str.

  This method auto-registers the "-V, --version" flag which will print the version number when passed.

  You can optionally supply the flags and description to override the defaults.

  Parameters

  • str: string
  • Optionalflags: string
  • Optionaldescription: string

  Returns this

• version(): string | undefined

  Get the program version.

  Returns string | undefined