default

gunshi cli entry point.

This entry point exports the bellow APIs and types:

• cli: The main CLI function to run the command, included global options and usage renderer built-in plugins.
• define: A function to define a command.
• defineWithTypes: A function to define a command with specific type parameters.
• lazy: A function to lazily load a command.
• lazyWithTypes: A function to lazily load a command with specific type parameters.
• plugin: A function to create a plugin.
• createCommandContext: A function to create a command context, mainly for testing purposes.
• args-tokens utilities: parseArgs, resolveArgs, ArgsValidationError, ArgsValidationErrorKeys, and ArgsValidationErrorCode for parsing and validating command line arguments.
• Structured error utilities: CommandNotFoundError, CommandNotFoundErrorKeys, CommandNotFoundErrorCode, CommandNotFoundErrorOptions, CommandResolutionError, CommandResolutionErrorKeys, CommandResolutionErrorCode, CommandResolutionErrorOptions, isCommandNotFoundError, isCommandResolutionError, isArgsValidationError, and hasPriorityValidationError.
• CommandError, CommandErrorOptions, and isCommandError: An error for the failures that a command expects, printed without a stack trace.
• jsonArgs: The argument that a command spreads into its args to support --json.
• JsonOutputError, JsonOutputErrorKeys, JsonOutputErrorCode, JsonOutputErrorOptions, and isJsonOutputError: The errors of the JSON output.
• Some basic type definitions, such as CommandContext, Plugin, PluginContext, etc.

Example

import { cli } from 'gunshi'

Variables

Variable	Description
ANONYMOUS_COMMAND_NAME
CommandNotFoundErrorKeys	Command not found error resource keys.
CommandResolutionErrorKeys	Command resolution error resource keys.
jsonArgs	The argument that a command spreads into its args to support --json.
JsonOutputErrorKeys	The resource keys of the errors of the JSON output, which are the codes of JsonOutputError.

Functions

Function	Description
cli	Run the command.
hasPriorityValidationError	Check whether validation errors should be handled before version, help, or command execution.
isArgsValidationError	Check whether an error is an ArgsValidationError.
isCommandError	Check whether an error is a CommandError.
isCommandNotFoundError	Check whether an error is a CommandNotFoundError.
isCommandResolutionError	Check whether an error is a CommandResolutionError.
isJsonOutputError	Check whether an error is a JsonOutputError.
parseArgs	Parse command line arguments.
plugin	Define a plugin with extension compatibility and typed dependency extensions
resolveArgs	Resolve command line arguments.

Classes

Class	Description
ArgsValidationError	An error that contains structured metadata for argument validation failures.
CommandError	Error for a failure that a command expects, such as a project that does not exist.
CommandNotFoundError	Error raised when a command cannot be resolved.
CommandResolutionError	Error raised when command routing cannot produce one consistent command.
DefaultTranslation	Default implementation of TranslationAdapter.
JsonOutputError	Error raised by the global options plugin for the JSON output, when a command is given --json.

Interfaces

Interface	Description
Args	An object that contains argument schema.
ArgSchema	An argument schema definition for command-line argument parsing.
ArgToken	Argument token.
CliOptions	CLI options of cli function.
Command	Command interface.
CommandContext	Command context.
CommandContextExtension	Command context extension
CommandEnvironment	Command environment.
GunshiParams	Gunshi unified parameter type.
PluginContext	Gunshi plugin context interface.
PluginDependency	Plugin dependency definition
PluginOptions	Plugin definition options
PluginWithExtension	Plugin return type with extension, which includes the plugin ID, name, dependencies, and extension.
PluginWithoutExtension	Plugin return type without extension, which includes the plugin ID, name, and dependencies, but no extension.
RenderingOptions	Rendering control options
SubCommandable	Sub-command entry type for use in subCommands.

References

CommandContextParams

Re-exports CommandContextParams

---

createCommandContext

Re-exports createCommandContext

---

define

Re-exports define

---

defineWithTypes

Re-exports defineWithTypes

---

lazy

Re-exports lazy

---

lazyWithTypes

Re-exports lazyWithTypes

Type Aliases

Type Alias	Description
ArgsValidationErrorCode	A machine-readable argument validation error code.
ArgValues	An object that contains the values of the arguments.
Awaitable	Awaitable type.
Commandable	Define a command type.
CommandCallMode	Command call mode.
CommandContextCore	Readonly command context available to a command context extension factory.
CommandDecorator	Command decorator.
CommandErrorOptions	Options for CommandError. All of them are optional.
CommandExamplesFetcher	Command examples fetcher.
CommandLoader	Command loader.
CommandNotFoundErrorCode	Command not found error code.
CommandNotFoundErrorOptions	Options for CommandNotFoundError.
CommandResolutionErrorCode	Command resolution error code.
CommandResolutionErrorOptions	Options for CommandResolutionError.
CommandRunner	Command runner.
CommandRunnerResult	What the runner of a command returns: its result for a command that spreads jsonArgs, otherwise a string or nothing.
DefaultGunshiParams	Default Gunshi parameters.
ExtendContext	Extend command context type. This type is used to extend the command context with additional properties at CommandContext.extensions.
GunshiParamsConstraint	Generic constraint for command-related types.
HasJsonArgs	Whether the arguments have the json of jsonArgs.
JsonOutputErrorCode	The code of a JsonOutputError.
JsonOutputErrorOptions	Options for JsonOutputError.
JsonResult	The result of a command that supports --json: an object keyed by a noun, such as { project } or { projects }, so that fields can be added later. The global options plugin prints it with JSON.stringify, so convert what JSON cannot hold, such as a Map or a BigInt, yourself.
LazyCommand	Lazy command interface.
OnPluginExtension	Plugin extension callback, which is called when the plugin is extended with extension option.
Plugin	Gunshi plugin, which is a function that receives a PluginContext.
PluginExtension	Plugin extension
PluginFunction	Plugin function type
Prettify	Prettify a type by flattening its structure.
RendererDecorator	Renderer decorator type.
ValidationErrorsDecorator	Validation errors renderer decorator type. A function that wraps a validation errors renderer to add or modify its behavior.