Interface: CliOptions<G>
CLI options of cli function.
Signature
ts
export interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams>Type Parameters
| Name | Description |
|---|---|
G extends GunshiParamsConstraint = DefaultGunshiParams | A type extending GunshiParams to specify the shape of cli options. |
Properties
| Name | Type | Description |
|---|---|---|
cwd (optional) | string | Current working directory. |
description (optional) | string | Command program description. |
fallbackToEntry (optional) | boolean | Whether to fallback to entry command when the sub-command is not found. Default: false Since v0.27.0 |
leftMargin (optional) | number | Left margin of the command output. |
middleMargin (optional) | number | Middle margin of the command output. |
name (optional) | string | Command program name. |
onAfterCommand (optional) | (ctx: Readonly<CommandContext<G>>, result: string | undefined) => Awaitable<void> | Hook that runs after successful command execution Since v0.27.0 |
onBeforeCommand (optional) | (ctx: Readonly<CommandContext<G>>) => Awaitable<void> | Hook that runs before any command execution Since v0.27.0 |
onErrorCommand (optional) | (ctx: Readonly<CommandContext<G>>, error: Error) => Awaitable<void> | Hook that runs when a command throws an error, or when the arguments fail validation For the validation errors and a CommandError that the global options plugin has printed, the exit code is already set when the hook runs (1 for the validation errors, and the exitCode of a CommandError), so the hook can set another one, and cli() resolves after it. Any other error rejects cli() after the hook. Since v0.27.0 |
plugins (optional) | Plugin[] | User plugins. Since v0.27.0 |
renderHeader (optional) | ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null | Render function the header section in the command usage. |
renderUsage (optional) | ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null | Render function the command usage. |
renderValidationErrors (optional) | ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null | Render function the validation errors. With the global options plugin, the rendered message is printed to stderr, the exit code is set to 1, CliOptions.onErrorCommand is called, and cli() resolves with undefined. Set it to null to report the validation errors yourself: nothing is printed, and cli() rejects with the AggregateError. A renderer that returns an empty message, and CliOptions.usageSilent, also leave them to the caller. With --json, the plugin prints the validation errors as one line of JSON, and does not call the renderer. null and CliOptions.usageSilent still leave them to the caller. |
strict (optional) | boolean | Whether to treat undefined options as argument validation errors. When enabled, option tokens that are not declared by the resolved command arguments or installed global options are reported as validation errors before the command runner is executed. --json is not reported, since gunshi knows what it means: given to a command that does not spread jsonArgs, the global options plugin reports json_not_supported for it instead, with or without strict. --json=false asks for no JSON, and is reported. Default: false |
subCommands (optional) | Record<string, SubCommandable> | Map<string, SubCommandable> | readonly SubCommandable[] | Sub commands. An object or a Map keyed by the sub-command names, or an array of commands, which are keyed by their names. When this is not given, the Command.subCommands of the entry command are the sub-commands. |
usageOptionType (optional) | boolean | Whether to display the usage optional argument type. |
usageOptionValue (optional) | boolean | Whether to display the optional argument value. |
usageSilent (optional) | boolean | Whether to keep usage, header, version, and validation-error text off the terminal (they are still returned as strings) and to silence CommandContext.log. Output that must still appear — machine-readable results for an agent, warnings for the CLI author — should use console.log / console.warn, not ctx.log. A command that spreads jsonArgs and is given --json prints its result, and its errors, as JSON even with it. The validation errors, and a CommandError that the command throws, are not printed either, so cli() rejects with them, for the caller to report them (see CliOptions.renderValidationErrors). The exit code is left alone. Default: false |
version (optional) | string | Command program version. |
onAfterCommand Parameters
| Name | Type | Description |
|---|---|---|
ctx | Readonly<CommandContext<G>> | The command context |
result | string | undefined | The result of the command, when it is a string. The result of a command that prints JSON with --json is printed, not passed, so it is undefined |
onAfterCommand Returns
Awaitable<void>
onBeforeCommand Parameters
| Name | Type | Description |
|---|---|---|
ctx | Readonly<CommandContext<G>> | The command context |
onBeforeCommand Returns
Awaitable<void>
onErrorCommand Parameters
| Name | Type | Description |
|---|---|---|
ctx | Readonly<CommandContext<G>> | The command context |
error | Error | The error thrown during execution, or the AggregateError of the validation errors |
onErrorCommand Returns
Awaitable<void>