# burgee/yargs/v17 > Every export of burgee/yargs/v17, with its signature and doc comment: applyExtends, argsert, camelCase, decamelize, hideBin, isPromise and 8 more, plus 32 types. Source: https://burgee.interlace.tools/docs/api/yargs/v17 `burgee/yargs/v17` — `burgee/yargs` for a program on yargs 17, the entry `burgee migrate` writes for one (`previous-majors` R3, R4). `import` reaches this file: 17's `index.mjs`, the factory, with 17's string table and `commandDir()` (`v17-factory.ts`). `require()` reaches `v17.cjs`, 17's singleton. ```ts import Yargs17 from 'burgee/yargs/v17'; import { applyExtends, argsert, camelCase, … } from 'burgee/yargs/v17'; ``` ## Functions ### applyExtends `extends` in a config object. The upstream resolves a bare specifier with `import.meta.resolve` and then loads it through `require`; both are done from here. ```ts function applyExtends(config: Record, cwd: string, mergeExtends?: boolean): Record; ``` | Parameter | Type | | :-- | :-- | | `config` | `Record` | | `cwd` | `string` | | `mergeExtends` (optional) | `boolean` | **Returns** `Record` ### argsert ```ts function argsert(arg1: string | any[], arg2?: any, arg3?: number): void; ``` | Parameter | Type | | :-- | :-- | | `arg1` | `string \| any[]` | | `arg2` (optional) | `any` | | `arg3` (optional) | `number` | **Returns** `void` ### camelCase ```ts function camelCase(str: string): string; ``` | Parameter | Type | | :-- | :-- | | `str` | `string` | **Returns** `string` ### decamelize ```ts function decamelize(str: string, joinString?: string): string; ``` | Parameter | Type | | :-- | :-- | | `str` | `string` | | `joinString` (optional) | `string` | **Returns** `string` ### hideBin ```ts function hideBin(argv: string[]): string[]; ``` | Parameter | Type | | :-- | :-- | | `argv` | `string[]` | **Returns** `string[]` ### isPromise ```ts function isPromise(maybePromise: any): maybePromise is Promise; ``` | Parameter | Type | | :-- | :-- | | `maybePromise` | `any` | **Returns** `maybePromise is Promise` ### isYargsInstance ```ts function isYargsInstance(y: any): y is YargsInstance; ``` | Parameter | Type | | :-- | :-- | | `y` | `any` | **Returns** `y is YargsInstance` ### looksLikeNumber ```ts function looksLikeNumber(x: any): boolean; ``` | Parameter | Type | | :-- | :-- | | `x` | `any` | **Returns** `boolean` ### objFilter ```ts function objFilter(original?: T, filter?: (k: string, v: any) => boolean): T; ``` | Parameter | Type | | :-- | :-- | | `original` (optional) | `T` | | `filter` (optional) | `(k: string, v: any) => boolean` | **Returns** `T` ### parseCommand ```ts function parseCommand(cmd: string): ParsedCommand; ``` | Parameter | Type | | :-- | :-- | | `cmd` | `string` | **Returns** `ParsedCommand` ## Classes ### YargsInstance ```ts class YargsInstance { #private; $0: string; argv?: any; customScriptName: boolean; parsed: any; constructor(processArgs: string | string[] | undefined, cwd: string, parentRequire: NodeJS.Require | undefined, shim: PlatformShim); addHelpOpt(opt?: string | false, msg?: string): this; help(opt?: string | false, msg?: string): this; addShowHiddenOpt(opt?: string | false, msg?: string): this; showHidden(opt?: string | false, msg?: string): this; alias(key: string | string[] | Record, value?: string | string[]): this; array(keys: string | string[]): this; boolean(keys: string | string[]): this; check(f: (argv: any, options: Options) => any, global?: boolean): this; choices(key: string | string[] | Record, value?: any): this; coerce(keys: string | string[] | Record any>, value?: (arg: any) => any): this; conflicts(key1: string | Record, key2?: string | string[]): this; config(key?: string | string[] | Record, msg?: string | ((path: string) => any), parseFn?: (path: string) => any): this; completion(cmd?: string, desc?: string | false | CompletionFunction, fn?: CompletionFunction): this; command(cmd: any, description?: any, builder?: any, handler?: any, middlewares?: Middleware[], deprecated?: boolean | string): this; commands(cmd: any, description?: any, builder?: any, handler?: any, middlewares?: Middleware[], deprecated?: boolean | string): this; commandDir(dir: string, opts?: any): this; count(keys: string | string[]): this; default(key: string | string[] | Record, value?: any, defaultDescription?: string): this; defaults(key: string | string[] | Record, value?: any, defaultDescription?: string): this; demandCommand(min?: number, max?: number | string | null, minMsg?: string | null, maxMsg?: string | null): this; demand(keys: string | string[] | number | Record, max?: number | string | string[] | boolean, msg?: string | boolean): this; demandOption(keys: string | string[] | Record, msg?: string): this; deprecateOption(option: string, message?: string | boolean): this; describe(keys: string | string[] | Record, description?: string): this; detectLocale(detect: boolean): this; env(prefix?: string | false): this; epilogue(msg: string): this; epilog(msg: string): this; example(cmd: string | [string, string?][], description?: string): this; exit(code: number, err?: YError | string): void; exitProcess(enabled?: boolean): this; fail(f: FailureFunction | boolean): this; getAliases(): Record; getCompletion(args: string[], done?: (err: Error | null, completions: string[] | undefined) => void): Promise; getDemandedOptions(): Record; getDemandedCommands(): Options['demandedCommands']; getDeprecatedOptions(): Options['deprecatedOptions']; getDetectLocale(): boolean; getExitProcess(): boolean; getGroups(): Record; getHelp(): Promise; getOptions(): Options; getStrict(): boolean; getStrictCommands(): boolean; getStrictOptions(): boolean; global(globals: string | string[], global?: boolean): this; group(opts: string | string[], groupName: string): this; hide(key: string): this; implies(key: string | Record, value?: number | string | string[]): this; locale(locale?: string): this | string; middleware(callback: Middleware | Middleware[], applyBeforeValidation?: boolean, global?: boolean): this; nargs(key: string | string[] | Record, value?: number): this; normalize(keys: string | string[]): this; number(keys: string | string[]): this; option(key: string | Record, opt?: any): this; options(key: string | Record, opt?: any): this; parse(args?: string | string[], shortCircuit?: object | ParseCallback | boolean, _parseFn?: ParseCallback): any; parseAsync(args?: string | string[], shortCircuit?: object | ParseCallback | boolean, _parseFn?: ParseCallback): Promise; parseSync(args?: string | string[], shortCircuit?: object | ParseCallback | boolean, _parseFn?: ParseCallback): any; parserConfiguration(config: Record): this; pkgConf(key: string, rootPath?: string): this; positional(key: string, opts: Record): this; recommendCommands(recommend?: boolean): this; required(keys: string | string[] | number | Record, max?: number | string | string[] | boolean, msg?: string | boolean): this; require(keys: string | string[] | number | Record, max?: number | string | string[] | boolean, msg?: string | boolean): this; requiresArg(keys: string | string[] | Record): this; showCompletionScript($0?: string, cmd?: string): this; showHelp(level?: 'error' | 'log' | ((message: string) => void)): this; scriptName(scriptName: string): this; showHelpOnFail(enabled?: string | boolean, message?: string): this; showVersion(level?: 'error' | 'log' | ((message: string) => void)): this; skipValidation(keys: string | string[]): this; strict(enabled?: boolean): this; strictCommands(enabled?: boolean): this; strictOptions(enabled?: boolean): this; string(keys: string | string[]): this; terminalWidth(): number | null; updateLocale(obj: Record): this; updateStrings(obj: Record): this; usage(msg: string | null, description?: string | false, builder?: any, handler?: any): this; usageConfiguration(config: Record): this; version(opt?: string | false, msg?: string, ver?: string): this; wrap(cols: number | null | undefined): this; getInternalMethods(): { getCommandInstance: () => CommandInstance; getContext: () => Context; getHasOutput: () => boolean; getLoggerInstance: () => Logger; getParseContext: () => object; getParserConfiguration: () => Record; getUsageConfiguration: () => Record; getUsageInstance: () => UsageInstance; getValidationInstance: () => ValidationInstance; hasParseCallback: () => boolean; isGlobalContext: () => boolean; postProcess: (argv: any, populateDoubleDash: boolean, calledFromCommand: boolean, runGlobalMiddleware: boolean) => any; reset: (aliases?: Record) => YargsInstance; runValidation: (aliases: Record, positionalMap: Record, parseErrors: Error | null, isDefaultCommand?: boolean) => (argv: any) => void; runYargsParserAndExecuteCommands: (args: string | string[] | null, shortCircuit?: boolean, calledFromCommand?: boolean, commandIndex?: number, helpOnly?: boolean) => any; setHasOutput: () => void; runHandler: (handler: (argv: any) => any, argv: any, original: string) => any; }; /** * The manifest every surface reads (J7, J8). Projected on each access from what the * program registered; a command's builder is run on a scratch instance to learn its * options, exactly as yargs' own completion does. Plugin-contributed nodes are kept. */ get manifest(): Manifest; /** burgee: declare what the command does to the world (N6); what exposes it as an MCP tool (N2). */ effects(value: DeclaredEffects): this; /** Additive: plugins yargs never had. `preRun`/`postRun` fire around every handler. */ use(plugin: Plugin): this; /** * Inject the streams and the exit for this instance (T1). Output goes to `stdout`/`stderr` * instead of the console, and `exit` receives an E1 code: OK for help and version, USAGE * for a validation failure, RUNTIME for a handler that threw. */ burgee({ floor, ...seam }: BurgeeSeam): this; } ``` ### YError yargs' small internal modules — yerror, parse-command, argsert, obj-filter, is-promise, levenshtein, maybe-async-result, set-blocking, apply-extends, process-argv — ported for `burgee/yargs`. Its suite imports four of these by their upstream file paths; the oracle shims those paths to this entry, so the names here are the upstream names. ```ts class YError extends Error { constructor(msg?: string | null); } ``` ## Constants ### default The default export, declared as `Yargs17`. 17's `index.mjs`: the factory, over a string table of its own (`v17-factory.ts`). ```ts const Yargs17: typeof Yargs; ``` ### platformShim ```ts const shim: PlatformShim; ``` ## Interfaces ### Argv The type parameter `T` is the expected shape of the parsed options. `Arguments` is those options plus `_` and `$0`, and an indexer falling back to `unknown` for unknown options. ```ts interface Argv { /** * Set key names as equivalent such that updates to a key will propagate to aliases and vice-versa. */ alias(shortName: K1, longName: K2 | readonly K2[]): Argv; alias(shortName: K2, longName: K1 | readonly K1[]): Argv; alias(shortName: string | readonly string[], longName: string | readonly string[]): Argv; alias(aliases: { [shortName: string]: string | readonly string[]; }): Argv; /** * Get the arguments as a plain old object. */ argv: { [key in keyof Arguments as key | CamelCaseKey]: Arguments[key]; } | Promise<{ [key in keyof Arguments as key | CamelCaseKey]: Arguments[key]; }>; /** * 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']` */ array(key: K | readonly K[]): Argv & { [key in K]: ToArray; }>; array(key: K | readonly K[]): Argv | undefined; }>; /** * 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`. */ boolean(key: K | readonly K[]): Argv & { [key in K]: boolean | undefined; }>; boolean(key: K | readonly K[]): Argv; /** * Check that certain conditions are met in the provided arguments. * @param func 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. * @param global Indicates whether `check()` should be enabled both at the top-level and for each sub-command. */ check(func: (argv: Arguments, aliases: { [alias: string]: string; }) => any, global?: boolean): Argv; /** * 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. */ choices(key: K, values: C): Argv & { [key in K]: C[number] | undefined; }>; choices(key: K, values: C): Argv; choices(choices: C): Argv & { [key in keyof C]: C[key][number] | undefined; }>; /** * Provide a synchronous function to coerce or transform the value(s) given on the command line for `key`. */ coerce(key: K | readonly K[], func: (arg: any) => V): Argv & { [key in K]: V | undefined; }>; coerce(key: K | readonly K[], func: (arg: any) => V): Argv; coerce any; }>(opts: O): Argv & { [key in keyof O]: ReturnType | undefined; }>; /** * Define the commands exposed by your application. * @param command Should be a string representing the command or an array of strings representing the command and its aliases. * @param description 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. * @param [builder] Object to give hints about the options that your command accepts. * Can also be a function. This function is executed with a yargs instance, and can be used to provide advanced command specific help. * * Note that when `void` is returned, the handler `argv` object type will not include command-specific arguments. * @param [handler] Function, which will be executed with the parsed `argv` object. */ command(command: string | readonly string[], description: string, builder?: BuilderCallback, handler?: (args: ArgumentsCamelCase) => unknown, middlewares?: Array>, deprecated?: boolean | string): Argv; command(command: string | readonly string[], description: string, builder?: O, handler?: (args: ArgumentsCamelCase>) => unknown, middlewares?: Array>, deprecated?: boolean | string): Argv; command(command: string | readonly string[], description: string, module: CommandModule): Argv; command(command: string | readonly string[], showInHelp: false, builder?: BuilderCallback, handler?: (args: ArgumentsCamelCase) => unknown, middlewares?: Array>, deprecated?: boolean | string): Argv; command(command: string | readonly string[], showInHelp: false, builder?: O, handler?: (args: ArgumentsCamelCase>) => unknown): Argv; command(command: string | readonly string[], showInHelp: false, module: CommandModule): Argv; command(module: CommandModule): Argv; command(modules: Array>): Argv; /** Apply command modules from a directory relative to the module calling this method. */ commandDir(dir: string, opts?: RequireDirectoryOptions): Argv; /** * Enable bash/zsh-completion shortcuts for commands and options. * @param [cmd] When present in `argv._`, will result in the `.bashrc` or `.zshrc` completion script being outputted. * To enable bash/zsh completions, concat the generated script to your `.bashrc` or `.bash_profile` (or `.zshrc` for zsh). * @param [description] Provide a description in your usage instructions for the command that generates the completion scripts. * @param [func] Rather than relying on yargs' default completion functionality, which shiver me timbers is pretty awesome, you can provide your own completion method. */ completion(): Argv; completion(cmd: string, func?: AsyncCompletionFunction): Argv; completion(cmd: string, func?: SyncCompletionFunction): Argv; completion(cmd: string, func?: PromiseCompletionFunction): Argv; completion(cmd: string, func?: FallbackCompletionFunction): Argv; completion(cmd: string, description?: string | false, func?: AsyncCompletionFunction): Argv; completion(cmd: string, description?: string | false, func?: SyncCompletionFunction): Argv; completion(cmd: string, description?: string | false, func?: PromiseCompletionFunction): Argv; completion(cmd: string, description?: string | false, func?: FallbackCompletionFunction): Argv; /** * 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. * @param [description] Provided to customize the config (`key`) option in the usage string. * @param [explicitConfigurationObject] An explicit configuration `object` */ config(): Argv; config(key: string | readonly string[], description?: string, parseFn?: (configPath: string) => object): Argv; config(key: string | readonly string[], parseFn: (configPath: string) => object): Argv; config(explicitConfigurationObject: object): Argv; /** * 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. */ conflicts(key: string, value: string | readonly string[]): Argv; conflicts(conflicts: { [key: string]: string | readonly string[]; }): Argv; /** * 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`. */ count(key: K | readonly K[]): Argv & { [key in K]: number; }>; count(key: K | readonly K[]): Argv; /** * Set `argv[key]` to `value` if no option was specified in `process.argv`. */ default(key: K, value: V, description?: string): Argv & { [key in K]: V; }>; default(key: K, value: V, description?: string): Argv; default(defaults: D, description?: string): Argv & D>; /** * @deprecated since version 6.6.0 * Use '.demandCommand()' or '.demandOption()' instead */ demand(key: K | readonly K[], msg?: string | true): Argv>; demand(key: K | readonly K[], msg?: string | true): Argv; demand(key: string | readonly string[], required?: boolean): Argv; demand(positionals: number, msg: string): Argv; demand(positionals: number, required?: boolean): Argv; demand(positionals: number, max: number, msg?: string): Argv; /** * @param key 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. * @param msg If string is given, it will be printed when the argument is missing, instead of the standard error message. * @param demand Controls whether the option is demanded; this is useful when using .options() to specify command line parameters. */ demandOption(key: K | readonly K[], msg?: string | true): Argv>; demandOption(key: K | readonly K[], msg?: string | true): Argv; demandOption(key: string | readonly string[], demand?: boolean): Argv; /** * 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. */ demandCommand(): Argv; demandCommand(min: number, minMsg?: string): Argv; demandCommand(min: number, max?: number, minMsg?: string, maxMsg?: string): Argv; /** * Shows a [deprecated] notice in front of the option */ deprecateOption(option: string, msg?: string): Argv; /** * Describe a `key` for the generated usage information. */ describe(key: string | readonly string[], description: string): Argv; describe(descriptions: { [key: string]: string; }): Argv; /** Should yargs attempt to detect the os' locale? Defaults to `true`. */ detectLocale(detect: boolean): Argv; /** * Tell yargs to parse environment variables matching the given prefix and apply them to argv as though they were command line arguments. */ env(): Argv; env(prefix: string): Argv; env(enable: boolean): Argv; /** A message to print at the end of the usage instructions */ epilog(msg: string): Argv; /** A message to print at the end of the usage instructions */ epilogue(msg: string): Argv; /** * 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. */ example(command: string, description: string): Argv; example(command: ReadonlyArray<[string, string?]>): Argv; /** Manually indicate that the program should exit, and provide context about why we wanted to exit. Follows the behavior set by `.exitProcess().` */ exit(code: number, err: Error): void; /** * 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. */ exitProcess(enabled: boolean): Argv; /** * Method to execute when a failure occurs, rather than printing the failure message. * @param func Is called with the failure message that would have been printed, the Error instance originally thrown and yargs state when the failure occurred. */ fail(func: ((msg: string, err: Error, yargs: Argv) => any) | boolean): Argv; /** * Allows to programmatically get completion choices for any line. * @param args An array of the words in the command line to complete. * @param done The callback to be called with the resulting completions. */ getCompletion(args: readonly string[], done: (err: Error | null, completions: readonly string[]) => void): Argv; getCompletion(args: readonly string[], done?: never): Promise; /** * Returns a promise which resolves to a string containing the help text. */ getHelp(): Promise; /** * Indicate that an option (or group of options) should not be reset when a command is executed */ global(key: string | readonly string[]): Argv; /** Given a key, or an array of keys, places options under an alternative heading when displaying usage instructions */ group(key: string | readonly string[], groupName: string): Argv; /** Hides a key from the generated usage information. Unless a `--show-hidden` option is also passed with `--help` (see `showHidden()`). */ hide(key: string): Argv; /** * 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. * @param [description] Customizes the description of the help option in the usage string. * @param [enableExplicit] If `false` is provided, it will disable --help. */ help(): Argv; help(enableExplicit: boolean): Argv; help(option: string, enableExplicit: boolean): Argv; help(option: string, description?: string, enableExplicit?: boolean): Argv; /** * Given the key `x` is set, it is required that the key `y` is set. * y` can 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 with `x`. */ implies(key: string, value: string | readonly string[]): Argv; implies(implies: { [key: string]: string | readonly string[]; }): Argv; /** * Return the locale that yargs is currently using. */ locale(): 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. */ locale(loc: string): Argv; /** * Define global middleware functions to be called first, in list order, for all cli command. * @param callbacks Can be a function or a list of functions. Each callback gets passed a reference to argv. * @param [applyBeforeValidation] Set to `true` to apply middleware before validation. This will execute the middleware prior to validation checks, but after parsing. */ middleware(callbacks: MiddlewareFunction | ReadonlyArray>, applyBeforeValidation?: boolean): Argv; /** * The number of arguments that should be consumed after a key. This can be a useful hint to prevent parsing ambiguity. */ nargs(key: string, count: number): Argv; nargs(nargs: { [key: string]: number; }): Argv; /** The key provided represents a path and should have `path.normalize()` applied. */ normalize(key: K | readonly K[]): Argv & { [key in K]: ToString; }>; normalize(key: K | readonly K[]): Argv; /** * Tell the parser to always interpret key as a number. */ number(key: K | readonly K[]): Argv & { [key in K]: ToNumber; }>; number(key: K | readonly K[]): Argv; /** * 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. */ option(key: K, options: O): Argv & { [key in K]: InferredOptionType; } & Alias>; option(key: K, options: O): Argv; } & Alias>; option(options: O): Argv & InferredOptionTypes & Alias>; /** * 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. */ options(key: K, options: O): Argv & { [key in K]: InferredOptionType; }>; options(key: K, options: O): Argv; }>; options(options: O): Argv & InferredOptionTypes>; /** * Parse `args` instead of `process.argv`. Returns the `argv` object. `args` may either be a pre-processed argv array, or a raw argument string. * @param [context] Provides a useful mechanism for passing state information to commands */ parse(): { [key in keyof Arguments as key | CamelCaseKey]: Arguments[key]; } | Promise<{ [key in keyof Arguments as key | CamelCaseKey]: Arguments[key]; }>; parse(arg: string | readonly string[], context?: object, parseCallback?: ParseCallback): { [key in keyof Arguments as key | CamelCaseKey]: Arguments[key]; } | Promise<{ [key in keyof Arguments as key | CamelCaseKey]: Arguments[key]; }>; parseSync(): { [key in keyof Arguments as key | CamelCaseKey]: Arguments[key]; }; parseSync(arg: string | readonly string[], context?: object, parseCallback?: ParseCallback): { [key in keyof Arguments as key | CamelCaseKey]: Arguments[key]; }; parseAsync(): Promise<{ [key in keyof Arguments as key | CamelCaseKey]: Arguments[key]; }>; parseAsync(arg: string | readonly string[], context?: object, parseCallback?: ParseCallback): Promise<{ [key in keyof Arguments as key | CamelCaseKey]: Arguments[key]; }>; /** * If the arguments have not been parsed, this property is `false`. */ parsed: DetailedArguments | false; /** Allows to configure advanced yargs features. */ parserConfiguration(configuration: Partial): Argv; /** * Similar to `config()`, indicates that yargs should interpret the object from the specified key in package.json as a configuration object. * @param [cwd] If provided, the package.json will be read from this location */ pkgConf(key: string | readonly string[], cwd?: string): Argv; /** * 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. */ positional(key: K, opt: O): Argv & { [key in K]: InferredOptionType; }>; positional(key: K, opt: O): Argv; }>; /** Should yargs provide suggestions regarding similar commands if no matching command is found? */ recommendCommands(): Argv; /** * @deprecated since version 6.6.0 * Use '.demandCommand()' or '.demandOption()' instead */ require(key: K | readonly K[], msg?: string | true): Argv>; require(key: string, msg: string): Argv; require(key: string, required: boolean): Argv; require(keys: readonly number[], msg: string): Argv; require(keys: readonly number[], required: boolean): Argv; require(positionals: number, required: boolean): Argv; require(positionals: number, msg: string): Argv; /** * @deprecated since version 6.6.0 * Use '.demandCommand()' or '.demandOption()' instead */ required(key: K | readonly K[], msg?: string | true): Argv>; required(key: string, msg: string): Argv; required(key: string, required: boolean): Argv; required(keys: readonly number[], msg: string): Argv; required(keys: readonly number[], required: boolean): Argv; required(positionals: number, required: boolean): Argv; required(positionals: number, msg: string): Argv; requiresArg(key: string | readonly string[]): Argv; /** Set the name of your script ($0). Default is the base filename executed by node (`process.argv[1]`) */ scriptName($0: string): Argv; /** * 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. */ showCompletionScript(): Argv; /** * Configure the `--show-hidden` option that displays the hidden keys (see `hide()`). * @param option 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"). * @param description Changes the default description ("Show hidden options") */ showHidden(option?: string | boolean): Argv; showHidden(option: string, description?: string): Argv; /** * Print the usage data using the console function consoleLevel for printing. * @param [consoleLevel='error'] */ showHelp(consoleLevel?: string): Argv; /** * Provide the usage data as a string. * @param printCallback a function with a single argument. */ showHelp(printCallback: (s: string) => void): Argv; /** * By default, yargs outputs a usage string if any error is detected. * Use the `.showHelpOnFail()` method to customize this behavior. * @param enable If `false`, the usage string is not output. * @param [message] Message that is output after the error message. */ showHelpOnFail(enable: boolean, message?: string): Argv; /** * Print the version data using the console function consoleLevel or the specified function. * @param [level='error'] */ showVersion(level?: 'error' | 'log' | ((message: string) => void)): Argv; /** Specifies either a single option key (string), or an array of options. If any of the options is present, yargs validation is skipped. */ skipValidation(key: string | readonly string[]): Argv; /** * Any command-line argument given that is not demanded, or does not have a corresponding description, will be reported as an error. */ strict(): Argv; strict(enabled: boolean): Argv; /** * 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. */ strictCommands(): Argv; strictCommands(enabled: boolean): Argv; /** * 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. */ strictOptions(): Argv; strictOptions(enabled: boolean): Argv; /** * 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. */ string(key: K | readonly K[]): Argv & { [key in K]: ToString; }>; string(key: K | readonly K[]): Argv; terminalWidth(): number; updateLocale(obj: { [key: string]: string; }): Argv; /** * Override the default strings used by yargs with the key/value pairs provided in obj */ updateStrings(obj: { [key: string]: string; }): Argv; /** * 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. */ usage(message: string): Argv; usage(command: string | readonly string[], description: string, builder?: (args: Argv) => Argv, handler?: (args: ArgumentsCamelCase) => unknown): Argv; usage(command: string | readonly string[], showInHelp: boolean, builder?: (args: Argv) => Argv, handler?: (args: ArgumentsCamelCase) => unknown): Argv; usage(command: string | readonly string[], description: string, builder?: O, handler?: (args: ArgumentsCamelCase>) => unknown): Argv; usage(command: string | readonly string[], showInHelp: boolean, builder?: O, handler?: (args: ArgumentsCamelCase>) => unknown): Argv; /** * 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. */ version(): Argv; version(version: string): Argv; version(enable: boolean): Argv; version(optionKey: string, version: string): Argv; version(optionKey: string, description: string, version: string): Argv; /** * Format usage output to wrap at columns many columns. */ wrap(columns: number | null): Argv; /** burgee: the manifest every surface — help, `--json`, `--schema`, `--mcp`, completions — is projected from (J7, J8). */ readonly manifest: Manifest; /** burgee: declare what the command does to the world (N6); what exposes it as an MCP tool (N2). */ effects(value: DeclaredEffects): Argv; /** burgee: plugins yargs never had. `preRun`/`postRun` fire around every handler. */ use(plugin: Plugin): Argv; /** burgee: inject the streams and the exit for this instance (T1), and get E1 exit codes back. */ burgee(seam: BurgeeSeam): Argv; } ``` ### CommandModule ```ts interface CommandModule { /** array of strings (or a single string) representing aliases of `exports.command`, positional args defined in an alias are ignored */ aliases?: readonly string[] | string | undefined; /** object declaring the options the command accepts, or a function accepting and returning a yargs instance */ builder?: CommandBuilder | undefined; /** string (or array of strings) that executes this command when given on the command line, first string may contain positional args */ command?: readonly string[] | string | undefined; /** boolean (or string) to show deprecation notice */ deprecated?: boolean | string | undefined; /** string used as the description for the command in help text, use `false` for a hidden command */ describe?: string | false | undefined; /** a function which will be passed the parsed argv. */ handler: (args: ArgumentsCamelCase) => unknown; } ``` ### DetailedArguments ```ts interface DetailedArguments { argv: Record; error: Error | null; aliases: Record; newAliases: Record; defaulted: Record; configuration: Record; } ``` ### Options ```ts interface Options { /** string or array of strings, alias(es) for the canonical option key, see `alias()` */ alias?: string | readonly string[] | undefined; /** boolean, interpret option as an array, see `array()` */ array?: boolean | undefined; /** boolean, interpret option as a boolean flag, see `boolean()` */ boolean?: boolean | undefined; /** value or array of values, limit valid option arguments to a predefined set, see `choices()` */ choices?: Choices | undefined; /** function, coerce or transform parsed command line values into another value, see `coerce()` */ coerce?: ((arg: any) => any) | undefined; /** boolean, interpret option as a path to a JSON config file, see `config()` */ config?: boolean | undefined; /** function, provide a custom config parsing function, see `config()` */ configParser?: ((configPath: string) => object) | undefined; /** string or object, require certain keys not to be set, see `conflicts()` */ conflicts?: string | readonly string[] | { [key: string]: string | readonly string[]; } | undefined; /** boolean, interpret option as a count of boolean flags, see `count()` */ count?: boolean | undefined; /** value, set a default value for the option, see `default()` */ default?: any; /** string, use this description for the default value in help content, see `default()` */ defaultDescription?: string | undefined; /** * @deprecated since version 6.6.0 * Use 'demandOption' instead */ demand?: boolean | string | undefined; /** boolean or string, mark the argument as deprecated, see `deprecateOption()` */ deprecate?: boolean | string | undefined; /** boolean or string, mark the argument as deprecated, see `deprecateOption()` */ deprecated?: boolean | string | undefined; /** boolean or string, demand the option be given, with optional error message, see `demandOption()` */ demandOption?: boolean | string | undefined; /** string, the option description for help content, see `describe()` */ desc?: string | undefined; /** string, the option description for help content, see `describe()` */ describe?: string | undefined; /** string, the option description for help content, see `describe()` */ description?: string | undefined; /** boolean, indicate that this key should not be reset when a command is invoked, see `global()` */ global?: boolean | undefined; /** string, when displaying usage instructions place the option under an alternative group heading, see `group()` */ group?: string | undefined; /** don't display option in help output. */ hidden?: boolean | undefined; /** string or object, require certain keys to be set, see `implies()` */ implies?: string | readonly string[] | { [key: string]: string | readonly string[]; } | undefined; /** number, specify how many arguments should be consumed for the option, see `nargs()` */ nargs?: number | undefined; /** boolean, apply path.normalize() to the option, see `normalize()` */ normalize?: boolean | undefined; /** boolean, interpret option as a number, `number()` */ number?: boolean | undefined; /** * @deprecated since version 6.6.0 * Use 'demandOption' instead */ require?: boolean | string | undefined; /** * @deprecated since version 6.6.0 * Use 'demandOption' instead */ required?: boolean | string | undefined; /** boolean, require the option be specified with a value, see `requiresArg()` */ requiresArg?: boolean | undefined; /** boolean, skips validation if the option is present, see `skipValidation()` */ skipValidation?: boolean | undefined; /** boolean, interpret option as a string, see `string()` */ string?: boolean | undefined; type?: 'array' | 'count' | PositionalOptionsType | undefined; } ``` ### ParsedCommand ```ts interface ParsedCommand { cmd: string; demanded: Positional[]; optional: Positional[]; } ``` ### Parser ```ts interface Parser { (args: string | any[], opts?: any): Record; detailed: (args: string | any[], opts?: any) => DetailedArguments; camelCase: typeof camelCase; decamelize: typeof decamelize; looksLikeNumber: typeof looksLikeNumber; } ``` ### PlatformShim ```ts interface PlatformShim { assert: { notStrictEqual: (a: any, b: any, m?: string) => void; strictEqual: (a: any, b: any, m?: string) => void; }; cliui: typeof cliui; findUp: (start: string, callback: (dir: string, names: string[]) => string | undefined) => string | undefined; getEnv: (key: string) => string | undefined; inspect: typeof inspect; getProcessArgvBin: () => string; mainFilename: string; Parser: typeof Parser; path: { basename: typeof basename; dirname: typeof dirname; extname: typeof extname; relative: typeof relative; resolve: typeof resolve; join: typeof join; }; process: { argv: () => string[]; cwd: () => string; emitWarning: (warning: string | Error, type?: string) => void; execPath: () => string; exit: (code: number) => void; nextTick: (cb: () => void) => void; stdColumns: number | null; /** burgee: the streams --mcp serves on, reached through the shim like everything else. */ stdin: () => NodeJS.ReadableStream; stdout: () => { write: (s: string) => unknown; }; }; readFileSync: typeof readFileSync; readdirSync: typeof readdirSync; require: NodeJS.Require; getCallerFile: () => string; stringWidth: (str: string) => number; y18n: Y18N; /** burgee: a previous major's command collaborator, where its behaviour differs from 18's (`yargs/v17-factory.ts`). */ CommandInstance?: typeof CommandInstance; } ``` ### PositionalOptions ```ts interface PositionalOptions { /** string or array of strings, see `alias()` */ alias?: string | readonly string[] | undefined; /** boolean, interpret option as an array, see `array()` */ array?: boolean | undefined; /** value or array of values, limit valid option arguments to a predefined set, see `choices()` */ choices?: Choices | undefined; /** function, coerce or transform parsed command line values into another value, see `coerce()` */ coerce?: ((arg: any) => any) | undefined; /** string or object, require certain keys not to be set, see `conflicts()` */ conflicts?: string | readonly string[] | { [key: string]: string | readonly string[]; } | undefined; /** value, set a default value for the option, see `default()` */ default?: any; /** boolean or string, demand the option be given, with optional error message, see `demandOption()` */ demandOption?: boolean | string | undefined; /** string, the option description for help content, see `describe()` */ desc?: string | undefined; /** string, the option description for help content, see `describe()` */ describe?: string | undefined; /** string, the option description for help content, see `describe()` */ description?: string | undefined; /** string or object, require certain keys to be set, see `implies()` */ implies?: string | readonly string[] | { [key: string]: string | readonly string[]; } | undefined; /** boolean, apply path.normalize() to the option, see normalize() */ normalize?: boolean | undefined; type?: PositionalOptionsType | undefined; } ``` ### RequireDirectoryOptions ```ts interface RequireDirectoryOptions { /** Look for command modules in all subdirectories and apply them as a flattened (non-hierarchical) list. */ recurse?: boolean | undefined; /** The types of files to look for when requiring command modules. */ extensions?: readonly string[] | undefined; /** * A synchronous function called for each command module encountered. * Accepts `commandObject`, `pathToFile`, and `filename` as arguments. * Returns `commandObject` to include the command; any falsy value to exclude/skip it. */ visit?: ((commandObject: any, pathToFile?: string, filename?: string) => any) | undefined; /** Whitelist certain modules */ include?: RegExp | ((pathToFile: string) => boolean) | undefined; /** Blacklist certain modules. */ exclude?: RegExp | ((pathToFile: string) => boolean) | undefined; } ``` ## Types ### Arguments ```ts type Arguments = T & { /** Non-option arguments */ _: Array; /** The script name or node command */ $0: string; /** All remaining options */ [argName: string]: unknown; }; ``` ### ArgumentsCamelCase Arguments type, with camelcased keys ```ts type ArgumentsCamelCase = { [key in keyof T as key | CamelCaseKey]: T[key]; } & { /** Non-option arguments */ _: Array; /** The script name or node command */ $0: string; /** All remaining options */ [argName: string]: unknown; }; ``` ### AsyncCompletionFunction ```ts type AsyncCompletionFunction = (current: string, argv: any, done: (completion: readonly string[]) => void) => void; ``` ### BuilderArguments ```ts type BuilderArguments R, R = ReturnType> = R extends Argv ? ArgumentsCamelCase : {} | R extends PromiseLike> ? ArgumentsCamelCase : {}; ``` ### BuilderCallback ```ts type BuilderCallback = ((args: Argv) => PromiseLike>) | ((args: Argv) => Argv) | ((args: Argv) => void); ``` ### Choices ```ts type Choices = ReadonlyArray; ``` ### CommandBuilder ```ts type CommandBuilder = { [key: string]: Options; } | ((args: Argv) => Argv) | ((args: Argv) => PromiseLike>); ``` ### CompletionCallback ```ts type CompletionCallback = (err: Error | null, completions: string[] | undefined) => void; ``` ### Defined Remove undefined as a possible value for keys K in T ```ts type Defined = Omit & { [key in K]: Exclude; }; ``` ### FallbackCompletionFunction ```ts type FallbackCompletionFunction = (current: string, argv: any, completionFilter: (onCompleted?: CompletionCallback) => any, done: (completions: string[]) => any) => void; ``` ### InferredOptionType ```ts type InferredOptionType = O extends ({ coerce: (arg: any) => infer T; }) ? IsRequiredOrHasDefault extends true ? T : T | undefined : O extends ({ type: 'count'; default: infer D; } | { count: true; default: infer D; }) ? number | Exclude : O extends ({ type: 'count'; } | { count: true; }) ? number : IsUnknown> extends false ? InferredOptionTypePrimitive : O extends ({ default: infer D; }) ? Exclude : unknown; ``` ### InferredOptionTypeInner ```ts type InferredOptionTypeInner = O extends { type: 'array'; choices: ReadonlyArray; } ? C[] : O extends { type: 'array'; string: true; } ? string[] : O extends { type: 'array'; number: true; } ? number[] : O extends { type: 'array'; normalize: true; } ? string[] : O extends { array: true; choices: ReadonlyArray; } ? C[] : O extends { array: true; type: 'string'; } ? string[] : O extends { array: true; type: 'number'; } ? number[] : O extends { array: true; string: true; } ? string[] : O extends { array: true; number: true; } ? number[] : O extends { array: true; normalize: true; } ? string[] : O extends { choices: ReadonlyArray; } ? C : O extends { type: 'array'; } ? Array : O extends { type: 'boolean'; } ? boolean : O extends { type: 'number'; } ? number : O extends { type: 'string'; } ? string : O extends { array: true; } ? Array : O extends { boolean: true; } ? boolean : O extends { number: true; } ? number : O extends { string: true; } ? string : O extends { normalize: true; } ? string : unknown; ``` ### InferredOptionTypePrimitive ```ts type InferredOptionTypePrimitive = O extends { default: infer D; } ? IsRequiredOrHasDefault extends true ? InferredOptionTypeInner | Exclude : InferredOptionTypeInner | D : IsRequiredOrHasDefault extends true ? InferredOptionTypeInner : InferredOptionTypeInner | undefined; ``` ### InferredOptionTypes ```ts type InferredOptionTypes = { [key in keyof O]: InferredOptionType; }; ``` ### MiddlewareFunction ```ts type MiddlewareFunction = (args: ArgumentsCamelCase) => void | Promise; ``` ### ParseCallback ```ts type ParseCallback = (err: Error | undefined, argv: ArgumentsCamelCase, output: string) => void | Promise; ``` ### ParserConfigurationOptions ```ts type ParserConfigurationOptions = Configuration & { /** Sort commands alphabetically. Default is `false` */ 'sort-commands': boolean; }; ``` ### PositionalOptionsType ```ts type PositionalOptionsType = 'boolean' | 'number' | 'string'; ``` ### PromiseCompletionFunction ```ts type PromiseCompletionFunction = (current: string, argv: any) => Promise; ``` ### SyncCompletionFunction ```ts type SyncCompletionFunction = (current: string, argv: any) => string[]; ``` ### ToArray Convert T to T[] and T | undefined to T[] | undefined ```ts type ToArray = Array> | Extract; ``` ### ToNumber Gives number[] if T is an array type, otherwise number. Preserves | undefined. ```ts type ToNumber = (Exclude extends any[] ? number[] : number) | Extract; ``` ### ToString Gives string[] if T is an array type, otherwise string. Preserves | undefined. ```ts type ToString = (Exclude extends any[] ? string[] : string) | Extract; ```