commander

constructor

constructor(arg: string, description?: string);

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

property argChoices

argChoices?: string[];

property defaultValue

defaultValue?: any;

property defaultValueDescription

defaultValueDescription?: string;

property description

description: string;

property required

required: boolean;

property variadic

variadic: boolean;

method argOptional

argOptional: () => this;

• Make argument optional.

method argParser

argParser: <T>(fn: (value: string, previous: T) => T) => this;

• Set the custom handler for processing CLI command arguments into argument values.

method argRequired

argRequired: () => this;

• Make argument required.

method choices

choices: (values: readonly string[]) => this;

• Only allow argument value to be one of choices.

method default

default: (value: unknown, description?: string) => this;

• Set the default value, and optionally supply the description to be displayed in the help.

method name

name: () => string;

• Return argument name.

constructor

constructor(name?: string);

property args

args: string[];

property commands

readonly commands: readonly Command[];

property options

readonly options: readonly Option[];

property parent

parent: Command;

property processedArgs

processedArgs: any[];

property registeredArguments

readonly registeredArguments: readonly Argument[];

method action

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

• Register callback fn for the command.

  Returns

  this command for chaining

  Example 1

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

method addArgument

addArgument: (arg: Argument) => this;

• Define argument syntax for command, adding a prepared argument.

  Returns

  this command for chaining

method addCommand

addCommand: (cmd: Command, opts?: CommandOptions) => this;

• Add a prepared subcommand.

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

  Returns

  this command for chaining

method addHelpCommand

addHelpCommand: {
    (cmd: Command): this;
    (nameAndArgs: string, description?: string): this;
    (enable?: boolean): this;
};

• Add prepared custom help command.

• Deprecated

  since v12, instead use helpCommand

method addHelpOption

addHelpOption: (option: Option) => this;

• Supply your own option to use for the built-in help option. This is an alternative to using helpOption() to customise the flags and description etc.

method addHelpText

