Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Command

Hierarchy

  • Command

Index

Constructors

Properties

Methods

Constructors

constructor

  • new Command(name?: string): Command

  • Parameters

    • Optional name: string

    Returns Command

Properties

args

args: string[]

commands

commands: Command[]

parent

parent: null | Command

processedArgs

processedArgs: any[]

Methods

action

  • Register callback fn for the command.

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

    Parameters

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

        • Parameters

          • Rest ...args: any[]

          Returns void | Promise<void>

    Returns Command

    this command for chaining

addArgument

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

    Parameters

    Returns Command

    this command for chaining

addCommand

  • Add a prepared subcommand.

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

    Parameters

    Returns Command

    this command for chaining

addHelpCommand

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

  • Override default decision whether to add implicit help command.

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

    Parameters

    • Optional enableOrNameAndArgs: string | boolean
    • Optional description: string

    Returns Command

    this command for chaining

addHelpText

  • 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

    Returns Command

  • Parameters

    Returns Command

addOption

  • Add a prepared Option.

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

    Parameters

    Returns Command

alias

  • alias(alias: string): Command
  • alias(): 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.

    Parameters

    • alias: string

    Returns Command

    this command for chaining

  • Get alias for the command.

    Returns string

aliases

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

  • Set aliases for the command.

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

    Parameters

    • aliases: readonly string[]

    Returns Command

    this command for chaining

  • Get aliases for the command.

    Returns string[]

allowExcessArguments

  • allowExcessArguments(allowExcess?: boolean): Command

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

    Parameters

    • Optional allowExcess: boolean

    Returns Command

    this command for chaining

allowUnknownOption

  • allowUnknownOption(allowUnknown?: boolean): Command

  • Allow unknown options on the command line.

    Parameters

    • Optional allowUnknown: boolean

    Returns Command

    this command for chaining

argument

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

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

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

    Type parameters

    • T

    Parameters

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

        • Parameters

          • value: string
          • previous: T

          Returns T

    • Optional defaultValue: T

    Returns Command

    this command for chaining

  • Parameters

    • name: string
    • Optional description: string
    • Optional defaultValue: unknown

    Returns Command

arguments

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

    See also .argument().

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

    Parameters

    • names: string

    Returns Command

    this command for chaining

combineFlagAndOptionalValue

  • combineFlagAndOptionalValue(combine?: boolean): Command

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

    Parameters

    • Optional combine: boolean

    Returns Command

    this command for chaining

command

  • Define a command, implemented using an action handler.

    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');
      });

    Parameters

    • nameAndArgs: string

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

    • Optional opts: CommandOptions

      configuration options

    Returns Command

    new command

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

    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');

    Parameters

    • nameAndArgs: string

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

    • description: string

      description of executable command

    • Optional opts: ExecutableCommandOptions

      configuration options

    Returns Command

    this command for chaining

configureHelp

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

    Parameters

    Returns Command

  • Get configuration

    Returns Partial<Help>

configureOutput

  • 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

    Parameters

    Returns Command

  • Get configuration

    Returns OutputConfiguration

copyInheritedSettings

  • 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

    Returns Command

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
    • Optional description: 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

    • Optional name: string

    Returns Command

createHelp

  • 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
    • Optional description: string

    Returns Option

description

  • description(str: string): Command
  • description(str: string, argsDescription: {}): Command
  • description(): string

  • Set the description.

    Parameters

    • str: string

    Returns Command

    this command for chaining

  • Get the description.

    deprecated

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

    Parameters

    • str: string
    • argsDescription: {}
      • [argName: string]: string

    Returns Command

  • Get the description.

    Returns string

enablePositionalOptions

  • enablePositionalOptions(positional?: boolean): Command

  • 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

    • Optional positional: boolean

    Returns Command

    this command for chaining

error

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

    Parameters

    Returns never

executableDir

  • executableDir(path: string): Command
  • executableDir(): string

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

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

    Parameters

    • path: string

    Returns Command

    this command for chaining

  • Get the executable search directory.

    Returns string

exitOverride

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

    Parameters

    Returns Command

getOptionValue

  • getOptionValue(key: string): any

  • Retrieve option value.

    Parameters

    • key: string

    Returns any

getOptionValueSource

  • Retrieve option value source.

    Parameters

    • key: string

    Returns OptionValueSource

help

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

  • Output help information and exit.

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

    deprecated

    since v7

    Parameters

    Returns never

  • deprecated

    since v7

    Parameters

    • Optional cb: (str: string) => string
        • (str: string): string

        • Parameters

          • str: string

          Returns string

    Returns never

helpInformation

  • Return command help documentation.

    Parameters

    Returns string

helpOption

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

  • 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

    • Optional flags: string | boolean
    • Optional description: string

    Returns Command

hook

