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.
Get the arguments as a plain old object.
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.
If the arguments have not been parsed, this property is false.
If the arguments have been parsed, this contain detailed parsed arguments.
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.
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.
Interpret key as a boolean. If a non-flag option follows key in process.argv, that string won't get set as the value of key.
key will default to false, unless a default(key, undefined) is explicitly set.
If key is an array, interpret all the elements as booleans.
Check that certain conditions are met in the provided arguments.
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.
Indicates whether check() should be enabled both at the top-level and for each sub-command.
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().
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
Define the commands exposed by your application.
Should be a string representing the command or an array of strings representing the command and its aliases.
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.
Apply command modules from a directory relative to the module calling this method.
Enable bash/zsh-completion shortcuts for commands and options.
If invoked without parameters, .completion() will make completion the command to output the completion script.
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.
Given the key x is set, the key y must not be set. y can either be a single string or an array of argument names that x conflicts with.
Optionally .conflicts() can accept an object specifying multiple conflicting keys.
Interpret key as a boolean flag, but set its parsed value to the number of flag occurrences rather than true or false. Default value is thus 0.
Set argv[key] to value if no option was specified in process.argv.
Optionally .default() can take an object that maps keys to default values.
The default value can be a function which returns a value. The name of the function will be used in the usage string.
Optionally, description can also be provided and will take precedence over displaying the value in the usage instructions.
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.
If is a string, show the usage information and exit if key wasn't specified in process.argv.
If is an array, demand each element.
If string is given, it will be printed when the argument is missing, instead of the standard error message.
Describe a key for the generated usage information.
Optionally .describe() can take an object that maps keys to descriptions.
Should yargs attempt to detect the os' locale? Defaults to true.
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_nestedfoo => 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:
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.
A message to print at the end of the usage instructions
A message to print at the end of the usage instructions
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.
Manually indicate that the program should exit, and provide context about why we wanted to exit. Follows the behavior set by .exitProcess().
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.
Method to execute when a failure occurs, rather than printing the failure message.
Is called with the failure message that would have been printed, the Error instance originally thrown and yargs state when the failure occurred.
Allows to programmatically get completion choices for any line.
An array of the words in the command line to complete.
The callback to be called with the resulting completions.
Indicate that an option (or group of options) should not be reset when a command is executed
Options default to being global.
Given a key, or an array of keys, places options under an alternative heading when displaying usage instructions
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.
Hides a key from the generated usage information. Unless a --show-hidden option is also passed with --help (see showHidden()).
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.
Return the locale that yargs is currently using.
By default, yargs will auto-detect the operating system's locale so that yargs-generated help content will display in the user's language.
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.
Define global middleware functions to be called first, in list order, for all cli command.
Can be a function or a list of functions. Each callback gets passed a reference to argv.
The key provided represents a path and should have path.normalize() applied.
Tell the parser to always interpret key as a number.
If key is an array, all elements will be parsed as numbers.
If the option is given on the command line without a value, argv will be populated with undefined.
If the value given on the command line cannot be parsed as a number, argv will be populated with NaN.
Note that decimals, hexadecimals, and scientific notation are all accepted.
Method to execute when a command finishes successfully.
Is called with the successful result of the command that finished.
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 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 to configure advanced yargs features.
Similar to config(), indicates that yargs should interpret the object from the specified key in package.json as a configuration object.
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.
Should yargs provide suggestions regarding similar commands if no matching command is found?
Set the name of your script ($0). Default is the base filename executed by node (process.argv[1])
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.
Print the usage data using the console function consoleLevel for printing.
By default, yargs outputs a usage string if any error is detected.
Use the .showHelpOnFail() method to customize this behavior.
If false, the usage string is not output.
Configure the --show-hidden option that displays the hidden keys (see hide()).
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").
Specifies either a single option key (string), or an array of options. If any of the options is present, yargs validation is skipped.
Tell the parser logic not to interpret key as a number or boolean. This can be useful if you need to preserve leading zeros in an input.
If key is an array, interpret all the elements as strings.
.string('_') will result in non-hyphenated arguments being interpreted as strings, regardless of whether they resemble numbers.
Override the default strings used by yargs with the key/value pairs provided in obj
If you explicitly specify a locale(), you should do so before calling updateStrings().
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.