The type parameter T is the expected shape of the parsed options.
Arguments<T> is those options plus _ and $0, and an indexer falling
back to unknown for unknown options.
For the return type / argv property, we create a mapped type over
Arguments<T> to simplify the inferred type signature in client code.
The type parameter T is the expected shape of the parsed options.
Arguments<T> is those options plus _ and $0, and an indexer falling
back to unknown for unknown options.
For the return type / argv property, we create a mapped type over
Arguments<T> to simplify the inferred type signature in client code.
Arguments without a corresponding flag show up in the argv._ array.
The script name or node command is available at argv.$0 similarly to how $0 works in bash or perl.
If yargs is executed in an environment that embeds node and there's no script name (e.g. Electron or nw.js),
it will ignore the first parameter since it expects it to be the script name. In order to override
this behavior, use .parse(process.argv.slice(1)) instead of .argv and the first parameter won't be ignored.
Set key names as equivalent such that updates to a key will propagate to aliases and vice-versa.
Optionally .alias() can take an object that maps keys to aliases.
Each key of this object should be the canonical version of the option, and each value should be a string or an array of strings.
array<K>(key: K | readonly K[]): Argv<Omit<T, K> & {[ key in string | number | symbol]: ToArray<T[key]> }>
array<K>(key: K | readonly K[]): Argv<T & {[ key in string]: undefined | (string | number)[] }>
Tell the parser to interpret key as an array.
If .array('foo') is set, --foo foo bar will be parsed as ['foo', 'bar'] rather than as 'foo'.
Also, if you use the option multiple times all the values will be flattened in one array so --foo foo --foo bar will be parsed as ['foo', 'bar']
When the option is used with a positional, use -- to tell yargs to stop adding values to the array.
Type parameters
K: string | number | symbol
Parameters
key: K | readonly K[]
Returns Argv<Omit<T, K> & {[ key in string | number | symbol]: ToArray<T[key]> }>
Called with two arguments, the parsed argv hash and an array of options and their aliases.
If func throws or returns a non-truthy value, show the thrown error, usage information, and exit.
choices<C>(choices: C): Argv<Omit<T, keyof C> & {[ key in string | number | symbol]: undefined | C[key][number] }>
Limit valid values for key to a predefined set of choices, given as an array or as an individual value.
If this method is called multiple times, all enumerated values will be merged together.
Choices are generally strings or numbers, and value matching is case-sensitive.
Optionally .choices() can take an object that maps multiple keys to their choices.
Choices can also be specified as choices in the object given to option().
Type parameters
K: string | number | symbol
C: readonly any[]
Parameters
key: K
values: C
Returns Argv<Omit<T, K> & {[ key in string | number | symbol]: undefined | C[number] }>
Returns Argv<Omit<T, keyof C> & {[ key in string | number | symbol]: undefined | C[key][number] }>
coerce
coerce<K, V>(key: K | readonly K[], func: (arg: any) => V): Argv<Omit<T, K> & {[ key in string | number | symbol]: undefined | V }>
coerce<K, V>(key: K | readonly K[], func: (arg: any) => V): Argv<T & {[ key in string]: undefined | V }>
coerce<O>(opts: O): Argv<Omit<T, keyof O> & {[ key in string | number | symbol]: undefined | ReturnType<O[key]> }>
Provide a synchronous function to coerce or transform the value(s) given on the command line for key.
The coercion function should accept one argument, representing the parsed value from the command line, and should return a new value or throw an error.
The returned value will be used as the value for key (or one of its aliases) in argv.
If the function throws, the error will be treated as a validation failure, delegating to either a custom .fail() handler or printing the error message in the console.
Coercion will be applied to a value after all other modifications, such as .normalize().
Optionally .coerce() can take an object that maps several keys to their respective coercion function.
You can also map the same function to several keys at one time. Just pass an array of keys as the first argument to .coerce().
If you are using dot-notion or arrays, .e.g., user.email and user.password, coercion will be applied to the final object that has been parsed
Type parameters
K: string | number | symbol
V
Parameters
key: K | readonly K[]
func: (arg: any) => V
(arg: any): V
Parameters
arg: any
Returns V
Returns Argv<Omit<T, K> & {[ key in string | number | symbol]: undefined | V }>
Type parameters
K: string
V
Parameters
key: K | readonly K[]
func: (arg: any) => V
(arg: any): V
Parameters
arg: any
Returns V
Returns Argv<T & {[ key in string]: undefined | V }>
Type parameters
O: {}
Parameters
opts: O
Returns Argv<Omit<T, keyof O> & {[ key in string | number | symbol]: undefined | ReturnType<O[key]> }>
Should be a string representing the command or an array of strings representing the command and its aliases.
description: string
Use to provide a description for each command your application accepts (the values stored in argv._).
Set description to false to create a hidden command. Hidden commands don't show up in the help output and aren't available for completion.
Tells the parser that if the option specified by key is passed in, it should be interpreted as a path to a JSON config file.
The file is loaded and parsed, and its properties are set as arguments.
Because the file is loaded using Node's require(), the filename MUST end in .json to be interpreted correctly.
If invoked without parameters, .config() will make --config the option to pass the JSON config file.
Demand in context of commands.
You can demand a minimum and a maximum number a user can have within your program, as well as provide corresponding error messages if either of the demands is not met.
Tell yargs to parse environment variables matching the given prefix and apply them to argv as though they were command line arguments.
Use the "__" separator in the environment variable to indicate nested options. (e.g. prefix_nested__foo => nested.foo)
If this method is called with no argument or with an empty string or with true, then all env vars will be applied to argv.
Program arguments are defined in this order of precedence:
Command line args
Env vars
Config file/objects
Configured defaults
Env var parsing is disabled by default, but you can also explicitly disable it by calling .env(false), e.g. if you need to undo previous configuration.
Give some example invocations of your program.
Inside cmd, the string $0 will get interpolated to the current script name or node command for the present script similar to how $0 works in bash or perl.
Examples will be printed out as part of the help message.
By default, yargs exits the process when the user passes a help flag, the user uses the .version functionality, validation fails, or the command handler fails.
Calling .exitProcess(false) disables this behavior, enabling further actions after yargs have been validated.
Configure an (e.g. --help) and implicit command that displays the usage string and exits the process.
By default yargs enables help on the --help option.
Note that any multi-char aliases (e.g. help) used for the help option will also be used for the implicit command.
If there are no multi-char aliases (e.g. h), then all single-char aliases will be used for the command.
If invoked without parameters, .help() will use --help as the option and help as the implicit command to trigger help output.
Given the key x is set, it is required that the key y is set.
ycan either be the name of an argument to imply, a number indicating the position of an argument or an array of multiple implications to associate withx`.
Optionally .implies() can accept an object specifying multiple implications.
By default, yargs will auto-detect the operating system's locale so that yargs-generated help content will display in the user's language.
Returns string
Override the auto-detected locale from the user's operating system with a static locale.
Note that the OS locale can be modified by setting/exporting the LC_ALL environment variable.
This method can be used to make yargs aware of options that could exist.
You can also pass an opt object which can hold further customization, like .alias(), .demandOption() etc. for that option.
This method can be used to make yargs aware of options that could exist.
You can also pass an opt object which can hold further customization, like .alias(), .demandOption() etc. for that option.
parse(arg: string | readonly string[], context?: object, parseCallback?: ParseCallback<T>): {[ key in string | number | symbol as key | CamelCaseKey<key>]: Arguments<T>[key] } | Promise<{[ key in string | number | symbol as key | CamelCaseKey<key>]: Arguments<T>[key] }>
Parse args instead of process.argv. Returns the argv object. args may either be a pre-processed argv array, or a raw argument string.
Note: Providing a callback to parse() disables the exitProcess setting until after the callback is invoked.
Allows you to configure a command's positional arguments with an API similar to .option().
.positional() should be called in a command's builder function, and is not available on the top-level yargs instance. If so, it will throw an error.
Generate a bash completion script.
Users of your application can install this script in their .bashrc, and yargs will provide completion shortcuts for commands and options.
Configure the --show-hidden option that displays the hidden keys (see hide()).
Parameters
Optional option: string | boolean
If boolean, it enables/disables this option altogether. i.e. hidden keys will be permanently hidden if first argument is false.
If string it changes the key name ("--show-hidden").
Similar to .strict(), except that it only applies to unrecognized commands.
A user can still provide arbitrary options, but unknown positional commands
will raise an error.
Similar to .strict(), except that it only applies to unrecognized options. A
user can still provide arbitrary positional options, but unknown options
will raise an error.
Set a usage message to show which commands to use.
Inside message, the string $0 will get interpolated to the current script name or node command for the present script similar to how $0 works in bash or perl.
If the optional description/builder/handler are provided, .usage() acts an an alias for .command().
This allows you to use .usage() to configure the default command that will be run as an entry-point to your application
and allows you to provide configuration for the positional arguments accepted by your program:
Add an option (e.g. --version) that displays the version number (given by the version parameter) and exits the process.
By default yargs enables version for the --version option.
If no arguments are passed to version (.version()), yargs will parse the package.json of your module and use its version value.
If the boolean argument false is provided, it will disable --version.
Format usage output to wrap at columns many columns.
By default wrap will be set to Math.min(80, windowWidth). Use .wrap(null) to specify no column limit (no right-align).
Use .wrap(yargs.terminalWidth()) to maximize the width of yargs' usage instructions.
The type parameter
Tis the expected shape of the parsed options.Arguments<T>is those options plus_and$0, and an indexer falling back tounknownfor unknown options.For the return type /
argvproperty, we create a mapped type overArguments<T>to simplify the inferred type signature in client code.