Interface: Command<G>
Command interface.
Signature
ts
export interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams>Type Parameters
| Name | Description |
|---|---|
G extends GunshiParamsConstraint = DefaultGunshiParams | The Gunshi parameters constraint |
Properties
| Name | Type | Description |
|---|---|---|
aliases (optional) | readonly string[] | Other names of the command, such as ['ls'] for list. The command runs with any of them, as with its name, and ctx.name and ctx.commandPath have its name: the help, the hints and the help as JSON tell the name of the command. An alias is accepted but not taught: the help does not list it, and the Did you mean hint for an unknown command and shell completion do not offer it. A sub-command whose name is the alias wins over the alias, so an alias never hides a command. Two commands at the same level with the same alias are a mistake: using the alias throws a TypeError. A lazy command takes its aliases from the definition given to lazy, as it is found before it is loaded. |
args (optional) | ExtractArgs<G> | Command arguments. Each argument can include a description property to describe the argument in usage. |
deprecated (optional) | boolean | string | Whether the command is deprecated: true, or the text that tells what to use instead, such as 'Use deploy.'. A deprecated command still runs. With the global options plugin, it prints a warning to stderr when it runs, once: push is deprecated. Use deploy., and not when the command is asked for JSON with --json. A command under a deprecated group, such as the old name of a renamed group, warns of the group too. Its help says that it is deprecated, after its description. As an internal command, it is left out of the help, the Did you mean hint for an unknown command, shell completion and the help as JSON, so that they teach what to use instead. To rename a command, keep the old name as a deprecated command that runs as the new one, such as push: define({ ...deploy, name: 'push', aliases: [], deprecated: 'Use deploy.' }), where aliases: [] takes the aliases that the spread copies off the old name. It has no effect on the entry command. |
description (optional) | string | Command description. It's used to describe the command in usage and it's recommended to specify. |
entry (optional) | boolean | Whether this command is an entry command. Default: undefined Since v0.27.0 |
examples (optional) | string | CommandExamplesFetcher<G> | Command examples. examples of how to use the command. |
internal (optional) | boolean | Whether this is an internal command. Internal commands are not shown in help usage. Default: false Since v0.27.0 |
name (optional) | string | Command name. It's used to find command line arguments to execute from sub commands, and it's recommended to specify. |
passthrough (optional) | boolean | string | Whether the command passes the arguments that it does not take on to another program: true, or the text that tells what they are, such as 'The arguments for the script', which the help shows. Such a command reports neither an option that it does not declare, whatever CliOptions.strict says, nor a positional argument that it does not take, whatever CliOptions.strictPositionals says. ctx.passthrough has them, as they are given and in order, with the arguments after -- at the end. The options that it declares, the global options such as --help included, are read as before and are not passed on: to give --help to the other program, give it after --. A short option group with an option that the command does not declare is passed on whole, such as -qk for a command that declares -q and not -k: -q is read too, and the other program gets it in the group. The other errors of the arguments are reported as before. An option that the command does not declare takes the next argument as its value, unless it has a value of its own, such as --bail=3, or the next argument is an option or --. Both are passed on, and a positional argument that the command declares does not get it: give the positional arguments of the command before the options of the other program that take no value, such as exec run.js --watch, not exec --watch run.js. The help shows it at the end of the usage, as [ARGUMENTS ...], and the text in the ARGUMENTS section, which the i18n plugin translates with the key passthrough of the command. With the global options plugin, --json is passed on too when the command declares no json argument: jsonArgs, or a json argument of its own, takes --json. Without one, --help --json and --version --json are still answered by gunshi, as JSON, and the help as JSON has passthrough. A lazy command takes it from the loaded command, and from the definition given to lazy when the loaded command does not set it, or when the loader returns a runner. |
rendering (optional) | RenderingOptions<G> | Rendering control options Since v0.27.0 |
run (optional) | CommandRunner<G> | Command runner. it's the command to be executed A command that has sub-commands needs no runner: run without a sub-command, it prints its usage, with the global options plugin, as --help does. A command with a runner runs it then, with omitted set to true. A command without sub-commands needs a runner. Without one, it throws a TypeError when it runs ('run' is required in command: <name>), and --help still prints its usage. So does a lazy command whose loader returns a command without a runner. |
subCommands (optional) | Record<string, SubCommandable | SubCommandLoader> | Map<string, SubCommandable | SubCommandLoader> | readonly SubCommandable[] | Nested sub-commands for this command. Allows building command trees like git remote add. Each key is the sub-command name, and the value is a command, a lazy command, or a loader, a function that returns the command or its runner, which runs as a lazy command named after its key. An array of commands is keyed by the names of the commands. On the entry command, these are the top-level sub-commands when CliOptions.subCommands is not given. Since v0.28.0 |
toKebab (optional) | boolean | Whether to convert the camel-case style argument name to kebab-case. If you will set to true, All Command.args names will be converted to kebab-case. |
