ReadonlycommandsReadonlyoptionsReadonlyregisteredInternal: set the merged root options bag for this run.
Register callback fn for the command.
this command for chaining
Define argument syntax for command, adding a prepared argument.
this command for chaining
Add a prepared subcommand.
See .command() for creating an attached subcommand which inherits settings from its parent.
Optionalopts: CommandOptionsthis command for chaining
Add prepared custom help command.
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.
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.
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.
Add a prepared Option.
See .option() and .requiredOption() for creating and attaching an option in a single call.
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.
this command for chaining
Get alias for the command.
Set aliases for the command.
Only the first alias is shown in the auto-generated help.
this command for chaining
Get aliases for the command.
Allow excess command-arguments on the command line. Pass false to make excess arguments an error.
OptionalallowExcess: booleanthis command for chaining
Allow unknown options on the command line.
OptionalallowUnknown: booleanthis command for chaining
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.
this command for chaining
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.
Optionaldescription: stringOptionaldefaultValue: unknownthis command for chaining
Attach legacy root flags to this CLI instance. Defaults come from baseRootOptionDefaults when none are provided.
Optionaldefaults: Partial<RootOptionsShape>Optionalopts: { includeCommandOption?: boolean }Branding helper: set CLI name/description/version and optional help header. If version is omitted and importMetaUrl is provided, attempts to read the nearest package.json version (best-effort; non-fatal on failure).
Alter parsing of short flags with optional values.
Optionalcombine: booleanthis command for chaining
Define a command, implemented using an action handler.
command name and arguments, args are <required> or [optional] and last may also be variadic...
Optionalopts: CommandOptionsconfiguration options
new command
Define a command, implemented in a separate executable file.
command name and arguments, args are <required> or [optional] and last may also be variadic...
description of executable command
Optionalopts: ExecutableCommandOptionsconfiguration options
this command for chaining
Set the default help group heading for subcommands added to this command. (This does not override a group set directly on the subcommand using .helpGroup().)
this command for chaining
Get the default help group heading for subcommands added to this command.
You can customise the help by overriding Help properties using configureHelp(), or with a subclass of Help by overriding createHelp().
Get configuration
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
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.)
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.
Optionaldescription: stringFactory 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.
Optionalname: stringYou can customise the help with a subclass of Help by overriding createHelp, or by overriding Help properties using configureHelp().
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.
Optionaldescription: stringSet the description.
this command for chaining
Get the description.
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.
Optionalpositional: booleanthis command for chaining
Display error message and exit (or call exitOverride).
OptionalerrorOptions: ErrorOptionsGet the executable search directory.
Register callback to use as replacement for calling process.exit.
Optionalcallback: (err: CommanderError) => voidRetrieve the current invocation context (if any).
Retrieve the merged root CLI options bag (if set by passOptions()). Downstream-safe: no generics required.
Retrieve option value.
Get source of option value.
Get source of option value. See also .optsWithGlobals().
Output help information and exit.
Outputs built-in help, and custom text added using .addHelpText().
Optionalcontext: HelpContextCustomise or override default help command. By default a help command is automatically added if your command has subcommands.
Optionaldescription: stringCustomise or override default help command. By default a help command is automatically added if your command has subcommands.
Set the help group heading for this subcommand in parent command's help.
this command for chaining
Get the help group heading for this subcommand in parent command's help.
Return command help documentation.
Optionalcontext: HelpContextYou 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.
Optionalflags: string | booleanOptionaldescription: stringInstall all registered plugins in parent → children (pre-order). Runs only once per CLI instance.
Set the name of the command.
this command for chaining
Get the name of the command.
Add a listener (callback) for when events occur. (Implemented using EventEmitter.)
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().
Optionaldescription: stringOptionaldefaultValue: string | boolean | string[]this command for chaining
program
.option('-p, --pepper', 'add pepper')
.option('--pt, --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
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().
this command for chaining
program
.option('-p, --pepper', 'add pepper')
.option('--pt, --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
OptionaldefaultValue: string | boolean | string[]Set the default help group heading for options added to this command. (This does not override a group set directly on the option using .helpGroup().)
this command for chaining
Get the default help group heading for options added to this command.
Return an object containing local option values as key-value pairs
Return an object containing merged local and global option values as key-value pairs.
Output help information for this command.
Outputs built-in help, and custom text added using .addHelpText().
Optionalcontext: HelpContextParse 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 argumentsOptionalargv: readonly string[]OptionalparseOptions: ParseOptionsthis command for chaining
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 argumentsOptionalargv: readonly string[]OptionalparseOptions: ParseOptionsPromise
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]
Parse options from argv removing known options,
and return argv split into operands and unknown arguments.
Side effects: modifies command by storing options. Does not reset state if called again.
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], []
Install a preSubcommand hook that merges CLI flags (including parent round-trip) and resolves the dotenv context before executing actions. Defaults come from baseRootOptionDefaults when none are provided.
Optionaldefaults: Partial<RootOptionsShape>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.
OptionalpassThrough: booleanthis command for chaining
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.
Optionaldescription: stringOptionaldefaultValue: string | boolean | string[]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.
OptionaldefaultValue: string | boolean | string[]Resolve options (strict) and compute dotenv context. * Stores the context on the instance under a symbol.
Restore state before parse for calls after the first. Not usually called directly, but available for subclasses to save their custom state.
This is called in a lazy way. Only commands used in parsing chain will have state restored.
Called the first time parse is called to save state and allow a restore before subsequent calls to parse. Not usually called directly, but available for subclasses to save their custom state.
This is called in a lazy way. Only commands used in parsing chain will have state saved.
Store option value.
Store option value and where the value came from.
Display the help or a custom message after an error occurs.
OptionaldisplayHelp: string | booleanDisplay suggestion of similar commands for unknown commands, or options for unknown options.
OptionaldisplaySuggestion: booleanWhether 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().
this command for chaining
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().
this command for chaining
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().
OptionalstoreAsProperties: booleanthis command for chaining
Set the summary. Used when listed as subcommand of parent.
this command for chaining
Get the summary.
Set the command usage.
this command for chaining
Get the command usage.
Register a plugin for installation (parent level). Installation occurs on first resolveAndLoad() (or explicit install()).
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.
Optionalflags: stringOptionaldescription: stringGet the program version.
Plugin-first CLI host for get-dotenv. Extends Commander.Command.
Responsibilities:
NOTE: This host is additive and does not alter the legacy CLI.