addHelpText: {
    (position: AddHelpTextPosition, text: string): this;
    (
        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.

method addOption

addOption: (option: Option) => this;

• Add a prepared Option.

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

method alias

alias: { (alias: string): this; (): string };

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

  Returns

  this command for chaining

• Get alias for the command.

method aliases

aliases: { (aliases: readonly string[]): this; (): string[] };

• Set aliases for the command.

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

  Returns

  this command for chaining

• Get aliases for the command.

method allowExcessArguments

allowExcessArguments: (allowExcess?: boolean) => this;

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

  Returns

  this command for chaining

method allowUnknownOption

allowUnknownOption: (allowUnknown?: boolean) => this;

• Allow unknown options on the command line.

  Returns

  this command for chaining

method argument

argument: {
    <T>(
        flags: string,
        description: string,
        fn: (value: string, previous: T) => T,
        defaultValue?: T
    ): this;
    (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.

  Returns

  this command for chaining

  Example 1

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

method arguments

arguments: (names: string) => this;

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

  See also .argument().

  Returns

  this command for chaining

  Example 1

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

method combineFlagAndOptionalValue

combineFlagAndOptionalValue: (combine?: boolean) => this;

• Alter parsing of short flags with optional values.

  Returns

  this command for chaining

  Example 1

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

method command

command: {
    (nameAndArgs: string, opts?: CommandOptions): ReturnType<
        this['createCommand']
    >;
    (
        nameAndArgs: string,
        description: string,
        opts?: ExecutableCommandOptions
    ): this;
};

• Define a command, implemented using an action handler.

  Parameter nameAndArgs

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

  Parameter opts

  configuration options

  Returns

  new command

  Remarks

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

  Example 1

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

• Define a command, implemented in a separate executable file.

  Parameter nameAndArgs

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

  Parameter description

  description of executable command

  Parameter opts

  configuration options

  Returns

  this command for chaining

  Remarks

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

  Example 1

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

method configureHelp

configureHelp: { (configuration: HelpConfiguration): this; (): Partial<Help> };

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

• Get configuration

method configureOutput

configureOutput: {
    (configuration: OutputConfiguration): this;
    (): OutputConfiguration;
};

• 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

• Get configuration

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

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

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

method createHelp

createHelp: () => Help;

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

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

method description

description: {
    (str: string): this;
    (str: string, argsDescription: Record<string, string>): this;
    (): string;
};

• Set the description.

  Returns

  this command for chaining

• Deprecated

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

• Get the description.

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

  Returns

  this command for chaining

method error

error: (message: string, errorOptions?: ErrorOptions) => never;

• Display error message and exit (or call exitOverride).

method executableDir

executableDir: { (path: string): this; (): string };

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

  Returns

  this command for chaining

  Example 1

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

• Get the executable search directory.

method exitOverride

exitOverride: (callback?: (err: CommanderError) => never | void) => this;

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

method getOptionValue

getOptionValue: (key: string) => any;

• Retrieve option value.

method getOptionValueSource

getOptionValueSource: (key: string) => OptionValueSource | undefined;

• Get source of option value.

method getOptionValueSourceWithGlobals

getOptionValueSourceWithGlobals: (key: string) => OptionValueSource | undefined;

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

method help

help: { (context?: HelpContext): never; (cb?: (str: string) => string): never };

• Output help information and exit.

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

• Deprecated

  since v7

method helpCommand

helpCommand: {
    (nameAndArgs: string, description?: string): this;
    (enable: boolean): this;
};

• Customise or override default help command. By default a help command is automatically added if your command has subcommands.

  Example 1

  program.helpCommand('help [cmd]');
  program.helpCommand('help [cmd]', 'show help');
  program.helpCommand(false); // suppress default help command
  program.helpCommand(true); // add help command even if no subcommands

method helpInformation

helpInformation: (context?: HelpContext) => string;

• Return command help documentation.

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

method hook

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

• Add hook for life cycle event.

method name

name: { (str: string): this; (): string };

• Set the name of the command.

  Returns

  this command for chaining

• Get the name of the command.

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

  Returns

  this command for chaining

  Example 1

  program.nameFromFilename(require.main.filename);

method on

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

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

method option

option: {
    (
        flags: string,
        description?: string,
        defaultValue?: string | boolean | string[]
    ): this;
    <T>(
        flags: string,
        description: string,
        parseArg: (value: string, previous: T) => T,
        defaultValue?: T
    ): this;
    (
        flags: string,
        description: string,
        regexp: RegExp,
        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().

  Returns

  this command for chaining

  Example 1

  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

• Deprecated

  since v7, instead use choices or a custom function

method opts

opts: <T extends OptionValues>() => T;

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

method optsWithGlobals

optsWithGlobals: <T extends OptionValues>() => T;

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

method outputHelp

outputHelp: {
    (context?: HelpContext): void;
    (cb?: (str: string) => string): void;
};

• Output help information for this command.

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

• Deprecated

  since v7

method parse

parse: (argv?: readonly string[], parseOptions?: ParseOptions) => this;

• Parse argv, setting options and invoking commands when defined.

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

  Call with no parameters to parse process.argv. Detects Electron and special node options like node --eval. Easy mode!

  Or call with an array of strings to parse, and optionally where the user arguments start by specifying where the arguments are from: - 'node': default, argv[0] is the application and argv[1] is the script being run, with user arguments after that - 'electron': argv[0] is the application and argv[1] varies depending on whether the electron application is packaged - 'user': just user arguments

  Returns

  this command for chaining

  Example 1

  program.parse(); // parse process.argv and auto-detect electron and special node flags
  program.parse(process.argv); // assume argv[0] is app and argv[1] is script
  program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]

method parseAsync

parseAsync: (
    argv?: readonly string[],
    parseOptions?: ParseOptions
) => Promise<this>;

• Parse argv, setting options and invoking commands when defined.

  Call with no parameters to parse process.argv. Detects Electron and special node options like node --eval. Easy mode!

  Or call with an array of strings to parse, and optionally where the user arguments start by specifying where the arguments are from: - 'node': default, argv[0] is the application and argv[1] is the script being run, with user arguments after that - 'electron': argv[0] is the application and argv[1] varies depending on whether the electron application is packaged - 'user': just user arguments

  Returns

  Promise

  Example 1

  await program.parseAsync(); // parse process.argv and auto-detect electron and special node flags
  await program.parseAsync(process.argv); // assume argv[0] is app and argv[1] is script
  await program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]

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

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

  Returns

  this command for chaining

method requiredOption

requiredOption: {
    (
        flags: string,
        description?: string,
        defaultValue?: string | boolean | string[]
    ): this;
    <T>(
        flags: string,
        description: string,
        parseArg: (value: string, previous: T) => T,
        defaultValue?: T
    ): this;
    (
        flags: string,
        description: string,
        regexp: RegExp,
        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.

• Deprecated

  since v7, instead use choices or a custom function

method setOptionValue

setOptionValue: (key: string, value: unknown) => this;

• Store option value.

method setOptionValueWithSource

setOptionValueWithSource: (
    key: string,
    value: unknown,
    source: OptionValueSource
) => this;

• Store option value and where the value came from.

method showHelpAfterError

showHelpAfterError: (displayHelp?: boolean | string) => this;

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

method showSuggestionAfterError

showSuggestionAfterError: (displaySuggestion?: boolean) => this;

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

method storeOptionsAsProperties

storeOptionsAsProperties: {
    <T extends OptionValues>(): this & T;
    <T extends OptionValues>(storeAsProperties: true): this & T;
    (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().

  Returns

  this command for chaining

method summary

summary: { (str: string): this; (): string };

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

  Returns

  this command for chaining

• Get the summary.

method usage

usage: { (str: string): this; (): string };

• Set the command usage.

  Returns

  this command for chaining

• Get the command usage.

method version

version: {
    (str: string, flags?: string, description?: string): this;
    (): string;
};

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

• Get the program version.

constructor

constructor(exitCode: number, code: string, message: string);

• Constructs the CommanderError class

  Parameter exitCode

  suggested exit code which could be used with process.exit

  Parameter code

  an id string representing the error

  Parameter message

  human-readable description of the error

property code

code: string;

property exitCode

exitCode: number;

property message

message: string;

property nestedError

nestedError?: string;

constructor

constructor();

property helpWidth

helpWidth?: number;

• output helpWidth, long lines are wrapped to fit

property showGlobalOptions

showGlobalOptions: boolean;

property sortOptions

sortOptions: boolean;

property sortSubcommands

sortSubcommands: boolean;

method argumentDescription

argumentDescription: (argument: Argument) => string;

• Get the argument description to show in the list of arguments.

method argumentTerm

argumentTerm: (argument: Argument) => string;

• Get the argument term to show in the list of arguments.

method commandDescription

commandDescription: (cmd: Command) => string;

• Get the description for the command.

method commandUsage

commandUsage: (cmd: Command) => string;

• Get the command usage to be displayed at the top of the built-in help.

method formatHelp

formatHelp: (cmd: Command, helper: Help) => string;

• Generate the built-in help text.

method longestArgumentTermLength

longestArgumentTermLength: (cmd: Command, helper: Help) => number;

• Get the longest argument term length.

method longestGlobalOptionTermLength

longestGlobalOptionTermLength: (cmd: Command, helper: Help) => number;

• Get the longest global option term length.

method longestOptionTermLength

longestOptionTermLength: (cmd: Command, helper: Help) => number;

• Get the longest option term length.

method longestSubcommandTermLength

longestSubcommandTermLength: (cmd: Command, helper: Help) => number;

• Get the longest command term length.

method optionDescription

optionDescription: (option: Option) => string;

• Get the option description to show in the list of options.

method optionTerm

optionTerm: (option: Option) => string;

• Get the option term to show in the list of options.

method padWidth

padWidth: (cmd: Command, helper: Help) => number;

• Calculate the pad width from the maximum term length.

method subcommandDescription

subcommandDescription: (cmd: Command) => string;

• Get the command summary to show in the list of subcommands.

method subcommandTerm

subcommandTerm: (cmd: Command) => string;

• Get the command term to show in the list of subcommands.

method visibleArguments

visibleArguments: (cmd: Command) => Argument[];

• Get an array of the arguments which have descriptions.

method visibleCommands

visibleCommands: (cmd: Command) => Command[];

• Get an array of the visible subcommands. Includes a placeholder for the implicit help command, if there is one.

method visibleGlobalOptions

visibleGlobalOptions: (cmd: Command) => Option[];

• Get an array of the visible global options. (Not including help.)

method visibleOptions

visibleOptions: (cmd: Command) => Option[];

• Get an array of the visible options. Includes a placeholder for the implicit help option, if there is one.

method wrap

wrap: (
    str: string,
    width: number,
    indent: number,
    minColumnWidth?: number
) => string;

• Wrap the given string to width characters per line, with lines after the first indented. Do not wrap if insufficient room for wrapping (minColumnWidth), or string is manually formatted.

constructor

constructor(message: string);

• Constructs the InvalidArgumentError class

  Parameter message

  explanation of why argument is invalid

constructor

constructor(message: string);

• Constructs the InvalidArgumentError class

  Parameter message

  explanation of why argument is invalid

constructor

constructor(flags: string, description?: string);

property argChoices

argChoices?: string[];

property defaultValue

defaultValue?: any;

property defaultValueDescription

defaultValueDescription?: string;

property description

description: string;

property envVar

envVar?: string;

property flags

flags: string;

property hidden

hidden: boolean;

property long

long?: string;

property mandatory

mandatory: boolean;

property negate

negate: boolean;

property optional

optional: boolean;

property parseArg

parseArg?: <T>(value: string, previous: T) => T;

property presetArg

presetArg?: {};

property required

required: boolean;

property short

short?: string;

property variadic

variadic: boolean;

method argParser

argParser: <T>(fn: (value: string, previous: T) => T) => this;

• Set the custom handler for processing CLI option arguments into option values.

method attributeName

attributeName: () => string;

• Return option name, in a camelcase format that can be used as a object attribute key.

method choices

choices: (values: readonly string[]) => this;

• Only allow option value to be one of choices.

method conflicts

conflicts: (names: string | string[]) => this;

• Add option name(s) that conflict with this option. An error will be displayed if conflicting options are found during parsing.

  Example 1

  new Option('--rgb').conflicts('cmyk');
  new Option('--js').conflicts(['ts', 'jsx']);

method default

default: (value: unknown, description?: string) => this;

• Set the default value, and optionally supply the description to be displayed in the help.

method env

env: (name: string) => this;

• Set environment variable to check for option value.

  An environment variables is only used if when processed the current option value is undefined, or the source of the current value is 'default' or 'config' or 'env'.

method hideHelp

hideHelp: (hide?: boolean) => this;

• Hide option in help.

method implies

implies: (optionValues: OptionValues) => this;

• Specify implied option values for when this option is set and the implied options are not.

  The custom processing (parseArg) is not called on the implied values.

  Example 1

  program .addOption(new Option('--log', 'write logging information to file')) .addOption(new Option('--trace', 'log extra details').implies({ log: 'trace.txt' }));

method isBoolean

isBoolean: () => boolean;

• Return whether a boolean option.

  Options are one of boolean, negated, required argument, or optional argument.

method makeOptionMandatory

makeOptionMandatory: (mandatory?: boolean) => this;

• Whether the option is mandatory and must have a value after parsing.

method name

name: () => string;

• Return option name.

method preset

preset: (arg: unknown) => this;

• Preset to use when option used without option-argument, especially optional but also boolean and negated. The custom processing (parseArg) is called.

  Example 1

  new Option('--color').default('GREYSCALE').preset('RGB');
  new Option('--donate [amount]').preset('20').argParser(parseFloat);

property command

command: Command;

property error

error: boolean;

property hidden

hidden?: boolean;

property isDefault

isDefault?: boolean;

property noHelp

noHelp?: boolean;

• Deprecated

  since v7, replaced by hidden

property code

code?: string;

• an id string representing the error

property exitCode

exitCode?: number;

• suggested exit code which could be used with process.exit

property executableFile

executableFile?: string;

property error

error: boolean;

method getErrHelpWidth

getErrHelpWidth: () => number;

method getOutHelpWidth

getOutHelpWidth: () => number;

method outputError

outputError: (str: string, write: (str: string) => void) => void;

method writeErr

writeErr: (str: string) => void;

method writeOut

writeOut: (str: string) => void;

property from

from: 'node' | 'electron' | 'user';

property operands

operands: string[];

property unknown

unknown: string[];