Skip to content

Interface: CliOptions<G> ​

CLI options of cli function.

Signature ​

ts
export interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams>

Type Parameters ​

NameDescription
G extends GunshiParamsConstraint = DefaultGunshiParamsA type extending GunshiParams to specify the shape of cli options.

Properties ​

NameTypeDescription
cwd (optional)stringCurrent working directory.
description (optional)stringCommand program description.
fallbackToEntry (optional)booleanWhether to fallback to entry command when the sub-command is not found. When it is not set, it is true for a CLI that declares no sub-commands and to which a plugin adds commands, such as the complete command of @gunshi/plugin-completion, so that the positional arguments of the entry command are not taken for command names. This is so when the entry command has something to run: a command object with run, a lazy command, whose loader gives the runner, or a runner given to cli(). For a command object without run, it stays false: the commands of the plugins are then the commands of the CLI, and an argument that is not one of them is reported. Default: false Since v0.27.0
helpHint (optional)booleanWhether to follow the validation errors with the command that shows the help of the nearest command: the command itself for an argument error, and the parent of an unknown command, such as my-app deploy --help. With the global options plugin, it is printed to stderr after the errors, after an empty line and a heading. It is the command that next of the JSON error has with --json. Set it to false to leave the command out, such as when your renderer of the validation errors points to the help in its own way. It changes the output for people only: next of the JSON error stays. The command is left out for a command whose --help does not show the help, too: one that declares a help argument of its own, or with renderUsage: null. Default: true
leftMargin (optional)numberLeft margin of the command output.
middleMargin (optional)numberMiddle margin of the command output.
name (optional)stringThe name of the CLI, as it is run, such as todo. The usage line and the help as JSON start with it, and so do the command that the errors point to for the help and next of the errors of --json. Without it, the usage line starts with COMMAND, and the others with <COMMAND>, a placeholder for how the CLI was run.
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 (CliOptions.validationErrorExitCode 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>) | nullRender function the header section in the command usage.
renderUsage (optional)((ctx: Readonly<CommandContext<G>>) => Promise<string>) | nullRender function the command usage.
renderValidationErrors (optional)((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | nullRender function the validation errors. With the global options plugin, the rendered message is printed to stderr, the exit code is set to CliOptions.validationErrorExitCode, 1 by default, CliOptions.onErrorCommand is called, and cli() resolves with undefined. The message is followed by the command that shows the help, unless CliOptions.helpHint is false. 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)booleanWhether to treat undefined options as argument validation errors. By default, 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, such as Unknown option: --alow-reload. Set it to false to ignore them, and run the command, such as for a command that passes its arguments as they are to another program. The arguments after -- are not option tokens: they stay in rest either way. With the global options plugin, --help and --version are still answered: given with them, an unknown option is not reported, as the other argument validation errors are not. An unknown command is still reported. --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: true
strictPositionals (optional)booleanWhether to treat the positional arguments that the command does not take as argument validation errors, as strict does for the options. When enabled, the positional arguments after the command path that the positional arguments of the resolved command do not take are reported as validation errors before the command runner is executed. A command takes as many as it declares, an optional one included, and any number with a positional argument with multiple: true. The arguments after -- are not positional arguments: they stay in rest. With the global options plugin, --help and --version are still answered, as they are with the other argument validation errors. After a command with sub-commands, a word that is not one of them is reported as an unknown command instead. Default: false
subCommands (optional)Record<string, SubCommandable | SubCommandLoader> | Map<string, SubCommandable | SubCommandLoader> | 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. A value of the object or the Map may also be a loader, a function that returns the command or its runner, which runs as a lazy command named after its key. When this is not given, the Command.subCommands of the entry command are the sub-commands.
usageOptionType (optional)booleanWhether to display the usage optional argument type.
usageOptionValue (optional)booleanWhether to display the optional argument value.
usageSilent (optional)booleanWhether 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
validationErrorExitCode (optional)numberThe exit code of the validation errors, such as 2, the exit code of a usage error in many command-line tools. They are the errors of the arguments: a missing or invalid argument, an unknown command or a command line that cannot be resolved, an unknown option, unless strict is false, a positional argument that the command does not take, only with strictPositionals, and --json given to a command that does not spread jsonArgs. With the global options plugin, the exit code is set to it when the errors are printed, as text or as JSON, before CliOptions.onErrorCommand is called, which can still change it. It is an integer from 1 to 255, as the exitCode of a CommandError is, and any other value is replaced with 1. It does not change the exit code of a CommandError, nor of any other error that a command throws. With renderValidationErrors: null, a renderer that returns an empty message, or CliOptions.usageSilent, nothing is printed, and the exit code is left alone. Default: 1
version (optional)stringCommand program version.

onAfterCommand Parameters ​

NameTypeDescription
ctxReadonly<CommandContext<G>>The command context
resultstring | undefinedThe 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 ​

NameTypeDescription
ctxReadonly<CommandContext<G>>The command context

onBeforeCommand Returns ​

Awaitable<void>

onErrorCommand Parameters ​

NameTypeDescription
ctxReadonly<CommandContext<G>>The command context
errorErrorThe error thrown during execution, or the AggregateError of the validation errors

onErrorCommand Returns ​

Awaitable<void>

Released under the MIT License.