commander
- Version 13.0.0
- Published
- 199 kB
- No dependencies
- MIT license
Install
npm i commander
yarn add commander
pnpm add commander
Overview
the complete solution for node.js command-line programs
Index
Variables
Functions
Classes
Command
- action()
- addArgument()
- addCommand()
- addHelpCommand()
- addHelpOption()
- addHelpText()
- addOption()
- alias()
- aliases()
- allowExcessArguments()
- allowUnknownOption()
- args
- argument()
- arguments()
- combineFlagAndOptionalValue()
- command()
- commands
- configureHelp()
- configureOutput()
- copyInheritedSettings()
- createArgument()
- createCommand()
- createHelp()
- createOption()
- description()
- enablePositionalOptions()
- error()
- executableDir()
- exitOverride()
- getOptionValue()
- getOptionValueSource()
- getOptionValueSourceWithGlobals()
- help()
- helpCommand()
- helpInformation()
- helpOption()
- hook()
- name()
- nameFromFilename()
- on()
- option()
- options
- opts()
- optsWithGlobals()
- outputHelp()
- parent
- parse()
- parseAsync()
- parseOptions()
- passThroughOptions()
- processedArgs
- registeredArguments
- requiredOption()
- restoreStateBeforeParse()
- saveStateBeforeParse()
- setOptionValue()
- setOptionValueWithSource()
- showHelpAfterError()
- showSuggestionAfterError()
- storeOptionsAsProperties()
- summary()
- usage()
- version()
Help
- argumentDescription()
- argumentTerm()
- boxWrap()
- commandDescription()
- commandUsage()
- displayWidth()
- formatHelp()
- formatItem()
- helpWidth
- longestArgumentTermLength()
- longestGlobalOptionTermLength()
- longestOptionTermLength()
- longestSubcommandTermLength()
- minWidthToWrap
- optionDescription()
- optionTerm()
- padWidth()
- preformatted()
- prepareContext()
- showGlobalOptions
- sortOptions
- sortSubcommands
- styleArgumentDescription()
- styleArgumentTerm()
- styleArgumentText()
- styleCommandDescription()
- styleCommandText()
- styleDescriptionText()
- styleOptionDescription()
- styleOptionTerm()
- styleOptionText()
- styleSubcommandDescription()
- styleSubcommandTerm()
- styleSubcommandText()
- styleTitle()
- styleUsage()
- subcommandDescription()
- subcommandTerm()
- visibleArguments()
- visibleCommands()
- visibleGlobalOptions()
- visibleOptions()
Interfaces
Type Aliases
Variables
variable program
const program: Command;
Functions
function createArgument
createArgument: (name: string, description?: string) => Argument;
function createCommand
createCommand: (name?: string) => Command;
function createOption
createOption: (flags: string, description?: string) => Option;
Classes
class Argument
class Argument {}
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.
class Command
class Command {}
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: (this: this, ...args: any[]) => void | Promise<void>) => this;
Register callback
fn
for the command.Returns
this
command for chainingExample 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 chainingGet 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 chainingGet 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 chainingExample 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 chainingExample 1
program.arguments('<cmd> [env]');
method combineFlagAndOptionalValue
combineFlagAndOptionalValue: (combine?: boolean) => this;
Alter parsing of short flags with optional values.
Returns
this
command for chainingExample 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 bevariadic...
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 bevariadic...
Parameter description
description of executable command
Parameter opts
configuration options
Returns
this
command for chainingRemarks
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 stderrwriteOut(str)writeErr(str)// matching functions to specify width for wrapping helpgetOutHelpWidth()getErrHelpWidth()// functions based on what is being written outoutputError(str, write) // used for displaying errors, and not used for displaying helpGet 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 chainingDeprecated
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 chainingExample 1
program.executableDir(__dirname);// orprogram.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 commandprogram.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 chainingGet 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 chainingExample 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 ordefaultValue
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 chainingExample 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 functionDeprecated
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 likenode --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 andargv[1]
is the script being run, with user arguments after that -'electron'
:argv[0]
is the application andargv[1]
varies depending on whether the electron application is packaged -'user'
: just user argumentsReturns
this
command for chainingExample 1
program.parse(); // parse process.argv and auto-detect electron and special node flagsprogram.parse(process.argv); // assume argv[0] is app and argv[1] is scriptprogram.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 likenode --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 andargv[1]
is the script being run, with user arguments after that -'electron'
:argv[0]
is the application andargv[1]
varies depending on whether the electron application is packaged -'user'
: just user argumentsReturns
Promise
Example 1
await program.parseAsync(); // parse process.argv and auto-detect electron and special node flagsawait program.parseAsync(process.argv); // assume argv[0] is app and argv[1] is scriptawait 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.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], []
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 restoreStateBeforeParse
restoreStateBeforeParse: () => void;
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.
method saveStateBeforeParse
saveStateBeforeParse: () => void;
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.
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 chainingGet the summary.
method usage
usage: { (str: string): this; (): string };
Set the command usage.
Returns
this
command for chainingGet 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.
class CommanderError
class CommanderError extends Error {}
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;
class Help
class Help {}
constructor
constructor();
property helpWidth
helpWidth?: number;
output helpWidth, long lines are wrapped to fit
property minWidthToWrap
minWidthToWrap: number;
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 boxWrap
boxWrap: (str: string, width: number) => string;
Wrap a string at whitespace, preserving existing line breaks. Wrapping is skipped if the width is less than
minWidthToWrap
.
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 displayWidth
displayWidth: (str: string) => number;
Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations.
method formatHelp
formatHelp: (cmd: Command, helper: Help) => string;
Generate the built-in help text.
method formatItem
formatItem: ( term: string, termWidth: number, description: string, helper: Help) => string;
Format the "item", which consists of a term and description. Pad the term and wrap the description, indenting the following lines.
So "TTT", 5, "DDD DDDD DD DDD" might be formatted for this.helpWidth=17 like so: TTT DDD DDDD DD DDD
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 preformatted
preformatted: (str: string) => boolean;
Detect manually wrapped and indented strings by checking for line break followed by whitespace.
method prepareContext
prepareContext: (contextOptions: { error?: boolean; helpWidth?: number; outputHasColors?: boolean;}) => void;
method styleArgumentDescription
styleArgumentDescription: (str: string) => string;
method styleArgumentTerm
styleArgumentTerm: (str: string) => string;
method styleArgumentText
styleArgumentText: (str: string) => string;
Base style used in terms and usage for arguments.
method styleCommandDescription
styleCommandDescription: (str: string) => string;
method styleCommandText
styleCommandText: (str: string) => string;
Style for command name in usage string.
method styleDescriptionText
styleDescriptionText: (str: string) => string;
Base style used by descriptions.
method styleOptionDescription
styleOptionDescription: (str: string) => string;
method styleOptionTerm
styleOptionTerm: (str: string) => string;
method styleOptionText
styleOptionText: (str: string) => string;
Base style used in terms and usage for options.
method styleSubcommandDescription
styleSubcommandDescription: (str: string) => string;
method styleSubcommandTerm
styleSubcommandTerm: (str: string) => string;
method styleSubcommandText
styleSubcommandText: (str: string) => string;
Base style used in terms and usage for subcommands.
method styleTitle
styleTitle: (title: string) => string;
Style the titles. Called with 'Usage:', 'Options:', etc.
method styleUsage
styleUsage: (str: string) => string;
Usage:
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.
class InvalidArgumentError
class InvalidArgumentError extends CommanderError {}
constructor
constructor(message: string);
Constructs the InvalidArgumentError class
Parameter message
explanation of why argument is invalid
class InvalidOptionArgumentError
class InvalidArgumentError extends CommanderError {}
constructor
constructor(message: string);
Constructs the InvalidArgumentError class
Parameter message
explanation of why argument is invalid
class Option
class Option {}
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 an 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);
Interfaces
interface AddHelpTextContext
interface AddHelpTextContext {}
interface CommandOptions
interface CommandOptions {}
interface ErrorOptions
interface ErrorOptions {}
interface ExecutableCommandOptions
interface ExecutableCommandOptions extends CommandOptions {}
property executableFile
executableFile?: string;
interface HelpContext
interface HelpContext {}
property error
error: boolean;
interface OutputConfiguration
interface OutputConfiguration {}
method getErrHasColors
getErrHasColors: () => boolean;
method getErrHelpWidth
getErrHelpWidth: () => number;
method getOutHasColors
getOutHasColors: () => boolean;
method getOutHelpWidth
getOutHelpWidth: () => number;
method outputError
outputError: (str: string, write: (str: string) => void) => void;
method stripColor
stripColor: (str: string) => string;
method writeErr
writeErr: (str: string) => void;
method writeOut
writeOut: (str: string) => void;
interface ParseOptions
interface ParseOptions {}
property from
from: 'node' | 'electron' | 'user';
interface ParseOptionsResult
interface ParseOptionsResult {}
Type Aliases
type AddHelpTextPosition
type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
type HelpConfiguration
type HelpConfiguration = Partial<Help>;
type HookEvent
type HookEvent = 'preSubcommand' | 'preAction' | 'postAction';
type OptionValues
type OptionValues = Record<string, any>;
type OptionValueSource
type OptionValueSource = | LiteralUnion<'default' | 'config' | 'env' | 'cli' | 'implied', string> | undefined;
Package Files (1)
Dependencies (0)
No dependencies.
Dev Dependencies (13)
Peer Dependencies (0)
No peer dependencies.
Badge
To add a badge like this oneto your package's README, use the codes available below.
You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/commander
.
- Markdown[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/commander)
- HTML<a href="https://www.jsdocs.io/package/commander"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>
- Updated .
Package analyzed in 4866 ms. - Missing or incorrect documentation? Open an issue for this package.