name

  • name(str: string): Command
  • name(): string

  • Set the name of the command.

    Parameters

    • str: string

    Returns Command

    this command for chaining

  • Get the name of the command.

    Returns string

nameFromFilename

  • nameFromFilename(filename: string): Command

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

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

    Parameters

    • filename: string

    Returns Command

    this command for chaining

on

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

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

    Parameters

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

        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns Command

option

  • option(flags: string, description?: string, defaultValue?: string | boolean | string[]): Command
  • option<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): Command
  • option(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): Command

  • Define option with flags, description and optional coercion fn.

    The flags string contains the short and/or long flags, 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"
    example
    // simple boolean defaulting to false
     program.option('-p, --pepper', 'add pepper');

     --pepper
     program.pepper
     // => Boolean

     // simple boolean defaulting to true
     program.option('-C, --no-cheese', 'remove cheese');

     program.cheese
     // => true

     --no-cheese
     program.cheese
     // => false

     // required argument
     program.option('-C, --chdir <path>', 'change the working directory');

     --chdir /tmp
     program.chdir
     // => "/tmp"

     // optional argument
     program.option('-c, --cheese [type]', 'add cheese [marble]');

    Parameters

    • flags: string
    • Optional description: string
    • Optional defaultValue: string | boolean | string[]

    Returns Command

    this command for chaining

  • deprecated

    since v7, instead use choices or a custom function

    Type parameters

    • T

    Parameters

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

        • Parameters

          • value: string
          • previous: T

          Returns T

    • Optional defaultValue: T

    Returns Command

  • deprecated

    since v7, instead use choices or a custom function

    Parameters

    • flags: string
    • description: string
    • regexp: RegExp
    • Optional defaultValue: string | boolean | string[]

    Returns Command

opts

  • opts<T>(): T

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

    Type parameters

    Returns T

optsWithGlobals

  • optsWithGlobals<T>(): T

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

    Type parameters

    Returns T

outputHelp

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

  • Output help information for this command.

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

    deprecated

    since v7

    Parameters

    Returns void

  • deprecated

    since v7

    Parameters

    • Optional cb: (str: string) => string
        • (str: string): string

        • Parameters

          • str: string

          Returns string

    Returns void

parse

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

    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]

    Parameters

    • Optional argv: readonly string[]
    • Optional options: ParseOptions

    Returns Command

    this command for chaining

parseAsync

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

    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]

    Parameters

    • Optional argv: readonly string[]
    • Optional options: ParseOptions

    Returns Promise<Command>

    Promise

parseOptions

  • 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): Command

  • 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

    • Optional passThrough: boolean

    Returns Command

    this command for chaining

requiredOption

  • requiredOption(flags: string, description?: string, defaultValue?: string | boolean | string[]): Command
  • requiredOption<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): Command
  • requiredOption(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): Command

  • 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

    Parameters

    • flags: string
    • Optional description: string
    • Optional defaultValue: string | boolean | string[]

    Returns Command

  • deprecated

    since v7, instead use choices or a custom function

    Type parameters

    • T

    Parameters

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

        • Parameters

          • value: string
          • previous: T

          Returns T

    • Optional defaultValue: T

    Returns Command

  • deprecated

    since v7, instead use choices or a custom function

    Parameters

    • flags: string
    • description: string
    • regexp: RegExp
    • Optional defaultValue: string | boolean | string[]

    Returns Command

setOptionValue

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

  • Store option value.

    Parameters

    • key: string
    • value: unknown

    Returns Command

setOptionValueWithSource

  • Store option value and where the value came from.

    Parameters

    Returns Command

showHelpAfterError

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

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

    Parameters

    • Optional displayHelp: string | boolean

    Returns Command

showSuggestionAfterError

  • showSuggestionAfterError(displaySuggestion?: boolean): Command

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

    Parameters

    • Optional displaySuggestion: boolean

    Returns Command

storeOptionsAsProperties

  • storeOptionsAsProperties<T>(): Command & T
  • storeOptionsAsProperties<T>(storeAsProperties: true): Command & T
  • storeOptionsAsProperties(storeAsProperties?: boolean): Command

  • 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

    Returns Command & T

    this command for chaining

  • Type parameters

    Parameters

    • storeAsProperties: true

    Returns Command & T

  • Parameters

    • Optional storeAsProperties: boolean

    Returns Command

summary

  • summary(str: string): Command
  • summary(): string

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

    Parameters

    • str: string

    Returns Command

    this command for chaining

  • Get the summary.

    Returns string

usage

  • usage(str: string): Command
  • usage(): string

  • Set the command usage.

    Parameters

    • str: string

    Returns Command

    this command for chaining

  • Get the command usage.

    Returns string

version

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

  • 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
    • Optional flags: string
    • Optional description: string

    Returns Command

Generated using TypeDoc