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