index.d.ts (28512B)
1 // Type definitions for commander 2 // Original definitions by: Alan Agius <https://github.com/alan-agius4>, Marcelo Dezem <https://github.com/mdezem>, vvakame <https://github.com/vvakame>, Jules Randolph <https://github.com/sveinburne> 3 4 // Using method rather than property for method-signature-style, to document method overloads separately. Allow either. 5 /* eslint-disable @typescript-eslint/method-signature-style */ 6 /* eslint-disable @typescript-eslint/no-explicit-any */ 7 8 // This is a trick to encourage editor to suggest the known literals while still 9 // allowing any BaseType value. 10 // References: 11 // - https://github.com/microsoft/TypeScript/issues/29729 12 // - https://github.com/sindresorhus/type-fest/blob/main/source/literal-union.d.ts 13 // - https://github.com/sindresorhus/type-fest/blob/main/source/primitive.d.ts 14 type LiteralUnion<LiteralType, BaseType extends string | number> = LiteralType | (BaseType & Record<never, never>); 15 16 export class CommanderError extends Error { 17 code: string; 18 exitCode: number; 19 message: string; 20 nestedError?: string; 21 22 /** 23 * Constructs the CommanderError class 24 * @param exitCode - suggested exit code which could be used with process.exit 25 * @param code - an id string representing the error 26 * @param message - human-readable description of the error 27 * @constructor 28 */ 29 constructor(exitCode: number, code: string, message: string); 30 } 31 32 export class InvalidArgumentError extends CommanderError { 33 /** 34 * Constructs the InvalidArgumentError class 35 * @param message - explanation of why argument is invalid 36 * @constructor 37 */ 38 constructor(message: string); 39 } 40 export { InvalidArgumentError as InvalidOptionArgumentError }; // deprecated old name 41 42 export interface ErrorOptions { // optional parameter for error() 43 /** an id string representing the error */ 44 code?: string; 45 /** suggested exit code which could be used with process.exit */ 46 exitCode?: number; 47 } 48 49 export class Argument { 50 description: string; 51 required: boolean; 52 variadic: boolean; 53 defaultValue?: any; 54 defaultValueDescription?: string; 55 argChoices?: string[]; 56 57 /** 58 * Initialize a new command argument with the given name and description. 59 * The default is that the argument is required, and you can explicitly 60 * indicate this with <> around the name. Put [] around the name for an optional argument. 61 */ 62 constructor(arg: string, description?: string); 63 64 /** 65 * Return argument name. 66 */ 67 name(): string; 68 69 /** 70 * Set the default value, and optionally supply the description to be displayed in the help. 71 */ 72 default(value: unknown, description?: string): this; 73 74 /** 75 * Set the custom handler for processing CLI command arguments into argument values. 76 */ 77 argParser<T>(fn: (value: string, previous: T) => T): this; 78 79 /** 80 * Only allow argument value to be one of choices. 81 */ 82 choices(values: readonly string[]): this; 83 84 /** 85 * Make argument required. 86 */ 87 argRequired(): this; 88 89 /** 90 * Make argument optional. 91 */ 92 argOptional(): this; 93 } 94 95 export class Option { 96 flags: string; 97 description: string; 98 99 required: boolean; // A value must be supplied when the option is specified. 100 optional: boolean; // A value is optional when the option is specified. 101 variadic: boolean; 102 mandatory: boolean; // The option must have a value after parsing, which usually means it must be specified on command line. 103 short?: string; 104 long?: string; 105 negate: boolean; 106 defaultValue?: any; 107 defaultValueDescription?: string; 108 presetArg?: unknown; 109 envVar?: string; 110 parseArg?: <T>(value: string, previous: T) => T; 111 hidden: boolean; 112 argChoices?: string[]; 113 114 constructor(flags: string, description?: string); 115 116 /** 117 * Set the default value, and optionally supply the description to be displayed in the help. 118 */ 119 default(value: unknown, description?: string): this; 120 121 /** 122 * Preset to use when option used without option-argument, especially optional but also boolean and negated. 123 * The custom processing (parseArg) is called. 124 * 125 * @example 126 * ```ts 127 * new Option('--color').default('GREYSCALE').preset('RGB'); 128 * new Option('--donate [amount]').preset('20').argParser(parseFloat); 129 * ``` 130 */ 131 preset(arg: unknown): this; 132 133 /** 134 * Add option name(s) that conflict with this option. 135 * An error will be displayed if conflicting options are found during parsing. 136 * 137 * @example 138 * ```ts 139 * new Option('--rgb').conflicts('cmyk'); 140 * new Option('--js').conflicts(['ts', 'jsx']); 141 * ``` 142 */ 143 conflicts(names: string | string[]): this; 144 145 /** 146 * Specify implied option values for when this option is set and the implied options are not. 147 * 148 * The custom processing (parseArg) is not called on the implied values. 149 * 150 * @example 151 * program 152 * .addOption(new Option('--log', 'write logging information to file')) 153 * .addOption(new Option('--trace', 'log extra details').implies({ log: 'trace.txt' })); 154 */ 155 implies(optionValues: OptionValues): this; 156 157 /** 158 * Set environment variable to check for option value. 159 * 160 * An environment variables is only used if when processed the current option value is 161 * undefined, or the source of the current value is 'default' or 'config' or 'env'. 162 */ 163 env(name: string): this; 164 165 /** 166 * Calculate the full description, including defaultValue etc. 167 */ 168 fullDescription(): string; 169 170 /** 171 * Set the custom handler for processing CLI option arguments into option values. 172 */ 173 argParser<T>(fn: (value: string, previous: T) => T): this; 174 175 /** 176 * Whether the option is mandatory and must have a value after parsing. 177 */ 178 makeOptionMandatory(mandatory?: boolean): this; 179 180 /** 181 * Hide option in help. 182 */ 183 hideHelp(hide?: boolean): this; 184 185 /** 186 * Only allow option value to be one of choices. 187 */ 188 choices(values: readonly string[]): this; 189 190 /** 191 * Return option name. 192 */ 193 name(): string; 194 195 /** 196 * Return option name, in a camelcase format that can be used 197 * as a object attribute key. 198 */ 199 attributeName(): string; 200 201 /** 202 * Return whether a boolean option. 203 * 204 * Options are one of boolean, negated, required argument, or optional argument. 205 */ 206 isBoolean(): boolean; 207 } 208 209 export class Help { 210 /** output helpWidth, long lines are wrapped to fit */ 211 helpWidth?: number; 212 sortSubcommands: boolean; 213 sortOptions: boolean; 214 showGlobalOptions: boolean; 215 216 constructor(); 217 218 /** Get the command term to show in the list of subcommands. */ 219 subcommandTerm(cmd: Command): string; 220 /** Get the command summary to show in the list of subcommands. */ 221 subcommandDescription(cmd: Command): string; 222 /** Get the option term to show in the list of options. */ 223 optionTerm(option: Option): string; 224 /** Get the option description to show in the list of options. */ 225 optionDescription(option: Option): string; 226 /** Get the argument term to show in the list of arguments. */ 227 argumentTerm(argument: Argument): string; 228 /** Get the argument description to show in the list of arguments. */ 229 argumentDescription(argument: Argument): string; 230 231 /** Get the command usage to be displayed at the top of the built-in help. */ 232 commandUsage(cmd: Command): string; 233 /** Get the description for the command. */ 234 commandDescription(cmd: Command): string; 235 236 /** Get an array of the visible subcommands. Includes a placeholder for the implicit help command, if there is one. */ 237 visibleCommands(cmd: Command): Command[]; 238 /** Get an array of the visible options. Includes a placeholder for the implicit help option, if there is one. */ 239 visibleOptions(cmd: Command): Option[]; 240 /** Get an array of the visible global options. (Not including help.) */ 241 visibleGlobalOptions(cmd: Command): Option[]; 242 /** Get an array of the arguments which have descriptions. */ 243 visibleArguments(cmd: Command): Argument[]; 244 245 /** Get the longest command term length. */ 246 longestSubcommandTermLength(cmd: Command, helper: Help): number; 247 /** Get the longest option term length. */ 248 longestOptionTermLength(cmd: Command, helper: Help): number; 249 /** Get the longest global option term length. */ 250 longestGlobalOptionTermLength(cmd: Command, helper: Help): number; 251 /** Get the longest argument term length. */ 252 longestArgumentTermLength(cmd: Command, helper: Help): number; 253 /** Calculate the pad width from the maximum term length. */ 254 padWidth(cmd: Command, helper: Help): number; 255 256 /** 257 * Wrap the given string to width characters per line, with lines after the first indented. 258 * Do not wrap if insufficient room for wrapping (minColumnWidth), or string is manually formatted. 259 */ 260 wrap(str: string, width: number, indent: number, minColumnWidth?: number): string; 261 262 /** Generate the built-in help text. */ 263 formatHelp(cmd: Command, helper: Help): string; 264 } 265 export type HelpConfiguration = Partial<Help>; 266 267 export interface ParseOptions { 268 from: 'node' | 'electron' | 'user'; 269 } 270 export interface HelpContext { // optional parameter for .help() and .outputHelp() 271 error: boolean; 272 } 273 export interface AddHelpTextContext { // passed to text function used with .addHelpText() 274 error: boolean; 275 command: Command; 276 } 277 export interface OutputConfiguration { 278 writeOut?(str: string): void; 279 writeErr?(str: string): void; 280 getOutHelpWidth?(): number; 281 getErrHelpWidth?(): number; 282 outputError?(str: string, write: (str: string) => void): void; 283 284 } 285 286 export type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll'; 287 export type HookEvent = 'preSubcommand' | 'preAction' | 'postAction'; 288 // The source is a string so author can define their own too. 289 export type OptionValueSource = LiteralUnion<'default' | 'config' | 'env' | 'cli' | 'implied', string> | undefined; 290 291 export type OptionValues = Record<string, any>; 292 293 export class Command { 294 args: string[]; 295 processedArgs: any[]; 296 readonly commands: readonly Command[]; 297 readonly options: readonly Option[]; 298 readonly registeredArguments: readonly Argument[]; 299 parent: Command | null; 300 301 constructor(name?: string); 302 303 /** 304 * Set the program version to `str`. 305 * 306 * This method auto-registers the "-V, --version" flag 307 * which will print the version number when passed. 308 * 309 * You can optionally supply the flags and description to override the defaults. 310 */ 311 version(str: string, flags?: string, description?: string): this; 312 /** 313 * Get the program version. 314 */ 315 version(): string | undefined; 316 317 /** 318 * Define a command, implemented using an action handler. 319 * 320 * @remarks 321 * The command description is supplied using `.description`, not as a parameter to `.command`. 322 * 323 * @example 324 * ```ts 325 * program 326 * .command('clone <source> [destination]') 327 * .description('clone a repository into a newly created directory') 328 * .action((source, destination) => { 329 * console.log('clone command called'); 330 * }); 331 * ``` 332 * 333 * @param nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...` 334 * @param opts - configuration options 335 * @returns new command 336 */ 337 command(nameAndArgs: string, opts?: CommandOptions): ReturnType<this['createCommand']>; 338 /** 339 * Define a command, implemented in a separate executable file. 340 * 341 * @remarks 342 * The command description is supplied as the second parameter to `.command`. 343 * 344 * @example 345 * ```ts 346 * program 347 * .command('start <service>', 'start named service') 348 * .command('stop [service]', 'stop named service, or all if no name supplied'); 349 * ``` 350 * 351 * @param nameAndArgs - command name and arguments, args are `<required>` or `[optional]` and last may also be `variadic...` 352 * @param description - description of executable command 353 * @param opts - configuration options 354 * @returns `this` command for chaining 355 */ 356 command(nameAndArgs: string, description: string, opts?: ExecutableCommandOptions): this; 357 358 /** 359 * Factory routine to create a new unattached command. 360 * 361 * See .command() for creating an attached subcommand, which uses this routine to 362 * create the command. You can override createCommand to customise subcommands. 363 */ 364 createCommand(name?: string): Command; 365 366 /** 367 * Add a prepared subcommand. 368 * 369 * See .command() for creating an attached subcommand which inherits settings from its parent. 370 * 371 * @returns `this` command for chaining 372 */ 373 addCommand(cmd: Command, opts?: CommandOptions): this; 374 375 /** 376 * Factory routine to create a new unattached argument. 377 * 378 * See .argument() for creating an attached argument, which uses this routine to 379 * create the argument. You can override createArgument to return a custom argument. 380 */ 381 createArgument(name: string, description?: string): Argument; 382 383 /** 384 * Define argument syntax for command. 385 * 386 * The default is that the argument is required, and you can explicitly 387 * indicate this with <> around the name. Put [] around the name for an optional argument. 388 * 389 * @example 390 * ``` 391 * program.argument('<input-file>'); 392 * program.argument('[output-file]'); 393 * ``` 394 * 395 * @returns `this` command for chaining 396 */ 397 argument<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this; 398 argument(name: string, description?: string, defaultValue?: unknown): this; 399 400 /** 401 * Define argument syntax for command, adding a prepared argument. 402 * 403 * @returns `this` command for chaining 404 */ 405 addArgument(arg: Argument): this; 406 407 /** 408 * Define argument syntax for command, adding multiple at once (without descriptions). 409 * 410 * See also .argument(). 411 * 412 * @example 413 * ``` 414 * program.arguments('<cmd> [env]'); 415 * ``` 416 * 417 * @returns `this` command for chaining 418 */ 419 arguments(names: string): this; 420 421 /** 422 * Override default decision whether to add implicit help command. 423 * 424 * @example 425 * ``` 426 * addHelpCommand() // force on 427 * addHelpCommand(false); // force off 428 * addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details 429 * ``` 430 * 431 * @returns `this` command for chaining 432 */ 433 addHelpCommand(enableOrNameAndArgs?: string | boolean, description?: string): this; 434 435 /** 436 * Add hook for life cycle event. 437 */ 438 hook(event: HookEvent, listener: (thisCommand: Command, actionCommand: Command) => void | Promise<void>): this; 439 440 /** 441 * Register callback to use as replacement for calling process.exit. 442 */ 443 exitOverride(callback?: (err: CommanderError) => never | void): this; 444 445 /** 446 * Display error message and exit (or call exitOverride). 447 */ 448 error(message: string, errorOptions?: ErrorOptions): never; 449 450 /** 451 * You can customise the help with a subclass of Help by overriding createHelp, 452 * or by overriding Help properties using configureHelp(). 453 */ 454 createHelp(): Help; 455 456 /** 457 * You can customise the help by overriding Help properties using configureHelp(), 458 * or with a subclass of Help by overriding createHelp(). 459 */ 460 configureHelp(configuration: HelpConfiguration): this; 461 /** Get configuration */ 462 configureHelp(): HelpConfiguration; 463 464 /** 465 * The default output goes to stdout and stderr. You can customise this for special 466 * applications. You can also customise the display of errors by overriding outputError. 467 * 468 * The configuration properties are all functions: 469 * ``` 470 * // functions to change where being written, stdout and stderr 471 * writeOut(str) 472 * writeErr(str) 473 * // matching functions to specify width for wrapping help 474 * getOutHelpWidth() 475 * getErrHelpWidth() 476 * // functions based on what is being written out 477 * outputError(str, write) // used for displaying errors, and not used for displaying help 478 * ``` 479 */ 480 configureOutput(configuration: OutputConfiguration): this; 481 /** Get configuration */ 482 configureOutput(): OutputConfiguration; 483 484 /** 485 * Copy settings that are useful to have in common across root command and subcommands. 486 * 487 * (Used internally when adding a command using `.command()` so subcommands inherit parent settings.) 488 */ 489 copyInheritedSettings(sourceCommand: Command): this; 490 491 /** 492 * Display the help or a custom message after an error occurs. 493 */ 494 showHelpAfterError(displayHelp?: boolean | string): this; 495 496 /** 497 * Display suggestion of similar commands for unknown commands, or options for unknown options. 498 */ 499 showSuggestionAfterError(displaySuggestion?: boolean): this; 500 501 /** 502 * Register callback `fn` for the command. 503 * 504 * @example 505 * ``` 506 * program 507 * .command('serve') 508 * .description('start service') 509 * .action(function() { 510 * // do work here 511 * }); 512 * ``` 513 * 514 * @returns `this` command for chaining 515 */ 516 action(fn: (...args: any[]) => void | Promise<void>): this; 517 518 /** 519 * Define option with `flags`, `description`, and optional argument parsing function or `defaultValue` or both. 520 * 521 * The `flags` string contains the short and/or long flags, separated by comma, a pipe or space. A required 522 * option-argument is indicated by `<>` and an optional option-argument by `[]`. 523 * 524 * See the README for more details, and see also addOption() and requiredOption(). 525 * 526 * @example 527 * 528 * ```js 529 * program 530 * .option('-p, --pepper', 'add pepper') 531 * .option('-p, --pizza-type <TYPE>', 'type of pizza') // required option-argument 532 * .option('-c, --cheese [CHEESE]', 'add extra cheese', 'mozzarella') // optional option-argument with default 533 * .option('-t, --tip <VALUE>', 'add tip to purchase cost', parseFloat) // custom parse function 534 * ``` 535 * 536 * @returns `this` command for chaining 537 */ 538 option(flags: string, description?: string, defaultValue?: string | boolean | string[]): this; 539 option<T>(flags: string, description: string, parseArg: (value: string, previous: T) => T, defaultValue?: T): this; 540 /** @deprecated since v7, instead use choices or a custom function */ 541 option(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): this; 542 543 /** 544 * Define a required option, which must have a value after parsing. This usually means 545 * the option must be specified on the command line. (Otherwise the same as .option().) 546 * 547 * The `flags` string contains the short and/or long flags, separated by comma, a pipe or space. 548 */ 549 requiredOption(flags: string, description?: string, defaultValue?: string | boolean | string[]): this; 550 requiredOption<T>(flags: string, description: string, parseArg: (value: string, previous: T) => T, defaultValue?: T): this; 551 /** @deprecated since v7, instead use choices or a custom function */ 552 requiredOption(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): this; 553 554 /** 555 * Factory routine to create a new unattached option. 556 * 557 * See .option() for creating an attached option, which uses this routine to 558 * create the option. You can override createOption to return a custom option. 559 */ 560 561 createOption(flags: string, description?: string): Option; 562 563 /** 564 * Add a prepared Option. 565 * 566 * See .option() and .requiredOption() for creating and attaching an option in a single call. 567 */ 568 addOption(option: Option): this; 569 570 /** 571 * Whether to store option values as properties on command object, 572 * or store separately (specify false). In both cases the option values can be accessed using .opts(). 573 * 574 * @returns `this` command for chaining 575 */ 576 storeOptionsAsProperties<T extends OptionValues>(): this & T; 577 storeOptionsAsProperties<T extends OptionValues>(storeAsProperties: true): this & T; 578 storeOptionsAsProperties(storeAsProperties?: boolean): this; 579 580 /** 581 * Retrieve option value. 582 */ 583 getOptionValue(key: string): any; 584 585 /** 586 * Store option value. 587 */ 588 setOptionValue(key: string, value: unknown): this; 589 590 /** 591 * Store option value and where the value came from. 592 */ 593 setOptionValueWithSource(key: string, value: unknown, source: OptionValueSource): this; 594 595 /** 596 * Get source of option value. 597 */ 598 getOptionValueSource(key: string): OptionValueSource | undefined; 599 600 /** 601 * Get source of option value. See also .optsWithGlobals(). 602 */ 603 getOptionValueSourceWithGlobals(key: string): OptionValueSource | undefined; 604 605 /** 606 * Alter parsing of short flags with optional values. 607 * 608 * @example 609 * ``` 610 * // for `.option('-f,--flag [value]'): 611 * .combineFlagAndOptionalValue(true) // `-f80` is treated like `--flag=80`, this is the default behaviour 612 * .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b` 613 * ``` 614 * 615 * @returns `this` command for chaining 616 */ 617 combineFlagAndOptionalValue(combine?: boolean): this; 618 619 /** 620 * Allow unknown options on the command line. 621 * 622 * @returns `this` command for chaining 623 */ 624 allowUnknownOption(allowUnknown?: boolean): this; 625 626 /** 627 * Allow excess command-arguments on the command line. Pass false to make excess arguments an error. 628 * 629 * @returns `this` command for chaining 630 */ 631 allowExcessArguments(allowExcess?: boolean): this; 632 633 /** 634 * Enable positional options. Positional means global options are specified before subcommands which lets 635 * subcommands reuse the same option names, and also enables subcommands to turn on passThroughOptions. 636 * 637 * The default behaviour is non-positional and global options may appear anywhere on the command line. 638 * 639 * @returns `this` command for chaining 640 */ 641 enablePositionalOptions(positional?: boolean): this; 642 643 /** 644 * Pass through options that come after command-arguments rather than treat them as command-options, 645 * so actual command-options come before command-arguments. Turning this on for a subcommand requires 646 * positional options to have been enabled on the program (parent commands). 647 * 648 * The default behaviour is non-positional and options may appear before or after command-arguments. 649 * 650 * @returns `this` command for chaining 651 */ 652 passThroughOptions(passThrough?: boolean): this; 653 654 /** 655 * Parse `argv`, setting options and invoking commands when defined. 656 * 657 * The default expectation is that the arguments are from node and have the application as argv[0] 658 * and the script being run in argv[1], with user parameters after that. 659 * 660 * @example 661 * ``` 662 * program.parse(process.argv); 663 * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions 664 * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0] 665 * ``` 666 * 667 * @returns `this` command for chaining 668 */ 669 parse(argv?: readonly string[], options?: ParseOptions): this; 670 671 /** 672 * Parse `argv`, setting options and invoking commands when defined. 673 * 674 * Use parseAsync instead of parse if any of your action handlers are async. Returns a Promise. 675 * 676 * The default expectation is that the arguments are from node and have the application as argv[0] 677 * and the script being run in argv[1], with user parameters after that. 678 * 679 * @example 680 * ``` 681 * program.parseAsync(process.argv); 682 * program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions 683 * program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0] 684 * ``` 685 * 686 * @returns Promise 687 */ 688 parseAsync(argv?: readonly string[], options?: ParseOptions): Promise<this>; 689 690 /** 691 * Parse options from `argv` removing known options, 692 * and return argv split into operands and unknown arguments. 693 * 694 * argv => operands, unknown 695 * --known kkk op => [op], [] 696 * op --known kkk => [op], [] 697 * sub --unknown uuu op => [sub], [--unknown uuu op] 698 * sub -- --unknown uuu op => [sub --unknown uuu op], [] 699 */ 700 parseOptions(argv: string[]): ParseOptionsResult; 701 702 /** 703 * Return an object containing local option values as key-value pairs 704 */ 705 opts<T extends OptionValues>(): T; 706 707 /** 708 * Return an object containing merged local and global option values as key-value pairs. 709 */ 710 optsWithGlobals<T extends OptionValues>(): T; 711 712 /** 713 * Set the description. 714 * 715 * @returns `this` command for chaining 716 */ 717 718 description(str: string): this; 719 /** @deprecated since v8, instead use .argument to add command argument with description */ 720 description(str: string, argsDescription: Record<string, string>): this; 721 /** 722 * Get the description. 723 */ 724 description(): string; 725 726 /** 727 * Set the summary. Used when listed as subcommand of parent. 728 * 729 * @returns `this` command for chaining 730 */ 731 732 summary(str: string): this; 733 /** 734 * Get the summary. 735 */ 736 summary(): string; 737 738 /** 739 * Set an alias for the command. 740 * 741 * You may call more than once to add multiple aliases. Only the first alias is shown in the auto-generated help. 742 * 743 * @returns `this` command for chaining 744 */ 745 alias(alias: string): this; 746 /** 747 * Get alias for the command. 748 */ 749 alias(): string; 750 751 /** 752 * Set aliases for the command. 753 * 754 * Only the first alias is shown in the auto-generated help. 755 * 756 * @returns `this` command for chaining 757 */ 758 aliases(aliases: readonly string[]): this; 759 /** 760 * Get aliases for the command. 761 */ 762 aliases(): string[]; 763 764 /** 765 * Set the command usage. 766 * 767 * @returns `this` command for chaining 768 */ 769 usage(str: string): this; 770 /** 771 * Get the command usage. 772 */ 773 usage(): string; 774 775 /** 776 * Set the name of the command. 777 * 778 * @returns `this` command for chaining 779 */ 780 name(str: string): this; 781 /** 782 * Get the name of the command. 783 */ 784 name(): string; 785 786 /** 787 * Set the name of the command from script filename, such as process.argv[1], 788 * or require.main.filename, or __filename. 789 * 790 * (Used internally and public although not documented in README.) 791 * 792 * @example 793 * ```ts 794 * program.nameFromFilename(require.main.filename); 795 * ``` 796 * 797 * @returns `this` command for chaining 798 */ 799 nameFromFilename(filename: string): this; 800 801 /** 802 * Set the directory for searching for executable subcommands of this command. 803 * 804 * @example 805 * ```ts 806 * program.executableDir(__dirname); 807 * // or 808 * program.executableDir('subcommands'); 809 * ``` 810 * 811 * @returns `this` command for chaining 812 */ 813 executableDir(path: string): this; 814 /** 815 * Get the executable search directory. 816 */ 817 executableDir(): string | null; 818 819 /** 820 * Output help information for this command. 821 * 822 * Outputs built-in help, and custom text added using `.addHelpText()`. 823 * 824 */ 825 outputHelp(context?: HelpContext): void; 826 /** @deprecated since v7 */ 827 outputHelp(cb?: (str: string) => string): void; 828 829 /** 830 * Return command help documentation. 831 */ 832 helpInformation(context?: HelpContext): string; 833 834 /** 835 * You can pass in flags and a description to override the help 836 * flags and help description for your command. Pass in false 837 * to disable the built-in help option. 838 */ 839 helpOption(flags?: string | boolean, description?: string): this; 840 841 /** 842 * Output help information and exit. 843 * 844 * Outputs built-in help, and custom text added using `.addHelpText()`. 845 */ 846 help(context?: HelpContext): never; 847 /** @deprecated since v7 */ 848 help(cb?: (str: string) => string): never; 849 850 /** 851 * Add additional text to be displayed with the built-in help. 852 * 853 * Position is 'before' or 'after' to affect just this command, 854 * and 'beforeAll' or 'afterAll' to affect this command and all its subcommands. 855 */ 856 addHelpText(position: AddHelpTextPosition, text: string): this; 857 addHelpText(position: AddHelpTextPosition, text: (context: AddHelpTextContext) => string): this; 858 859 /** 860 * Add a listener (callback) for when events occur. (Implemented using EventEmitter.) 861 */ 862 on(event: string | symbol, listener: (...args: any[]) => void): this; 863 } 864 865 export interface CommandOptions { 866 hidden?: boolean; 867 isDefault?: boolean; 868 /** @deprecated since v7, replaced by hidden */ 869 noHelp?: boolean; 870 } 871 export interface ExecutableCommandOptions extends CommandOptions { 872 executableFile?: string; 873 } 874 875 export interface ParseOptionsResult { 876 operands: string[]; 877 unknown: string[]; 878 } 879 880 export function createCommand(name?: string): Command; 881 export function createOption(flags: string, description?: string): Option; 882 export function createArgument(name: string, description?: string): Argument; 883 884 export const program: Command;