---
url: /guide/introduction/what-is-gunshi.md
---
# What's Gunshi?

Gunshi is a modern JavaScript command-line library designed to simplify the creation of command-line interfaces (CLIs).

## Origin of the Name

The name "gunshi" (軍師) refers to a position in ancient Japanese samurai battles where samurai devised strategies and gave orders. This name is inspired by the word "command", reflecting the library's purpose of handling command-line commands.

## Key Features

Gunshi is designed with several powerful features to make CLI development easier and more maintainable:

* 📏 **Simple & Universal**: Run commands with simple API and support for universal runtime (Node.js, Deno, Bun).
* ⚙️ **Declarative & Type Safe**: Configure commands declaratively with full TypeScript support and type-safe argument parsing by [args-tokens](https://github.com/kazupon/args-tokens)
* 🧩 **Composable & Lazy**: Create modular sub-commands with context sharing and lazy loading for better performance.
* 🎨 **Flexible Rendering**: Customize usage generation, validation errors, and help messages with pluggable renderers.
* 🌍 **Internationalization**: Built with global users in mind, featuring locale-aware design, resource management, and multi-language support.
* 🔌 **Pluggable**: Extensible plugin system with dependency management and lifecycle hooks for modular CLI development.

## Why Gunshi?

Gunshi provides a modern approach to building command-line interfaces in JavaScript and TypeScript. It's designed to be:

* **Developer-friendly**: Simple API with TypeScript support
* **Flexible**: Compose commands and customize behavior as needed
* **Maintainable**: Declarative configuration makes code easier to understand and maintain
* **Performant**: Lazy loading ensures resources are only loaded when needed

Whether you're building a simple CLI tool or a complex command-line application with multiple sub-commands, Gunshi provides the features you need to create a great user experience.

## Next Steps

Now that you understand what Gunshi is and its key features, here's how to proceed with the documentation:

### Documentation Structure

The Gunshi documentation is organized into three main sections:

* **Essentials**: Learn the fundamental concepts of Gunshi through a step-by-step tutorial format. This section covers everything from basic usage to composable commands and lazy loading.

* **Advanced**: Explore specialized features organized by topic. Each chapter focuses on a specific advanced capability like internationalization, custom rendering, or type system extensions.

* **Plugin**: Understand the plugin system through a tutorial approach. Learn how to create, configure, and distribute plugins for extending Gunshi's functionality.

### Where to Go Next

> \[!TIP]
> Start with the **Setup** guide to install Gunshi in your project, then proceed through the **Essentials** section in order. Each chapter builds upon previous concepts.

1. **[Setup](./setup.md)** - Install and configure Gunshi in your project
2. **[Getting Started](../essentials/getting-started.md)** - Create your first CLI application
3. Continue through the **Essentials** section to learn core concepts

After completing the essentials, you can explore the **Advanced** section based on your specific needs. The chapters there are independent and can be read in any order.

If you're interested in extending Gunshi with plugins, the **Plugin** section provides comprehensive guidance on creating and using plugins.

## Credits

Gunshi project is made possible by the open-source community and the many innovative tools in the JavaScript and TypeScript ecosystem. We extend our gratitude to all contributors and maintainers whose work has laid the foundation for this project.

* [`citty`](https://github.com/unjs/citty), Provided the original inspiration for modern JavaScript command-line library.
* [`ordana`](https://github.com/sapphi-red/ordana), Inspired documentation generation in Gunshi
* [`@bomb.sh/tab`](https://github.com/bombshell-dev/tab), Powered by shell auto-completion for the JavaScript ecosystem

---

---
url: /guide/introduction/setup.md
---
# Setup

Gunshi can be installed in various JavaScript environments. Choose the installation method that matches your project setup.

## Install

### Stable

::: code-group

```sh [npm]
npm install --save gunshi
```

```sh [pnpm]
pnpm add gunshi
```

```sh [yarn]
yarn add gunshi
```

```sh [deno]
# For deno projects, you can add Gunshi from JSR:
deno add jsr:@gunshi/gunshi
```

```sh [bun]
bun add gunshi
```

:::

## LLM-Assisted Development

Gunshi provides tooling to integrate with AI coding assistants such as [Claude Code](https://claude.ai/code).

### Automatic Setup (Recommended)

You can quickly set up LLM-assisted development for your project using the CLI tool:

::: code-group

```sh [npm]
npx @gunshi/docs
```

```sh [pnpm]
pnpm dlx @gunshi/docs
```

```sh [yarn]
yarn dlx @gunshi/docs
```

```sh [bun]
bun x @gunshi/docs
```

:::

This command automatically configures [Claude Code skills](https://docs.anthropic.com/en/docs/claude-code/skills) for Claude Code.

### Manual Setup

If you prefer manual configuration, install the documentation package as a dev dependency:

::: code-group

```sh [npm]
npm install --save-dev @gunshi/docs
```

```sh [pnpm]
pnpm add -D @gunshi/docs
```

```sh [yarn]
yarn add -D @gunshi/docs
```

```sh [bun]
bun add -D @gunshi/docs
```

:::

This package includes guide content and API references as markdown files in [llms.txt](https://llmstxt.org/) format.

Then add the following to your AI agent's configuration file (e.g., `CLAUDE.md`):

```md
# CLI Development with Gunshi

Use the Gunshi library for creating CLI applications instead of other libraries such as cac, yargs, commander, etc.
Gunshi is a modern JavaScript command-line library.

For more information, refer to the Gunshi API documentation in `node_modules/@gunshi/docs/**.md`.
```

## Requirements

Gunshi requires:

* **JavaScript Runtime**:
  * **Node.js**: v22 or later
  * **Deno**: v2 or later
  * **Bun**: v1.1 or later
* **ES Modules**: `"type": "module"` in `package.json` (if using Node.js and Bun)
* **TypeScript**: Version 5.0 or higher (if using TypeScript)

---

---
url: /guide/essentials/getting-started.md
---
# Getting Started

This guide will help you create your first command-line application with Gunshi.

We'll start with a simple "Hello World" example and gradually explore more features.

## Hello World Example

Let's create a simple CLI application that greets the user.

Create a new file (e.g., `cli.js` or `cli.ts`) and add the following code:

```js [cli.js]
import { cli } from 'gunshi'

// Run a simple command
await cli(process.argv.slice(2), () => {
  console.log('Hello, World!')
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/essentials/getting-started/hello).

This minimal example demonstrates the core concept of Gunshi.

The `cli` function takes command-line arguments and a function to execute.

## Running Your CLI

You can run your CLI application with:

```sh
node cli.js
```

You should see the output:

```sh
Hello, World!
```

## Adding Command-Line Arguments

Let's enhance our example to accept a name as an argument.

The function receives a `CommandContext` object (abbreviated as `ctx`) as its parameter.

This context object contains parsed command-line arguments, options, and other execution information:

```js [cli.js]
import { cli } from 'gunshi'

await cli(process.argv.slice(2), ctx => {
  // Access positional arguments
  const name = ctx.positionals[0] || 'World'
  console.log(`Hello, ${name}!`)
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/essentials/getting-started/context).

Now you can run:

```sh
node cli.js Alice
```

And you'll see:

```sh
Hello, Alice!
```

## Adding Command Options

Let's add some options to our command:

```js [cli.js]
import { cli, define } from 'gunshi'

const command = define({
  name: 'greeter',
  description: 'A simple greeting CLI',
  args: {
    name: {
      type: 'string',
      short: 'n',
      description: 'Name to greet'
    },
    uppercase: {
      type: 'boolean',
      short: 'u',
      description: 'Convert greeting to uppercase'
    }
  },
  run: ctx => {
    const { name = 'World', uppercase } = ctx.values
    let greeting = `Hello, ${name}!`

    if (uppercase) {
      greeting = greeting.toUpperCase()
    }

    console.log(greeting)
  }
})

await cli(process.argv.slice(2), command)
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/essentials/getting-started/options).

Now you can run:

```sh
node cli.js --name Alice --uppercase
# or with short options
node cli.js -n Alice -u
```

And you'll see:

```sh
HELLO, ALICE!
```

## Built-in Help

Gunshi automatically generates help information for your commands through its built-in plugin system.

Run:

```sh
node cli.js --help
```

You'll see a help message that includes:

Here's an example of the generated help output:

```sh
USAGE:
  COMMAND <OPTIONS>

OPTIONS:
  -h, --help                 Display this help message
  -v, --version              Display this version
  -n, --name <name>          Name to greet
  -u, --uppercase            Convert greeting to uppercase
```

The help message automatically includes:

* Command description
* Available options
* Option descriptions

The standard `cli()` function automatically includes these built-in plugins:

* `@gunshi/plugin-global` - Provides global options like `--help` and `--version`
* `@gunshi/plugin-renderer` - Handles formatted output for help messages, error messages, and usage information

These plugins are included by default when you use `cli()` from the main `gunshi` package. If you use `cli()` from [`@gunshi/bone`](./plugin-system.md#minimal-setup) instead, which includes no plugins, you'll need to manually configure these plugins to get help and version functionality.

> \[!TIP]
> Want to learn more about Gunshi's plugin architecture? Check out the [Plugin System guide](./plugin-system.md) to understand how plugins work, explore the built-in plugins in detail, and learn how to create your own custom plugins to extend your CLI's functionality.

## Using Gunshi with Different Runtimes

Gunshi is designed to work seamlessly across multiple JavaScript runtimes. Here's how to use it with each supported environment:

### Node.js

For Node.js applications, use `process.argv.slice(2)` to pass command-line arguments:

```js [cli.js]
import { cli } from 'gunshi'

function entry() {
  console.log('Hello, Gunshi!')
}

await cli(process.argv.slice(2), entry)
```

### Deno

In Deno, use `Deno.args` to access command-line arguments:

```ts [cli.ts]
import { cli } from '@gunshi/gunshi'

function entry() {
  console.log('Hello, Gunshi with Deno!')
}

await cli(Deno.args, entry)
```

### Bun

Bun also provides `Bun.argv` similar to Node.js:

```ts [cli.ts]
import { cli } from 'gunshi'

function entry() {
  console.log('Hello, Gunshi with Bun!')
}

await cli(Bun.argv.slice(2), entry) // or use process.argv.slice(2) in Bun
```

Note that while the argument passing differs slightly between runtimes, the Gunshi API remains consistent across all environments.

## Next Steps

You've successfully created your first Gunshi CLI application! You've learned the fundamentals: creating basic commands, handling arguments and options, using the built-in help system, and running your CLI across different JavaScript runtimes.

Now it's time to explore the essential features that will help you build powerful, production-ready CLI applications.

The following chapters will guide you through each topic:

* **[Declarative Configuration](./declarative.md)** - Organize commands with clear, maintainable declarative structures
* **[Type Safety](./type-safe.md)** - Leverage TypeScript for automatic type inference and compile-time checking
* **[Composable Sub-commands](./composable.md)** - Build complex CLIs with modular sub-commands like `git commit` or `npm install`
* **[Lazy & Async Command Loading](./lazy-async.md)** - Optimize startup performance by loading commands only when needed
* **[Auto Usage Generation](./auto-usage.md)** - Create self-documenting CLIs with automatic help and usage information
* **[Plugin System](./plugin-system.md)** - Extend your CLI with modular plugins for features like i18n and shell completion

Each chapter builds upon the previous ones, introducing more sophisticated patterns and techniques.

Start with [Declarative Configuration](./declarative.md) to learn how to structure your commands in a clean, maintainable way as your CLI grows in complexity.

---

---
url: /guide/essentials/declarative.md
---
# Declarative Configuration

Gunshi allows you to configure your commands declaratively, making your CLI code more organized and maintainable.

This approach separates the command definition from its execution logic.

## Basic Declarative Structure

If you've followed the Getting Started guide, you've seen how simple it is to create a basic CLI with Gunshi.

In that guide, we created a simple greeting command. As your CLI grows with more options, validation rules, and features, declarative configuration becomes essential for managing this complexity effectively.

A declaratively configured command in Gunshi follows this structure:

```js
import { define } from 'gunshi'

const command = define({
  // Command metadata
  name: 'command-name',
  description: 'Command description',

  // Command arguments
  args: {
    // Argument definitions
  },

  // Command examples
  examples: 'Example usage',

  // Command execution function
  run: ctx => {
    // Command implementation
  }
})
```

Let's see how this structure works in practice with a complete example.

## Complete Example

Let's start with a simple example that demonstrates the declarative approach.

We'll build a greeting command with a few basic options:

```js [cli.js]
import { cli, define } from 'gunshi'

// Define a command with declarative configuration
const command = define({
  // Command metadata
  name: 'greet',
  description: 'A greeting command with declarative configuration',

  // Command arguments with descriptions
  args: {
    name: {
      type: 'string',
      short: 'n',
      description: 'Name to greet',
      default: 'World'
    },
    greeting: {
      type: 'string',
      short: 'g',
      default: 'Hello',
      description: 'Greeting to use'
    },
    uppercase: {
      type: 'boolean',
      short: 'u',
      description: 'Display greeting in uppercase'
    }
  },

  // Command examples
  examples: `
# Basic usage with default values
$ node cli.js

# Specify a name
$ node cli.js --name Alice

# Use custom greeting and name
$ node cli.js -n Bob -g "Good morning"

# Display in uppercase
$ node cli.js --name Charlie --uppercase
`,

  // Command execution function
  run: ctx => {
    const { name, greeting, uppercase } = ctx.values

    let message = `${greeting}, ${name}!`

    if (uppercase) {
      message = message.toUpperCase()
    }

    console.log(message)
  }
})

// Run the command with the declarative configuration
await cli(process.argv.slice(2), command, {
  name: 'greet-cli',
  version: '1.0.0',
  description: 'A simple greeting CLI'
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/essentials/declarative).

This example demonstrates the key components of declarative configuration:

* **Command metadata** (`name`, `description`) identifies your command
* **Arguments definition** (`args`) specifies what options the command accepts
* **Examples** show users how to use the command
* **Run function** contains the command's execution logic

When you run this command with `--help`, Gunshi automatically generates comprehensive help text from your declarative configuration.

## Command Configuration Options

### Command Metadata

* `name`: The name of the command
* `description`: A description of what the command does

### Additional Command Properties

Since v0.27.0, commands support additional configuration properties:

* `internal`: Boolean flag to mark commands as internal (default: `false`). Internal commands are hidden from help usage but remain fully functional. This is useful for debug commands, administrative functions, or implementation details that shouldn't be exposed to end users.
* `entry`: Boolean flag that marks the main command when subcommands exist (default: `undefined`). This property is typically set automatically by the framework. When used with the `fallbackToEntry` CLI option, it enables fallback behavior for unmatched subcommands.
* `rendering`: Object to customize how the command displays help, usage, and error messages. This allows fine-grained control over command-level rendering output.

  > \[!TIP]
  > For detailed information about customizing rendering output including headers, usage text, and validation errors, see the [Rendering Customization guide](../advanced/custom-rendering.md).

### Command Options

Each option can have the following properties:

* `type`: The data type: 'string', 'number', 'boolean', 'enum', 'positional' or 'custom'
* `short`: A single-character alias for the option (e.g., `-n` as a shorthand for `--name`), making commands quicker to type for frequent use.
  > \[!TIP] Multiple boolean short option flags can be grouped together.
  > (e.g., `-Vb` is equivalent to `-V -b`). Options requiring values (like `string`, `number`, `enum`) cannot be part of a group.
* `description`: A description of what the option does
* `default`: Default value if the option is not provided
* `required`: Set to `true` if the option is required. For single positional arguments, omit this field to keep the compatibility default of required, or set `required: false` to make the positional argument optional.
* `multiple`: Set to `true` if multiple option values are allowed
* `toKebab`: Set to `true` to convert camelCase argument names to kebab-case in help text and command-line usage
* `hidden`: Set to `true` to hide the argument from generated help/usage output while keeping it parseable.
* `parse`: A function to parse and validate the argument value. Required when `type` is 'custom'
* `choices`: The values that an `enum` option accepts. Required when `type` is 'enum', unless the option has a `parse` function, which then receives the value as it would for a 'string' option
* `conflicts`: Specify mutually exclusive options that cannot be used together

> \[!NOTE]
> For a more type-safe and composable way to define arguments, see [Parser Combinators](../advanced/parser-combinators.md).

#### Positional Arguments

To define arguments that are identified by their position rather than a name/flag (like `--name`), set their `type` to `'positional'`.

The *key* you use for the argument in the `args` object serves as its name for accessing the value later.

Here's how you define positional arguments in your command configuration:

```js
import { define } from 'gunshi'

const command = define({
  args: {
    // ... other options

    // 'source' is the key and the name used to access the value
    source: {
      type: 'positional',
      description: 'The source file path'
    },

    // 'destination' is the key and the name used to access the value
    destination: {
      type: 'positional',
      description: 'The destination file path'
    },

    // optional positional argument, useful when the value may come from stdin
    query: {
      type: 'positional',
      required: false,
      description: 'SQL query to execute'
    }
    // ... potentially more positional arguments
  }
})
```

* **Required by Default**: A single positional argument without `required: false` or `default` remains required for compatibility. Set `required: false` when the value can be omitted, such as a command that can read from stdin.
* **Default Values**: A single positional argument with `default` uses that value when the command-line value is missing, unless `required: true` is set.
* **Order Matters**: Positional arguments are matched based on the order they appear on the command line and the order they are defined in the `args` object. Optional positional arguments leave enough input values for later required positional arguments before consuming a value.
* **Accessing Values**: The resolved value is accessible via `ctx.values`, using the *key* you defined in the `args` object (e.g., `ctx.values.source`, `ctx.values.destination`).
* **`ctx.positionals`**: This array still exists and contains the raw string values of positional arguments in the order they were parsed (e.g., `ctx.positionals[0]`, `ctx.positionals[1]`). While available, using `ctx.values.<key>` is generally preferred for clarity and consistency.
* **Descriptions**: The `description` property is used for generating help/usage messages.
* **Type Conversion**: `args-tokens` resolves positional arguments as strings. You typically need to perform type conversions or further validation on the values accessed via `ctx.values.<key>` within your `run` function based on your application's needs.

#### Custom Type Arguments

While the built-in types (`string`, `number`, `boolean`, `positional`) cover most use cases, you may need more complex parsing logic for certain arguments.

Gunshi supports custom argument types with user-defined parsing functions, allowing you to parse structured input like JSON, validate ranges, or integrate with validation libraries like `zod`.

To define a custom argument type:

```js
import { define } from 'gunshi'
import { z } from 'zod'

// custom schema with `zod`
const config = z.object({
  debug: z.boolean(),
  mode: z.string()
})

const command = define({
  name: 'example',
  description: 'Example command with custom argument types',
  args: {
    // CSV parser example
    tags: {
      type: 'custom',
      short: 't',
      description: 'Comma-separated list of tags',
      parse: value => value.split(',').map(tag => tag.trim())
    },

    // JSON parser example with `zod`
    config: {
      type: 'custom',
      short: 'c',
      description: 'JSON configuration',
      parse: value => {
        return config.parse(JSON.parse(value))
      }
    },

    // Custom validation example
    port: {
      type: 'custom',
      short: 'p',
      description: 'Port number (1024-65535)',
      parse: value => {
        const port = Number(value)
        if (Number.isNaN(port) || port < 1024 || port > 65_535) {
          throw new TypeError(`Invalid port: ${value}. Must be a number between 1024 and 65535`)
        }
        return port
      }
    }
  },
  run: ctx => {
    // Access the parsed values
    console.log('Tags:', ctx.values.tags) // Array of strings
    console.log('Config:', ctx.values.config) // Parsed JSON object
    console.log('Port:', ctx.values.port) // Validated port number
  }
})
```

Custom type arguments support:

* **Type safety**: The return type of the `parse` function is properly inferred in TypeScript
* **Validation**: Throw an error from the `parse` function to indicate invalid input
* **Default values**: Set a `default` property to provide a value when the argument is not specified
* **Multiple values**: Set `multiple: true` to allow multiple instances of the argument
* **Short aliases**: Set a `short` property to provide a single-character alias

#### Argument Names That Plugins Also Use

Plugins add global options, which are merged into the arguments of every command. `@gunshi/plugin-global`, installed by default, adds `help` and `version`; `@gunshi/plugin-dryrun` adds `dryRun`, under a name you can change with its `name` option.

None of those names is reserved. A command may declare an argument of its own under any of them, and the command's argument wins — gunshi merges the arguments of the command over the global options:

```js
const release = define({
  name: 'release',
  args: {
    // shadows the global `--version` for this command only
    version: { type: 'string', description: 'Version to release' }
  },
  run: ctx => console.log(`releasing ${ctx.values.version}`)
})
```

Taking the name means taking it whole. `my-cli release --version` no longer prints the version of the CLI, and `-v` is no longer defined either, because the global schema is replaced rather than extended. Declare a `short` of your own if you want one. Other commands of the same CLI keep the global option.

A short name is taken the same way, and on its own. When an argument of the command declares a `short` that a global option also uses, the letter belongs to the command, and the global option keeps its long name:

```js
const build = define({
  name: 'build',
  args: {
    // takes `-v` from the global `--version`, for this command only
    verbose: { type: 'boolean', short: 'v', description: 'Verbose output' }
  },
  run: ctx => console.log(`building${ctx.values.verbose ? ' verbosely' : ''}`)
})
```

`my-cli build -v` sets `verbose`, while `my-cli build --version` still prints the version of the CLI, and its help lists it as `--version` alone. Other commands of the same CLI keep `-v` for `--version`.

> \[!NOTE]
> Declaring the name is what takes a global option away, even with a schema identical, field for field, to the one the plugin registered. A plugin is told which of its own options are still in effect; how each one reacts is part of that plugin's documentation. See [Plugin System](../plugin/introduction.md).

#### Option Values That Start with a Dash

An option that takes a value, such as a `string`, `number` or `enum` option, takes the next argument as its value, as in `--port 5000`. The exception is an argument that starts with a dash, since it looks like an option: `--port -5` does not take `-5`, and reports `--port` as missing a value (`err:arg:missing-value`). With a `string` option `name`, `--name --foo` is reported the same way. A lone `-` is still taken as a value.

This only concerns options that take a value. A `boolean` option takes no value, so `--verbose --foo` sets `verbose` and goes on to read `--foo` as an option.

To pass a value that starts with a dash, write it after `=`, or right after a short option:

```sh
app --port=-5
app -p=-5
app -p-5
```

The error message also suggests the form with `=`, such as `(to pass '-5' as its value, write '--port=-5')`. With the i18n plugin, the suggestion follows the translated error, and is translated by the built-in resource key `err:arg:missing-value:hint`.

#### Strict Unknown Option Validation

By default, Gunshi keeps backward compatibility by ignoring option tokens that are not declared in the resolved command's `args` or installed global options. Enable `strict` when you want typos or unsupported options to fail before the command runner executes:

```js
await cli(process.argv.slice(2), command, {
  strict: true
})
```

With `strict: true`, an input such as `--alow-reload` is reported as an argument validation error:

```txt
Unknown option: --alow-reload
```

The error uses the `err:arg:unknown-option` resource key, so the message follows the same renderer and i18n behavior as other argument validation errors. Suggestions such as `Did you mean --allow-reload?` are intentionally left to suggestion plugins.

#### Options before sub-commands

Option values are removed before Gunshi chooses a sub-command. A string option can therefore appear
before or after the command without turning its value into a command name:

```ts
await cli(['--config', 'prod.json', 'deploy'], entry, { subCommands })
await cli(['--config=prod.json', 'deploy'], entry, { subCommands })
await cli(['deploy', '--config', 'prod.json'], entry, { subCommands })
await cli(['-c', 'prod.json', 'deploy'], entry, { subCommands })
```

All four calls select `deploy` and resolve `ctx.values.config` to `prod.json`. This also applies to
nested paths such as `remote --config prod.json add origin`. A value that happens to equal a command
name remains a value, so `--config clean deploy` selects `deploy` when `config` is a global string
option.

The command's own argument definition takes precedence when it declares the same long or short name.
For example, a command that declares `config: { type: 'boolean' }` interprets `--config deploy` as
`config: true` and selects `deploy`. If a lazy command needs an option before its name, declare the
option in the lazy metadata as well; otherwise place the option after the command name. Ambiguous or
inconsistent interpretations produce a command-resolution error and do not run a command. Use `--`
to stop command exploration; values after it are passed through as `ctx.rest`.

#### Command Not Found Handling

When a sub-command cannot be resolved, Gunshi reports it as a structured `CommandNotFoundError` inside the validation error pipeline. This avoids brittle checks such as `error.message.startsWith('Command not found:')`.

```js
import { cli, define, isCommandNotFoundError } from 'gunshi'

try {
  await cli(process.argv.slice(2), define({ name: 'app', run: () => {} }), {
    subCommands: {
      deploy: define({ name: 'deploy', run: () => {} })
    }
  })
} catch (error) {
  if (error instanceof AggregateError) {
    const commandError = error.errors.find(isCommandNotFoundError)
    if (commandError) {
      console.error(`Unknown command: ${commandError.commandName}`)
      console.error(`Available commands: ${commandError.candidates.join(', ')}`)
    }
  }
}
```

> \[!NOTE]
> Use `isCommandNotFoundError` and `isArgsValidationError` instead of `instanceof` checks. `gunshi`, `@gunshi/plugin`, and `@gunshi/bone` each bundle their own copy of the error classes, so `instanceof` fails when an error is thrown by one package and checked with a class imported from another. The guards recognize errors from every copy, including argument errors such as a missing required option or an invalid value, whose `name` is overridden with the argument name. Keep all `gunshi` and `@gunshi/*` packages on the same version. Older copies do not mark those argument errors, so the guards cannot recognize them when an older copy throws them. Unknown option and command not found errors from older copies are still recognized.

`commandName` is the command that could not be resolved. `candidates` contains command names from the same command level, which can be used by suggestion plugins. `commandPath` points to the parent command path. For example, `git remote ad` sets `commandName` to `ad` and `commandPath` to `['remote']`.

The command context is created from the parent command, not the missing command. This means `ctx.command`, `ctx.name`, and `ctx.commandPath` describe the parent command. The actual missing command is available from `CommandNotFoundError.commandName`.

The error uses the `err:cmd:not-found` resource key, so i18n plugins can localize the message while the fallback message remains compatible with `Command not found: <name>`.

#### Kebab-Case Argument Names

> \[!TIP]
> This feature is particularly useful for users migrating from the [`cac` library](https://github.com/cacjs/cac), which automatically converts camelCase argument names to kebab-case. If you're transitioning from `cac` to Gunshi, enabling the `toKebab` option will help maintain the same command-line interface for your users.

By default, argument names are displayed in the help text and used on the command line exactly as they are defined in the `args` object.

However, it's common practice in CLI applications to use kebab-case for multi-word argument names (e.g., `--user-name` instead of `--userName`).

Gunshi supports automatic conversion of camelCase argument names to kebab-case with the `toKebab` property, which can be set at two levels:

1. **Command level**: Apply to all arguments in the command

   To apply kebab-case conversion to all arguments in a command, set the `toKebab` property at the command level:

   ```js
   import { define } from 'gunshi'

   const command = define({
     name: 'example',
     description: 'Example command',
     toKebab: true, // Apply to all arguments
     args: {
       userName: { type: 'string' }, // Will be displayed as --user-name
       maxRetries: { type: 'number' } // Will be displayed as --max-retries
     },
     run: ctx => {
       /* ... */
     }
   })
   ```

2. **Argument level**: Apply to specific arguments only

   Alternatively, you can apply kebab-case conversion to specific arguments only by setting it at the argument level:

   ```js
   import { define } from 'gunshi'

   const command = define({
     name: 'example',
     description: 'Example command',
     args: {
       userName: {
         type: 'string',
         toKebab: true // Will be displayed as --user-name
       },
       maxRetries: { type: 'number' } // Will remain as --maxRetries
     },
     run: ctx => {
       /* ... */
     }
   })
   ```

When `toKebab` is enabled:

* Argument names are converted from camelCase to kebab-case in help text and usage information
* Parameter placeholders are also displayed in kebab-case (e.g., `--user-name <user-name>`)
* Negatable boolean options use kebab-case (e.g., `--no-auto-save` for `autoSave: { type: 'boolean', negatable: true, toKebab: true }`)

> \[!NOTE]
> The argument values are still accessed using the original camelCase keys in your code (e.g., `ctx.values.userName`), regardless of how they appear on the command line.

#### Negatable Boolean Options

Sometimes you need to explicitly disable a boolean option that might be enabled by default or through configuration files.

Negatable options solve this by providing both positive and negative forms of the same option.

To enable this (e.g., allowing both `--verbose` and `--no-verbose`), add the `negatable: true` property to the option's definition.

* If you define an option like `verbose: { type: 'boolean', negatable: true }`, Gunshi will recognize both `--verbose` and `--no-verbose`.
* If `-V` or `--verbose` is passed, the value will be `true`.
* If `--no-verbose` is passed, the value will be `false`.
* If neither is passed, the value will be `undefined` (unless a `default` is specified).
* The negative form does not take a value: `--no-verbose=false` is reported as an `err:arg:unexpected-value` error.

Without `negatable: true`, only the positive form (e.g., `--verbose`) is recognized, and passing it sets the value to `true`.

The positive form of any boolean option, negatable or not, can also be given a value with `=`: `--verbose=true` sets the value to `true`, and `--verbose=false` sets it to `false`. Any other value, such as `--verbose=0` or `--verbose=`, is reported as an `err:arg:invalid-type` error.

The description for the negatable option (e.g., `--no-verbose`) is automatically generated (e.g., "Negatable of --verbose"). You can customize this message using [internationalization resource files](../advanced/internationalization.md) by providing a translation for the specific `arg:no-<optionName>` key (e.g., `arg:no-verbose`).

`no-` is not reserved: an argument may be named `no-cache` or `no-emoji`, and it is then an option of its own, described by its own `description`. Declaring both `cache: { type: 'boolean', negatable: true }` and a separate `no-cache` argument is best avoided, though — a single `--no-cache` on the command line then sets a value for both of them.

The name that decides this is the one the argument is written under on the command line, not the key it is declared with. With `toKebab`, `noCache` is written `--no-cache` as well, so it takes the name from the negated form of `cache` the same way a literal `no-cache` does.

#### Conflicting Options

You can define mutually exclusive options using the `conflicts` property.

This ensures that conflicting options cannot be used together:

```js
import { define } from 'gunshi'

const command = define({
  name: 'server',
  description: 'Server configuration',
  args: {
    // These options are mutually exclusive
    verbose: {
      type: 'boolean',
      short: 'v',
      description: 'Enable verbose output',
      conflicts: 'quiet' // Cannot be used with --quiet
    },
    quiet: {
      type: 'boolean',
      short: 'q',
      description: 'Suppress all output',
      conflicts: 'verbose' // Cannot be used with --verbose
    },

    // Multiple conflicts
    development: {
      type: 'boolean',
      description: 'Development mode',
      conflicts: ['production', 'staging'] // Cannot be used with either
    },
    production: {
      type: 'boolean',
      description: 'Production mode',
      conflicts: ['development', 'staging']
    },
    staging: {
      type: 'boolean',
      description: 'Staging mode',
      conflicts: ['development', 'production']
    }
  },
  run: ctx => {
    // Only one of the conflicting options can be true
    if (ctx.values.verbose) {
      console.log('Verbose mode enabled')
    } else if (ctx.values.quiet) {
      // Minimal output
    }
  }
})
```

When conflicting options are used together, Gunshi will throw an error:

* Bidirectional conflict detection works with both long and short option forms
* Clear error messages indicate which options are conflicting
* Helps prevent invalid command configurations

### Examples

The `examples` property provides example commands showing how to use the CLI.

This helps users understand how to use your command correctly and is displayed in the help output.

#### Basic Examples

You can provide examples as a simple string:

```js
import { define } from 'gunshi'

const command = define({
  name: 'copy',
  description: 'Copy files',
  args: {
    source: {
      type: 'positional',
      description: 'Source file'
    },
    destination: {
      type: 'positional',
      description: 'Destination file'
    },
    recursive: {
      type: 'boolean',
      short: 'r',
      description: 'Copy recursively'
    }
  },
  examples: 'copy file1.txt file2.txt',
  run: ctx => {
    // Implementation
  }
})
```

#### Multiple Examples

For multiple examples, use a multi-line string with clear formatting:

```js
import { define } from 'gunshi'

const command = define({
  name: 'deploy',
  description: 'Deploy application',
  args: {
    environment: {
      type: 'string',
      short: 'e',
      required: true,
      description: 'Target environment'
    },
    tag: {
      type: 'string',
      short: 't',
      description: 'Version tag'
    },
    dryRun: {
      type: 'boolean',
      description: 'Perform a dry run'
    }
  },
  examples: `
# Deploy to production with a specific tag
deploy --environment production --tag v1.2.3

# Deploy to staging with dry run
deploy -e staging --dry-run

# Deploy to development (using short option)
deploy -e development

# Deploy with multiple options
deploy --environment production --tag latest --dry-run
  `.trim(),
  run: ctx => {
    // Implementation
  }
})
```

#### Dynamic Examples

You can also provide examples as a function that returns a string.

This is useful when examples need to be generated dynamically or localized:

```js
import { define } from 'gunshi'

const command = define({
  name: 'serve',
  description: 'Start development server',
  args: {
    port: {
      type: 'number',
      short: 'p',
      default: 3000,
      description: 'Port number'
    },
    host: {
      type: 'string',
      short: 'h',
      default: 'localhost',
      description: 'Host address'
    }
  },
  examples: ctx => {
    // Generate examples dynamically based on context
    const appName = ctx.name || 'serve'
    return `
# Start server with default settings
${appName}

# Start server on custom port
${appName} --port 8080

# Start server on all interfaces
${appName} --host 0.0.0.0 --port 3000

# Using short options
${appName} -h 192.168.1.100 -p 8080
    `.trim()
  },
  run: ctx => {
    console.log(`Server starting on ${ctx.values.host}:${ctx.values.port}`)
  }
})
```

#### Formatted Examples with Descriptions

For better readability, you can include descriptions with your examples:

```js
import { define } from 'gunshi'

const command = define({
  name: 'git-flow',
  description: 'Git flow commands',
  args: {
    feature: {
      type: 'string',
      description: 'Feature name'
    },
    hotfix: {
      type: 'string',
      description: 'Hotfix name'
    },
    release: {
      type: 'string',
      description: 'Release version'
    }
  },
  examples: `
Examples:
  # Start a new feature
  $ git-flow --feature user-authentication

  # Create a hotfix for production
  $ git-flow --hotfix critical-bug-fix

  # Prepare a new release
  $ git-flow --release 2.0.0

Notes:
  - Feature branches are created from develop
  - Hotfixes are created from master
  - Releases merge into both master and develop
  `.trim(),
  run: ctx => {
    // Implementation
  }
})
```

#### Async Examples

For complex CLIs that need to load examples from external files or generate them based on runtime conditions, you can use async functions.

When using the function form, you can return a Promise for async example generation:

```js
import { define } from 'gunshi'

const command = define({
  name: 'config',
  description: 'Manage configuration',
  args: {
    set: {
      type: 'string',
      description: 'Set configuration value'
    },
    get: {
      type: 'string',
      description: 'Get configuration value'
    }
  },
  examples: async ctx => {
    // Could load examples from external source
    const examples = await loadExamplesFromFile('config-examples.txt')
    return (
      examples ||
      `
# Set a configuration value
config --set "api.key=abc123"

# Get a configuration value
config --get "api.key"
    `.trim()
    )
  },
  run: ctx => {
    // Implementation
  }
})
```

The examples are displayed when users run the command with `--help` flag, making it easier for them to understand the correct usage.

### Command Execution

The `run` function receives a command context object (`ctx`) with:

* `args`: The command arguments configuration (`ArgSchema` object).
* `values`: An object containing the parsed and validated values for both named options (e.g., `ctx.values.name`) and positional arguments (accessed via their *key* from the `args` definition, e.g., `ctx.values.file`). Values are properly typed based on their argument definitions - strings, numbers, booleans, or custom parsed types.
* `explicit`: An object that tracks which arguments were explicitly provided by the user. Each property corresponds to an argument name and is `true` if the user explicitly provided it, `false` otherwise. This is useful for distinguishing between default values and user-provided values.
* `positionals`: An array of strings containing the raw values of the arguments identified as positional, in the order they were parsed. Useful if you need the original order, but `ctx.values.<key>` is generally recommended.
* `rest`: An array of strings containing arguments that appear after the `--` separator.
* `_`: The raw argument array passed to the `cli` function (original command line arguments).
* `tokens`: The raw tokens parsed by `args-tokens`.
* `omitted`: A boolean indicating if the command was run without specifying a subcommand name.
* `name`: The name of the *currently executing* command.
* `description`: The description of the *currently executing* command.
* `env`: The command environment settings (version, logger, renderers, etc.).
* `callMode`: Command call mode ('entry', 'subCommand', or 'unexpected') indicating how the command was invoked.
* `toKebab`: Boolean indicating whether camelCase argument names should be converted to kebab-case.
* `log`: Function for outputting messages that respects the `usageSilent` setting. Output that must still appear when `usageSilent` is set should use `console.log` / `console.warn`.
* `extensions`: Command context extensions for plugin functionality (available in v0.27.0+).
* `validationError`: Contains validation errors from argument parsing if any occurred.

#### Tracking Explicitly Provided Arguments

Among the context properties, the `explicit` property deserves special attention as it allows you to determine whether an argument was explicitly provided by the user or if it's using a default value:

```js
import { define } from 'gunshi'

const command = define({
  name: 'deploy',
  args: {
    environment: {
      type: 'string',
      default: 'development'
    },
    force: {
      type: 'boolean',
      default: false
    }
  },
  run: ctx => {
    // Check if the user explicitly provided the environment
    if (ctx.explicit.environment) {
      console.log(`User specified environment: ${ctx.values.environment}`)
    } else {
      console.log(`Using default environment: ${ctx.values.environment}`)
    }

    // Useful for conditional logic based on user intent
    if (ctx.explicit.force && ctx.values.force) {
      console.log('User explicitly requested force mode')
    }
  }
})
```

This feature is particularly useful for:

* Distinguishing between default values and user-provided values
* Implementing different behavior based on whether a user explicitly set an option
* Validation logic that needs to know if a value was user-provided
* Warning users when they're using default values for critical options

## CLI Configuration

When calling the `cli` function, you can provide additional configuration:

```js
await cli(process.argv.slice(2), command, {
  name: 'app-name',
  version: '1.0.0',
  description: 'Application description'
  // Additional configuration options
})
```

## Benefits of Declarative Configuration

Throughout this guide, you've seen how declarative configuration structures your CLI code. This approach provides several key advantages:

1. **Separation of concerns**: As shown in our examples, command definition stays separate from implementation logic
2. **Self-documentation**: The structure itself documents your command's capabilities, automatically generating help text
3. **Maintainability**: Clear structure makes commands easier to understand and modify as requirements change
4. **Consistency**: Enforces uniform patterns across all your commands, from simple to complex

## Next Steps

Now that you understand how to configure commands declaratively, you're ready to explore how Gunshi provides full type safety for your commands.

The next section on [Type Safe](./type-safe.md) will show you how to leverage TypeScript's type system to catch errors at compile time and get excellent IDE support while building your CLI applications.

With declarative configuration as your foundation, adding type safety will make your CLI development even more robust and developer-friendly.

---

---
url: /guide/essentials/type-safe.md
---
# Type Safe

In the previous chapter, we learned how to create commands using declarative configuration with plain JavaScript objects.

While this approach works well, TypeScript users can benefit from enhanced type safety and better development experience using Gunshi's `define` function.

The `define` function wraps your command configuration and provides automatic type inference, ensuring that your command handlers receive properly typed context objects without manual type annotations.

## Benefits of Type Safety

Using TypeScript with Gunshi's `define` function provides CLI-specific advantages:

* **Autocompletion for command options**: IDE suggests available options when accessing `ctx.values`
* **Prevent runtime errors**: Catch typos in option names before your CLI ships
* **Self-documenting commands**: Types show exactly what arguments your command accepts
* **Safe refactoring**: Rename options across your codebase with confidence

## Type Safety Levels in Gunshi

Gunshi provides different levels of type safety to match your needs:

1. **Basic type inference** (covered in this chapter): Automatic typing of command arguments
2. **Plugin extension typing**: Type-safe access to plugin functionality
3. **Full type parameters**: Complete control over all types using `GunshiParams`

This chapter focuses on the first level, which covers most common use cases. Advanced patterns are available when you need them.

## Using `define` for Type Safety

The `define` function transforms your command configuration to provide:

* **Automatic type inference**: No need to manually type `ctx` parameters
* **IDE autocompletion**: Get suggestions for `ctx.values` properties
* **Compile-time validation**: TypeScript catches typos and type mismatches before runtime
* **Simplified imports**: No need to import type definitions like `Command` or `CommandContext`

Let's transform the greeting command from the previous chapter to use `define` for full type safety.

The `define` function is a simple wrapper that preserves your command's type information, enabling TypeScript to automatically infer types for your command options and provide IDE autocompletion:

```ts [cli.ts]
import { cli, define } from 'gunshi'

// Define a command using the `define` function
const command = define({
  name: 'greet',
  args: {
    // Define a string option 'name' with a short alias 'n'
    name: {
      type: 'string',
      short: 'n',
      description: 'Your name'
    },
    // Define a number option 'age' with a default value
    age: {
      type: 'number',
      short: 'a',
      description: 'Your age',
      default: 30
    },
    // Define a boolean flag 'verbose'
    verbose: {
      type: 'boolean',
      short: 'V',
      description: 'Enable verbose output'
    }
  },
  // The 'ctx' parameter is automatically typed based on the args
  run: ctx => {
    // `ctx.values` is fully typed!
    const { name, age, verbose } = ctx.values

    // TypeScript knows the types:
    // - name: string | undefined (undefined if not provided)
    // - age: number (always a number due to the default)
    // - verbose: boolean | undefined (undefined if not provided, true if --verbose flag is used)

    let greeting = `Hello, ${name || 'stranger'}!`
    // age always has a value due to the default
    greeting += ` You are ${age} years old.`

    console.log(greeting)

    if (verbose) {
      console.log('Verbose mode enabled.')
      console.log('Parsed values:', ctx.values)
    }
  }
})

// Execute the command
await cli(process.argv.slice(2), command)
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/essentials/type-safe).

With `define`:

* You don't need to import types like `Command` or `CommandContext`.
* The `ctx` parameter in the `run` function automatically gets the correct type, derived from the `args` definition.
* Accessing `ctx.values.optionName` provides type safety and autocompletion based on the option's `type` and whether it has a `default`.
  * Options without a `default` (like `name`) are typed as `T | undefined`.
  * Options with a `default` (like `age`) are typed simply as `T`.
  * Boolean flags without a `default` (like `verbose`) are typed as `boolean | undefined`.

> \[!NOTE]
> For boolean options that need both positive and negative forms (e.g., `--verbose` and `--no-verbose`), see the [Negatable Boolean Options](./declarative.md#negatable-boolean-options) section in the declarative configuration guide.

This approach significantly simplifies creating type-safe CLIs with Gunshi.

> \[!TIP]
> For even stronger type inference with composable argument schemas, check out [Parser Combinators](../advanced/parser-combinators.md).
> Parser combinators provide functional factory functions like `string()`, `integer()`, `withDefault()`, and `required()` that automatically infer precise types without manual annotations.

## When to Use `define`

Use the `define` function when:

* You're writing TypeScript and want automatic type inference
* You need IDE autocompletion for command context
* You want to catch type-related errors at compile time

Use plain objects (as shown in the previous chapter) when:

* You're writing plain JavaScript
* You prefer explicit type annotations
* You're integrating with existing type definitions

## Advanced Type Parameters

While the examples above show the simplest form of the `define` function, Gunshi provides more advanced type parameter patterns for complex scenarios:

* **Plugin extensions**: Type-safe access to plugin-provided functionality
* **Explicit argument types**: Fine-grained control over type inference
* **GunshiParams utility**: Combined typing of arguments and extensions

These advanced patterns are covered in detail in the [Advanced Type System](../advanced/type-system.md) documentation.

For most commands, the basic `define` usage shown above provides sufficient type safety.

## Next Steps

Now that you understand how to create type-safe commands with `define`, you're ready to explore more advanced features:

* **Composable Sub-commands**: Learn how type safety extends to multi-command CLIs
* **Plugin System**: Discover how plugins maintain type safety across extensions
* **Advanced Type System**: For complex scenarios, Gunshi offers additional type parameters and patterns (covered in the [Advanced Type System](../advanced/type-system.md) documentation)

In the next chapter, we'll explore how to create [composable sub-commands](./composable.md) while maintaining the type safety we've established here.

---

---
url: /guide/essentials/composable.md
---
# Composable Sub-commands

In [the previous chapter](./type-safe.md), you learned how to create type-safe commands using the `define` function.

Now, let's extend that knowledge to build CLIs with multiple sub-commands while maintaining the same type safety benefits.

Gunshi's composable sub-command system allows you to create modular, organized CLIs similar to tools like Git (with commands like `git commit` and `git push`).

## Why Use Sub-commands?

Sub-commands are useful when your CLI needs to perform different operations that warrant separate commands.

Benefits include:

* **Organization**: Group related functionality logically
* **Scalability**: Add new commands without modifying existing ones
* **User experience**: Provide a consistent interface for different operations
* **Help system**: Each sub-command can have its own help documentation
* **Plugin integration**: Plugins are shared across all sub-commands for consistent functionality

## Basic Structure

A CLI with sub-commands typically has this structure:

```sh
cli <command> [command options]
```

For example:

```sh
your-cli create --name my-resource
```

## Creating Type-Safe Sub-commands

Building on the `define` function from the previous chapter, let's create a CLI with multiple sub-commands:

```ts [cli.ts]
import { cli, define } from 'gunshi'

// Define type-safe sub-commands
const createCommand = define({
  name: 'create',
  description: 'Create a new resource',
  args: {
    name: { type: 'string', short: 'n', required: true }
  },
  run: ctx => {
    // ctx.values is fully typed
    console.log(`Creating resource: ${ctx.values.name}`)
  }
})

const listCommand = define({
  name: 'list',
  description: 'List all resources',
  run: () => {
    console.log('Listing all resources...')
  }
})

// Define the main command
const mainCommand = define({
  name: 'manage',
  description: 'Manage resources',
  run: ctx => {
    // This runs when no sub-command is provided
    console.log('Available commands: create, list')
    console.log('Run "manage --help" for more information')
  }
})

// Run the CLI with composable sub-commands
await cli(process.argv.slice(2), mainCommand, {
  name: 'my-app',
  version: '1.0.0',
  subCommands: {
    create: createCommand,
    list: listCommand
  }
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/essentials/composable/basic).

This structure provides:

* Full type safety for all commands and sub-commands
* Automatic help generation for each command level
* Shared configuration across the command hierarchy

## Automatic Help for Sub-commands

Gunshi automatically generates help documentation for your sub-commands.

Using the code from the previous section, you can see the help for each command level:

```sh
# Show main command help
$ npx tsx cli.ts --help

# Show sub-command help
$ npx tsx cli.ts create --help
```

> \[!TIP]
> [`tsx`](https://github.com/privatenumber/tsx) is a TypeScript execution tool that allows you to run TypeScript files directly without compilation. Use it directly with `npx tsx`.

> \[!NOTE]
> On Node.js v22.6.0, you can run TypeScript with `--experimental-strip-types`:
>
> ```sh
> node --experimental-strip-types cli.ts --help
> ```
>
> From Node.js v23.6.0 and newer, type stripping is enabled by default (no flag needed for erasable TS). Features requiring transformation (e.g., `enum`) still need `--experimental-transform-types`.

Each sub-command's help includes its description, available options, and usage examples.

## Organizing Your Commands

As your CLI grows, organizing commands in separate files improves maintainability.

Here's a recommended project structure:

```sh
my-cli/
├── src/
│   ├── commands/
│   │   ├── create.ts      # Create command implementation
│   │   └── list.ts        # List command implementation
│   ├── main.ts            # Main command definition
│   └── cli.ts             # CLI entry point
├── package.json
└── tsconfig.json
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/essentials/composable/organizing).

This structure provides:

* Clear separation of concerns
* Shared utilities across commands
* Centralized type definitions
* Easy testing of individual components

### Individual Command Files

```ts [commands/create.ts]
import { define } from 'gunshi'

export default define({
  name: 'create',
  description: 'Create a new resource',
  args: {
    name: {
      type: 'string',
      short: 'n',
      required: true,
      description: 'Name of the resource'
    },
    type: {
      type: 'string',
      short: 't',
      default: 'default',
      description: 'Type of resource'
    }
  },
  run: ctx => {
    console.log(`Creating ${ctx.values.type} resource: ${ctx.values.name}`)
  }
})
```

```ts [commands/list.ts]
import { define } from 'gunshi'

export default define({
  name: 'list',
  description: 'List all resources',
  args: {
    filter: {
      type: 'string',
      short: 'f',
      description: 'Filter resources'
    }
  },
  run: ctx => {
    const filter = ctx.values.filter || 'all'
    console.log(`Listing resources with filter: ${filter}`)
  }
})
```

### Main Command File

```ts [main.ts]
import { define } from 'gunshi'

export default define({
  name: 'manage',
  description: 'Manage resources',
  run: () => {
    console.log('Use a sub-command')
    console.log('Run "resource-manager --help" for available commands')
  }
})
```

### Entry Point

> \[!NOTE]
> Some code examples in this guide include TypeScript file extensions (`.ts`) in import/export statements. If you use this pattern in your application, you'll need to enable `allowImportingTsExtensions` in your `tsconfig.json`.

```ts [cli.ts]
import { cli } from 'gunshi'
import main from './main.ts'
import create from './commands/create.ts'
import list from './commands/list.ts'

await cli(process.argv.slice(2), main, {
  name: 'resource-manager',
  version: '1.0.0',
  subCommands: {
    create,
    list
  }
})
```

## Handling Unknown Sub-commands

By default, Gunshi shows an error when users provide an unknown sub-command.

You can customize this behavior using the `fallbackToEntry` option:

```ts [cli.ts]
await cli(process.argv.slice(2), main, {
  name: 'resource-manager',
  version: '1.0.0',
  fallbackToEntry: true,
  subCommands: {
    create,
    list
  }
})
```

This option enables flexible command handling:

```sh
# Runs the create sub-command
npx tsx src/cli.ts create --name resource
resource-manager (resource-manager v1.0.0)

Creating default resource: resource

# Runs the list sub-command
npx tsx src/cli.ts list --filter active
resource-manager (resource-manager v1.0.0)

Listing resources with filter: active

# Falls back to main command when "unknown" sub-command is not found
npx tsx src/cli.ts unknown --flag value
resource-manager (resource-manager v1.0.0)

Use a sub-command
Run "resource-manager --help" for available commands

# Runs the main command directly
npx tsx src/cli.ts --help
resource-manager (resource-manager v1.0.0)

USAGE:
  resource-manager [COMMANDS] <OPTIONS>

COMMANDS:
  [manage]                  Manage resources
  create <OPTIONS>          Create a new resource
  list <OPTIONS>            List all resources

For more info, run any command with the `--help` flag:
  resource-manager --help
  resource-manager create --help
  resource-manager list --help

OPTIONS:
  -h, --help             Display this help message
  -v, --version          Display this version
```

This approach is particularly useful for CLIs that:

* Need to handle file paths or patterns as direct arguments
* Want to provide a default action when no sub-command matches
* Implement dynamic command resolution based on context

## Nested Sub-Commands

Gunshi also supports nested sub-commands for building hierarchical command trees like `git remote add`. You can add a `subCommands` property to any command definition:

```ts [cli.ts]
import { cli, define } from 'gunshi'

const addCommand = define({
  name: 'add',
  description: 'Add a remote',
  args: { url: { type: 'string', required: true } },
  run: ctx => console.log(`Adding: ${ctx.values.url}`)
})

const remoteCommand = define({
  name: 'remote',
  description: 'Manage remotes',
  subCommands: { add: addCommand },
  run: () => console.log('Use: remote add')
})

const entry = define({
  name: 'main',
  description: 'Git-like CLI',
  run: () => console.log('Run --help for available commands')
})

await cli(process.argv.slice(2), entry, {
  name: 'git',
  subCommands: { remote: remoteCommand }
})
```

For more details on nested sub-commands, including lazy loading, intermediate command handling, and `commandPath`, see the [Nested Sub-Commands](../advanced/nested-sub-commands.md) guide.

## Next Steps

Throughout this guide, you've learned how to build composable sub-commands that scale from simple to complex CLI applications.

You've seen how Gunshi maintains type safety across nested command structures, enables powerful routing patterns with default commands, and supports both synchronous and asynchronous command execution.

Now that you understand how to compose commands into well-organized hierarchies, you're ready to explore how to optimize their performance.

The next section on [Lazy & Async Command Loading](./lazy-async.md) will show you how to significantly improve your CLI's startup time by loading commands only when they're actually needed.

With composable sub-commands as your foundation, adding lazy loading will make your CLI applications both powerful and performant, especially as they grow to include many commands with varying resource requirements.

---

---
url: /guide/essentials/lazy-async.md
---
# Lazy & Async Command Loading

> \[!NOTE]
> This chapter continues using TypeScript for code examples, building upon the type safety concepts introduced in the [previous chapter](./type-safe.md). While all Gunshi features work with JavaScript, the TypeScript examples provide better IDE support and compile-time checking.

When building CLI applications with many commands or commands that require heavy dependencies, you may encounter slow startup times that frustrate users.

Even simple operations like displaying help text can take seconds if your CLI loads all command implementations upfront.

This guide shows you how to use Gunshi's lazy loading and asynchronous execution features to create fast, responsive CLI applications that only load what they need, when they need it.

## Benefits of Lazy Loading

Lazy loading provides immediate improvements to your CLI application:

* **Faster Startup Time**: Commands are only loaded when actually executed, not when displaying help or running other commands
* **Reduced Memory Usage**: Unexecuted commands and their dependencies stay unloaded, keeping memory footprint minimal
* **Better Code Splitting**: When bundling your CLI, each command can be a separate chunk that loads on demand
* **Improved User Experience**: Users see instant help text and quick responses for simple commands

These benefits become especially valuable as your CLI grows to include dozens or hundreds of commands, each potentially requiring different libraries or complex initialization.

## Basic Lazy Loading

Let's start with a simple example that demonstrates the core concept.

The following code shows how to create a lazy-loaded command that only loads its implementation when executed:

```ts [cli.ts]
import { cli, define, lazy } from 'gunshi'
import type { CommandRunner, CommandContext } from 'gunshi'

// Define the command without command runner separately
const helloDefinition = define({
  name: 'hello',
  description: 'A greeting command',
  args: {
    name: {
      type: 'string',
      description: 'Name to greet',
      default: 'world'
    }
  }
})

// Create a loader function that returns the command implementation
const helloLoader = async (): Promise<CommandRunner> => {
  console.log('Loading hello command runner ...')

  // The actual command runner logic is defined here
  const run = (ctx: CommandContext) => {
    console.log(`Hello, ${ctx.values.name}!`)
  }

  return run // Return the runner function
}

// Combine them using the lazy helper
const lazyHello = lazy(helloLoader, helloDefinition)

// Use the lazy command in your CLI
const subCommands = {
  [lazyHello.commandName]: lazyHello
}

await cli(
  process.argv.slice(2),
  {
    description: 'My CLI application',
    run: () => console.log('Run a sub-command with --help for more info')
  },
  {
    name: 'my-app',
    version: '1.0.0',
    subCommands
  }
)
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/essentials/lazy-async/basic).

In this example, when a user runs `npx tsx cli.ts --help`, Gunshi displays help text using only the metadata from `helloDefinition`.

The `helloLoader` function is never called.

Only when the user runs `npx tsx cli.ts hello` does Gunshi execute the loader and run the command.

When an option appears before a lazy command name, the second argument to `lazy()` must declare the
option information needed to identify the command. Keep the routing fields (`type`, `short`,
`negatable`, and `toKebab`) in the metadata; value conversion and validation still happen after the
loader runs:

```ts
const deploy = lazy(loadDeploy, {
  name: 'deploy',
  args: {
    config: { type: 'string', short: 'c' }
  }
})

// Selects deploy, then loads it once.
await cli(['--config', 'prod.json', 'deploy'], entry, {
  subCommands: { deploy }
})
```

If the loaded command changes the schema used to route a leading option, Gunshi reports a lazy
schema-mismatch error instead of retrying another command. Moving the option after the command name
is the compatibility path when the option is loader-only.

> \[!TIP]
> The command name is accessed via `commandName` property (not `name`) when using lazy commands. This is because lazy commands are functions, and the `name` property is reserved by the JavaScript runtime.

A lazy command can also be used as the entry command without a definition name. Gunshi still
uses the arguments from the definition and runs the loader before the returned runner:

```ts
const entry = lazy(
  async () => ctx => {
    console.log(`Building ${ctx.values.target}`)
  },
  {
    args: {
      target: { type: 'string', required: true }
    }
  }
)

await cli(['--target', 'prod'], entry, { name: 'my-cli' })
```

When a lazy command has no definition name, `commandName` is `undefined`. This is different from
the CLI name in `CliOptions.name`; the latter identifies the application, while the lazy command
is the default entry used when no sub-command is selected.

## Dynamic Imports for Code Splitting

For real-world applications, you'll typically want to use dynamic imports to load command implementations from separate files.

This enables bundlers to create separate chunks for each command:

```ts [cli.ts]
import { cli, define, lazy } from 'gunshi'
import type { CommandRunner } from 'gunshi'

// Command metadata stays in the main bundle
const buildDefinition = define({
  name: 'build',
  description: 'Build the project',
  args: {
    watch: {
      type: 'boolean',
      short: 'w',
      description: 'Watch for changes'
    },
    minify: {
      type: 'boolean',
      short: 'm',
      description: 'Minify output'
    }
  }
})

// Loader uses dynamic import to load the command from a separate file
const buildLoader = async (): Promise<CommandRunner> => {
  // This creates a separate chunk in your bundle
  const { run } = await import('./commands/build.ts')
  return run
}

const lazyBuild = lazy(buildLoader, buildDefinition)

// Add more commands following the same pattern
const deployDefinition = define({
  name: 'deploy',
  description: 'Deploy to production',
  args: {
    environment: {
      type: 'string',
      short: 'e',
      default: 'production'
    }
  }
})

const deployLoader = async (): Promise<CommandRunner> => {
  const { run } = await import('./commands/deploy.ts')
  return run
}

const lazyDeploy = lazy(deployLoader, deployDefinition)

// Register all lazy commands
const subCommands = {
  [lazyBuild.commandName]: lazyBuild,
  [lazyDeploy.commandName]: lazyDeploy
}

await cli(
  process.argv.slice(2),
  {
    description: 'Development tools CLI',
    run: () => console.log('Use --help to see available commands')
  },
  {
    name: 'dev-tools',
    version: '2.0.0',
    subCommands
  }
)
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/essentials/lazy-async/dynamic-import).

> \[!IMPORTANT]
> The examples above use `.ts` extensions in dynamic import paths (`await import('./commands/build.ts')`). This will work in the following scenarios:
>
> * **During development**: When using TypeScript execution tools like `tsx`, `ts-node`, or Bun's native TypeScript support
> * **Node.js with experimental support**: When running Node.js v22.6.0+ with the `--experimental-strip-types` flag (renamed to `--experimental-transform-types` in v22.7.0+)
>
> **For production builds with TypeScript compilation**:
> TypeScript does NOT rewrite import paths during compilation. If you plan to compile your TypeScript:
>
> * Use `.js` extensions in your source code: `await import('./commands/build.js')`
> * These `.js` imports will correctly resolve to the compiled JavaScript files
> * Alternatively, configure your bundler (rolldown, rollup, esbuild, webpack) to handle `.ts` extensions
>
> For standard JavaScript projects, use `.js` extensions:
>
> ```ts
> const { run } = await import('./commands/build.js')
> ```

With this approach, your bundler (rolldown, rollup, esbuild, webpack, etc.) will automatically create separate chunks for `./commands/build.ts` and `./commands/deploy.ts`. Users only download and parse the code for commands they actually use.

> \[!NOTE]
> On Node.js v23.6.0 and newer, type stripping is enabled by default so erasable TypeScript runs without flags; transformations (e.g., `enum`) still require `--experimental-transform-types`.

## Async Command Execution

Gunshi seamlessly supports asynchronous command execution, which is essential for commands that perform I/O operations, network requests, or other async tasks. Building on lazy loading, your command runners can be async functions:

```ts [cli.ts]
import { cli, define, lazy } from 'gunshi'
import type { Command, CommandContext, CommandRunner, GunshiParams } from 'gunshi'

// Mock implementations that simulate async file operations
// These work without requiring actual files on disk
async function readFile(path: string): Promise<string> {
  // Simulate async file read with a small delay
  await new Promise(resolve => setTimeout(resolve, 100))
  return `Sample data from ${path}`
}

async function transform(data: string): Promise<string> {
  // Simulate async data transformation
  await new Promise(resolve => setTimeout(resolve, 150))
  return data.toUpperCase() + '\n[TRANSFORMED]'
}

async function writeFile(path: string, data: string): Promise<void> {
  // Simulate async file write
  await new Promise(resolve => setTimeout(resolve, 100))
  console.log(`  Written to ${path}: "${data}"`)
}

// Alternative: Use real Node.js file operations
// import { readFile as fsReadFile, writeFile as fsWriteFile } from 'node:fs/promises'
//
// async function readFile(path: string): Promise<string> {
//   return await fsReadFile(path, 'utf-8')
// }
//
// async function transform(data: string): Promise<string> {
//   // Your actual transformation logic here
//   return data.toUpperCase()
// }
//
// async function writeFile(path: string, data: string): Promise<void> {
//   await fsWriteFile(path, data, 'utf-8')
// }

const processDataDefinition = define({
  name: 'process',
  description: 'Process data asynchronously',
  args: {
    input: {
      type: 'string',
      short: 'i',
      description: 'Input file path',
      required: true
    },
    output: {
      type: 'string',
      short: 'o',
      description: 'Output file path',
      required: true
    }
  }
})

const processDataLoader = async (): Promise<
  CommandRunner<GunshiParams<{ args: typeof processDataDefinition.args }>>
> => {
  // Return an async runner function
  return async ctx => {
    // TypeScript knows ctx.values has 'input' (string) and 'output' (string)
    const { input, output } = ctx.values

    console.log(`Processing ${input}...`)

    // Simulate async operations
    const data = await readFile(input)
    const processed = await transform(data)
    await writeFile(output, processed)

    console.log(`Successfully processed to ${output}`)
  }
}

const lazyProcess = lazy(processDataLoader, processDataDefinition)

// The CLI handles async execution automatically
const subCommands = {
  [lazyProcess.commandName]: lazyProcess
}

await cli(
  process.argv.slice(2),
  {
    description: 'Data processing CLI',
    run: () => console.log('Use process command to transform data')
  },
  {
    name: 'data-cli',
    version: '1.0.0',
    subCommands
  }
)
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/essentials/lazy-async/async).

Gunshi automatically handles the asynchronous execution, including proper error handling and process exit codes.

You don't need any special configuration—just return an async function from your loader.

## Alternative Loader Return Types

While the examples above show loaders returning runner functions, loaders can also return full Command objects.

This is useful when you want to dynamically construct the entire command structure:

```ts [cli.ts]
import { cli, define, lazy } from 'gunshi'

const configLoader = async () => {
  // Simulate loading configuration (in practice, read from file/API)
  const isDebug = process.env.DEBUG === 'true'

  return define({
    description: `Config command (debug: ${isDebug})`,
    args: {
      verbose: {
        type: 'boolean',
        description: isDebug ? 'Verbose output (DEBUG mode)' : 'Verbose output'
      }
    },
    run: ctx => {
      console.log(isDebug ? 'Running in DEBUG mode' : 'Running in normal mode')
      if (ctx.values.verbose) {
        console.log('Verbose:', ctx.values.verbose)
      }
    }
  })
}

// The definition (2nd parameter) is used without calling the loader, e.g. for the command list.
// Once loaded, the loaded command takes precedence, and the definition is the fallback
const config = lazy(configLoader, {
  name: 'config',
  description: 'Dynamically configured command'
})

await cli(
  process.argv.slice(2),
  { description: 'CLI with dynamic commands', run: () => {} },
  { name: 'my-cli', version: '1.0.0', subCommands: { config } }
)
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/essentials/lazy-async/dynamic-command)

This pattern is particularly useful when command structure depends on runtime configuration or external data sources.

When the loader returns a Command object, Gunshi resolves the command from both the loaded command and the definition passed as the second parameter of `lazy`:

* **The loaded command takes precedence**: A property that the loaded command defines is used, even if the definition has it too
* **The definition is the fallback**: A property that the loaded command does not define is taken from the definition, so a loader that returns only `{ run }` behaves the same as a loader that returns the runner function
* **Properties are not merged**: If both of them define a property such as `args` or `rendering`, the whole value of the loaded command is used

In the example above, `my-cli config --help` shows the description `Config command (debug: false)` and the `--verbose` option, which come from the loaded command. On the other hand, `my-cli --help` lists the command as `Dynamically configured command`, because the command list is rendered from the definition without calling the loader.

## Performance Considerations

To maximize the benefits of lazy loading:

1. **Keep loaders lightweight**: The loader function itself should be minimal. Put heavy imports and initialization inside the returned runner function or use dynamic imports.

2. **Group related commands**: If multiple commands share dependencies, consider loading them together to avoid redundant imports.

3. **Monitor bundle sizes**: Use your bundler's analysis tools to verify that commands are properly code-split into separate chunks.

4. **Consider startup frequency**: Commands that are frequently used together might benefit from being in the same chunk, while rarely-used commands should definitely be lazy-loaded.

## Next Steps

Now that you understand lazy loading and async execution in Gunshi, you've learned how to optimize your CLI's performance by loading commands only when needed.

You can create fast, responsive CLIs that handle complex asynchronous operations efficiently while keeping startup times minimal.

The next section on [Auto Usage Generation](./auto-usage.md) will show you how Gunshi automatically creates comprehensive help documentation for all your commands—including lazy-loaded ones.

You'll learn how to enhance your CLI's user experience with well-structured usage information, examples, and command descriptions.

With lazy loading keeping your CLI fast and auto-generated usage making it user-friendly, you'll have all the essential tools to build professional command-line applications with Gunshi.

---

---
url: /guide/essentials/auto-usage.md
---
# Auto Usage Generation

Gunshi automatically generates comprehensive usage information for your commands, ensuring your CLI is self-documenting and user-friendly without additional effort.

## How Auto Usage Works

When you define a command with Gunshi, the library automatically:

* Adds `--help` and `-h` flags to every command
* Adds `--version` and `-v` flags when you provide a version in the CLI options
* Generates formatted usage text based on your command configuration
* Displays usage information when users request help or provide invalid arguments
* Includes descriptions, examples, and type information you provide

The generated usage follows standard CLI conventions, making your application immediately familiar to users.

## Understanding Bracket Notation

Gunshi uses consistent bracket notation throughout the generated usage to indicate whether elements are required or optional:

### Angle Brackets `<>` - Required Elements

Angle brackets indicate required elements or parameters without default values:

* `<OPTIONS>` - The command has required options (at least one option without a default value)
* `<name>` - An option parameter that must be provided (no default value)
* `<positional>` - A required positional argument

Example:

```sh
USAGE:
  app <OPTIONS>

OPTIONS:
  -n, --name <name>    Name to use (required)
```

### Hiding Internal Options

If you need to support options for backward compatibility or internal workflows without showing them in `--help`, set `hidden: true` on the argument schema (or apply the `hidden()` combinator).

The option continues to be accepted and parsed at runtime, but it is omitted from the `OPTIONS` section and usage symbols.

It is left out of the other places a user could discover it, too: shell completion does not offer it and does not complete its value, and the `Did you mean` hint for an unknown option does not suggest it.

### Square Brackets `[]` - Optional Elements

Square brackets indicate optional elements or parameters with default values:

* `[name]` - An option parameter with a default value
* `[<positional>]` - An optional positional argument
* `[<positional> ...]` - Optional multiple positional arguments
* `[COMMANDS]` - Sub-command selection (when multiple commands exist)
* `[commandName]` - A default command that runs when no sub-command is specified

Example:

```sh
USAGE:
  app [COMMANDS]

COMMANDS:
  [manage]    Default command for managing resources

OPTIONS:
  -t, --type [type]    Resource type (default: standard)
```

This notation provides immediate visual feedback about what users must provide versus what they can omit, making your CLI more intuitive to use.

> \[!TIP]
> Auto-usage generation is powered by the `@gunshi/plugin-renderer` plugin, which is automatically included when you use the standard `cli()` function. This plugin handles all help text rendering and formatting.

## Generated Help Output

Gunshi transforms your command definitions into professional help documentation.

Here's what users see when they request help.

### Basic Command Help

For a simple command with basic configuration (see [Getting Started](./getting-started.md) for implementation details), running with `--help` displays:

```sh
A greeting CLI (greet-cli v1.0.0)

USAGE:
  greet-cli <OPTIONS>

OPTIONS:
  -h, --help                 Display this help message
  -v, --version              Display this version
  -n, --name <name>          Name to greet
  -u, --uppercase            Convert greeting to uppercase
```

> \[!NOTE]
> The `--help` flag is automatically added - you never need to define it manually.

### Help with Arguments and Examples

When your command includes argument definitions and examples (see [Declarative Configuration](./declarative.md) for how to define these), the generated help becomes more comprehensive:

```sh
app (app v1.0.0)

USAGE:
  app <OPTIONS>

OPTIONS:
  -p, --path <path>                    File or directory path to operate on
  -r, --recursive                      Operate recursively on directories
  --no-recursive                       Negatable of -r, --recursive
  -o, --operation <operation>          Operation to perform: list, copy, move, or delete
  -h, --help                           Display this help message
  -v, --version                        Display this version

EXAMPLES:
  # List files in current directory
  $ app --operation list

  # Copy files recursively
  $ app --operation copy --path ./source --recursive

  # Delete files
  $ app --operation delete --path ./temp
```

> \[!IMPORTANT]
> Boolean options automatically receive a negatable version with the `--no-` prefix. This allows users to explicitly disable boolean flags.

## Customizing Help Output

### Displaying Option Types

Enable type display in the usage output to help users understand what value each option expects:

```js
await cli(process.argv.slice(2), command, {
  name: 'app',
  version: '1.0.0',
  usageOptionType: true // Enable type display
})
```

This adds type information to each option:

```sh
OPTIONS:
  -p, --path <path>              [string]   File or directory path to operate on
  -r, --recursive                [boolean]  Operate recursively on directories
  --no-recursive                 [boolean]  Negatable of -r, --recursive
  -o, --operation <operation>    [string]   Operation to perform: list, copy, move, or delete
  -h, --help                     [boolean]  Display this help message
  -v, --version                  [boolean]  Display this version
```

## Sub-command Help Generation

For CLIs with sub-commands (see [Composable Sub-commands](./composable.md) for implementation), Gunshi generates hierarchical help documentation.

### Main Command Help

When users run the main command with `--help`:

```sh
resource-manager (resource-manager v1.0.0)

USAGE:
  resource-manager [COMMANDS] <OPTIONS>

COMMANDS:
  [manage]                  Manage resources
  create <OPTIONS>          Create a new resource
  list <OPTIONS>            List all resources

For more info, run any command with the `--help` flag:
  resource-manager --help
  resource-manager create --help
  resource-manager list --help

OPTIONS:
  -h, --help             Display this help message
  -v, --version          Display this version
```

> \[!NOTE]
> The brackets in `[manage]` indicate it's the default command that runs when no sub-command is specified.
> Each row describes the arguments that its own command declares, so a command with no options of its own
> has no `<OPTIONS>` next to it.

### Sub-command Specific Help

Each sub-command has its own help, accessible via `command --help`. The below `create --help`:

```sh
resource-manager (resource-manager v1.0.0)

Create a new resource

USAGE:
  resource-manager create <OPTIONS>

OPTIONS:
  -h, --help                 Display this help message
  -v, --version              Display this version
  -n, --name <name>          Name of the resource
  -t, --type [type]          Type of resource (default: default)
```

### Positional Arguments Display

When commands accept positional arguments (arguments without flags), they appear in the `ARGUMENTS` line:

```sh
resource-manager (resource-manager v1.0.0)

Manage resources

USAGE:
  resource-manager manage <OPTIONS> <resource>

ARGUMENTS:
  resource           Type of resource to manage (e.g., user, project)

OPTIONS:
  -h, --help             Display this help message
  -v, --version          Display this version
```

Positional arguments are displayed with clear, descriptive names that indicate their purpose. Required positional arguments use angle brackets (e.g., `<resource>`), while optional positional arguments use square brackets (e.g., `[<query>]`). Multiple positional arguments are shown as `[<file> ...]`, or `<file> [<file> ...]` when at least one value is required.

## Automatic Features

Gunshi provides several automatic features without requiring any configuration:

### Help Flag (`--help`, `-h`)

* Automatically added to all commands
* Displays usage information and exits
* Works at every command level (main and sub-commands)

### Version Flag (`--version`, `-v`)

* Automatically added when you provide a `version` in CLI options
* Displays the version and exits
* Available at all command levels

### Negatable Boolean Options

* Boolean options automatically get `--no-` prefixed versions
* Allows explicit disabling of boolean flags
* Example: `--recursive` automatically creates `--no-recursive`

### Invalid Argument Handling

* Usage is automatically displayed when users provide invalid arguments
* Helps users understand what went wrong
* Provides immediate guidance for correct usage

## Key Points

When working with auto-generated usage:

* The `--help` flag is automatically added to all commands - you don't need to define it
* Usage is displayed when users provide invalid arguments or explicitly request help
* Descriptions in your `args` configuration become the help text for each option
* The `examples` field accepts both single strings and multi-line strings for multiple examples
* Sub-command help is accessible both from the main help and individually via `command --help`
* Required options are shown with angle brackets `<option>` in the USAGE line
* Boolean options automatically get negatable versions (`--no-` prefix) when not required
* The `usageOptionType` CLI option adds type annotations to help output

## Next Steps

Learn about the [Plugin System](./plugin-system.md) to extend functionality.

---

---
url: /guide/essentials/plugin-system.md
---
# Plugin System

## What's a Plugin?

A plugin in Gunshi is a modular extension that adds functionality to your CLI application without modifying its core code.

Think of plugins as building blocks that you can snap together to create powerful command-line tools.

### Why Use Plugins?

Plugins solve common CLI development challenges:

* **Separation of Concerns**: Plugins keep your command logic clean by handling cross-cutting functionality like logging, authentication, or database connections separately. Your commands focus on their primary task while plugins handle the supporting infrastructure.
* **Reusability**: Write functionality once, use it everywhere. A plugin created for one command can be reused across your entire CLI or even in different projects, saving development time and ensuring consistency.
* **Composability**: Plugins work together seamlessly. You can combine multiple plugins—an authentication plugin with a logging plugin and a database plugin—and they'll integrate naturally into your CLI's lifecycle.

### How Plugins Work

Plugins integrate at specific points in your CLI's execution:

1. **Registration**: When your CLI starts, plugins are registered and their dependencies are resolved
2. **Setup**: Plugins initialize and configure themselves, adding any global options (like `--debug`)
3. **Extension**: Plugins extend your command context with new functionality (like translation methods or API clients)
4. **Decoration**: Plugins can modify how commands execute or how help text is displayed
5. **Execution**: Your commands run with all plugin enhancements seamlessly integrated

This lifecycle integration means plugins can:

* Add global options available to all commands (like `--debug` or `--verbose`)
* Provide utilities accessible in any command (like API clients or database connections)
* Modify how your CLI displays help text or handles errors
* Intercept command execution for logging or validation

The beauty of Gunshi's plugin system is that it handles all the complexity behind the scenes.

You simply declare which plugins you want to use, and they automatically become part of your CLI's capabilities.

Now that you understand how plugins work, let's explore the plugins that come with Gunshi.

These built-in plugins provide essential CLI functionality out of the box.

## Built-in Plugins

Gunshi provides a standard `cli()` function that comes pre-configured with two essential plugins.

These built-in plugins give your CLI the familiar behavior users expect from command-line tools.

Let's explore what each plugin provides:

### @gunshi/plugin-global

This plugin adds `--help` and `--version` options to all your commands automatically.

When either option is used, the plugin intercepts command execution to display the appropriate information.

The following example demonstrates how the cli() function automatically includes the global plugin:

```js
import { cli, define } from 'gunshi'

const command = define({
  name: 'app',
  description: 'My CLI application',
  run: ctx => {
    console.log('Running application')
  }
})

await cli(process.argv.slice(2), command, {
  name: 'my-app',
  version: '1.0.0'
})
```

Now your CLI automatically supports:

* `my-app --help` displays usage information rendered by the renderer plugin
* `my-app --version` displays the version number
* The plugin decorates command execution to handle these options before your command runs

### @gunshi/plugin-renderer

The renderer plugin automatically formats help text, usage information, and validation errors.

It works behind the scenes to ensure consistent, readable output across your entire CLI.

## Using Optional Plugins

Optional plugins add specialized features to your CLI.

Install them separately and configure them based on your needs.

### Internationalization

Add multi-language support with the i18n plugin:

::: code-group

```sh [npm]
npm install --save @gunshi/plugin-i18n
```

```sh [pnpm]
pnpm add @gunshi/plugin-i18n
```

```sh [yarn]
yarn add @gunshi/plugin-i18n
```

```sh [deno]
# For Deno projects, you can add Gunshi from JSR:
deno add jsr:@gunshi/plugin-i18n
```

```sh [bun]
bun add @gunshi/plugin-i18n
```

:::

Here's a simple example using the `defineI18n` helper:

```js
import { cli } from 'gunshi'
import i18n, { defineI18n, resolveKey } from '@gunshi/plugin-i18n'

// Define resources inline for each locale
const resources = {
  'en-US': {
    greeting: 'Hello, {$name}!',
    farewell: 'Goodbye!'
  },
  'ja-JP': {
    greeting: 'こんにちは、{$name}さん！',
    farewell: 'さようなら！'
  },
  'es-ES': {
    greeting: '¡Hola, {$name}!',
    farewell: '¡Adiós!'
  }
}

const command = defineI18n({
  name: 'greet',
  description: 'Greet someone in their language',
  // Resource function receives locale and returns translations
  resource: locale => {
    return resources[locale.toString()] || resources['en-US']
  },
  args: {
    name: {
      type: 'string',
      required: true,
      description: 'Name to greet'
    }
  },
  run: ctx => {
    // Access the i18n plugin extension via its namespaced ID 'g:i18n'
    // (All Gunshi plugins use the 'g:' prefix to prevent naming conflicts)
    const t = ctx.extensions['g:i18n'].translate
    console.log(t(resolveKey('greeting', ctx), { name: ctx.values.name }))
    console.log(t(resolveKey('farewell', ctx)))
  }
})

await cli(process.argv.slice(2), command, {
  name: 'greet-cli',
  version: '1.0.0',
  plugins: [
    i18n({
      locale: process.env.LANG || 'en-US'
    })
  ]
})
```

> \[!NOTE]
> Plugin IDs use namespacing to prevent conflicts and identify ownership. Official Gunshi plugins use the `g:` prefix (e.g., `g:i18n`, `g:completion`). When developing your own plugins, use your organization's namespace (e.g., `myorg:logger`) or scoped package format (e.g., `@company/auth`). For detailed naming conventions and guidelines, see the [Plugin ID Guidelines](../plugin/guidelines.md#plugin-ids).

Key benefits:

* The `defineI18n` helper simplifies i18n setup for commands
* Automatic locale detection from system settings
* Simple interpolation syntax for dynamic values
* Fallback to default locale when translation is missing
* Plugin functionality is accessible via `ctx.extensions` in your command runners

> \[!NOTE]
> The `ctx.extensions` object is how plugins extend your command context with additional functionality. The i18n plugin adds translation capabilities through `ctx.extensions['g:i18n']`. To learn more about working with plugin extensions and best practices for accessing them, see the [Context Extensions guide](../advanced/context-extensions.md).

> \[!TIP]
> This example demonstrates basic internationalization setup. For comprehensive coverage including external resource files, TypeScript support, dynamic locale switching, and production deployment strategies, see the [Advanced Internationalization Guide](../advanced/internationalization.md).

### Suggestions

Add correction hints for unknown long options and unknown commands with the suggestion plugin:

::: code-group

```sh [npm]
npm install --save @gunshi/plugin-suggestion
```

```sh [pnpm]
pnpm add @gunshi/plugin-suggestion
```

```sh [yarn]
yarn add @gunshi/plugin-suggestion
```

```sh [deno]
deno add jsr:@gunshi/plugin-suggestion
```

```sh [bun]
bun add @gunshi/plugin-suggestion
```

:::

```js
import { cli, define } from 'gunshi'
import { suggestion } from '@gunshi/plugin-suggestion'

const command = define({
  name: 'app',
  toKebab: true,
  args: {
    allowReload: {
      type: 'boolean',
      description: 'Allow reload'
    }
  },
  run: () => {}
})

await cli(process.argv.slice(2), command, {
  strict: true,
  plugins: [suggestion()]
})
```

If the user runs `app --alow-reload`, the validation output includes a hint:

```txt
Unknown option: --alow-reload
Did you mean --allow-reload?
```

The same plugin also handles command suggestions:

```txt
Command not found: rn
Did you mean run?
```

The plugin decorates validation error rendering. It does not detect unknown options or commands itself; Gunshi core provides structured validation errors and candidate metadata.

You can combine it with the i18n plugin so the base validation message and suggestion hint use locale resources:

```js
import i18n from '@gunshi/plugin-i18n'
import { suggestion } from '@gunshi/plugin-suggestion'

await cli(process.argv.slice(2), command, {
  strict: true,
  plugins: [i18n({ locale: 'ja-JP' }), suggestion()]
})
```

### Shell Completion

Enable tab completion across different shells:

::: code-group

```sh [npm]
npm install --save @gunshi/plugin-completion
```

```sh [pnpm]
pnpm add @gunshi/plugin-completion
```

```sh [yarn]
yarn add @gunshi/plugin-completion
```

:::

> \[!IMPORTANT]
> Shell completion supports Node.js and Bun, including Bun single-file executables built with `bun build --compile`. The completion feature is not available yet when running your CLI with Deno.

Here's how to add completion support:

```js
import { cli, define } from 'gunshi'
import completion from '@gunshi/plugin-completion'

const command = define({
  name: 'deploy',
  args: {
    environment: {
      type: 'string',
      required: true,
      description: 'Target environment'
    }
  },
  run: ctx => {
    console.log(`Deploying to ${ctx.values.environment}`)
  }
})

await cli(process.argv.slice(2), command, {
  name: 'deploy-cli',
  version: '1.0.0',
  plugins: [
    completion({
      config: {
        entry: {
          args: {
            environment: {
              handler: () => [
                { value: 'production', description: 'Production' },
                { value: 'staging', description: 'Staging' },
                { value: 'development', description: 'Development' }
              ]
            }
          }
        }
      }
    })
  ]
})
```

The completion plugin adds a special `complete` command to your CLI that generates shell-specific completion scripts.

### Installing Completion for End Users

Once you've added the completion plugin to your CLI, your users need to perform a one-time setup to enable tab completion on their system.

#### Basic Setup Example (Bash)

Users generate a completion script for their shell and add it to their shell configuration:

```sh
# Generate completion script and save it
deploy-cli complete bash > ~/.local/share/bash-completion/completions/deploy-cli

# Reload your shell configuration
source ~/.bashrc

# Now tab completion works!
deploy-cli dep<TAB>  # Completes to: deploy-cli deploy
```

> \[!TIP]
> For detailed setup instructions for all supported shells (Bash, Zsh, Fish, PowerShell), including directory creation and configuration steps, see the [@gunshi/plugin-completion README](https://github.com/kazupon/gunshi/tree/main/packages/plugin-completion#shell-completion-setup).

#### How It Works

The completion plugin adds a special `complete` command to your CLI that generates shell-specific completion scripts.

Users run this command once to generate the script for their shell, then source it in their shell configuration to enable tab completion.

### Dry Run

Add a `--dry-run` option and wrap side-effect operations that should be skipped when users only want to preview actions:

::: code-group

```sh [npm]
npm install --save @gunshi/plugin-dryrun
```

```sh [pnpm]
pnpm add @gunshi/plugin-dryrun
```

```sh [yarn]
yarn add @gunshi/plugin-dryrun
```

```sh [deno]
deno add jsr:@gunshi/plugin-dryrun
```

```sh [bun]
bun add @gunshi/plugin-dryrun
```

:::

```js
import { cli, define } from 'gunshi'
import dryrun from '@gunshi/plugin-dryrun'

const command = define({
  name: 'publish',
  async run(ctx) {
    const dryRun = ctx.extensions['g:dryrun']

    await dryRun.run(
      async function publishPackage() {
        // Publish package here
      },
      {
        message: 'publish package'
      }
    )
  }
})

await cli(process.argv.slice(2), command, {
  name: 'publish-tool',
  plugins: [dryrun()]
})
```

With `--dry-run`, the wrapped operation is skipped and the message is printed through the command context logger:

```sh
[dryrun] publish package
```

The dry-run plugin does not skip the whole command. It only skips operations that command authors explicitly pass to `run()` or `wrap()`, so commands can still validate input, resolve configuration, and print useful context.

## Combining Plugins

Plugins work seamlessly together. Here's an example using both i18n and completion:

```js
import { cli } from 'gunshi'
import i18n, { defineI18n, resolveKey } from '@gunshi/plugin-i18n'
import completion from '@gunshi/plugin-completion'

// Define your resources
const resources = {
  'en-US': {
    start: 'Starting build for {$mode} mode...',
    success: 'Build completed successfully!'
  },
  'ja-JP': {
    start: '{$mode}モードでビルドを開始しています...',
    success: 'ビルドが正常に完了しました！'
  }
}

const buildCommand = defineI18n({
  name: 'build',
  description: 'Build the project',
  resource: locale => {
    return resources[locale.toString()] || resources['en-US']
  },
  args: {
    mode: {
      type: 'string',
      default: 'development',
      description: 'Build mode'
    }
  },
  run: ctx => {
    const t = ctx.extensions['g:i18n'].translate
    console.log(t(resolveKey('start', ctx), { mode: ctx.values.mode }))
    // Build logic here
    console.log(t(resolveKey('success', ctx)))
  }
})

await cli(process.argv.slice(2), buildCommand, {
  name: 'build-tool',
  version: '2.0.0',
  plugins: [
    i18n({
      locale: process.env.LANG || 'en-US'
    }),
    completion({
      config: {
        entry: {
          args: {
            mode: {
              handler: () => [
                { value: 'development', description: 'Development build' },
                { value: 'production', description: 'Production build' }
              ]
            }
          }
        }
      }
    })
  ]
})
```

Both plugins enhance your CLI without interfering with each other - i18n handles translations while completion provides tab suggestions.

## Plugin Configuration

Configure plugins based on your environment or user preferences.

### Environment-based Configuration

Load plugins conditionally:

```js
import { cli } from 'gunshi'

const plugins = []

// Add completion in development only
if (process.env.NODE_ENV === 'development') {
  const completion = await import('@gunshi/plugin-completion')
  plugins.push(completion.default())
}

// Add i18n if locale is set
if (process.env.LANG) {
  const i18n = await import('@gunshi/plugin-i18n')
  plugins.push(i18n.default({ locale: process.env.LANG }))
}

await cli(process.argv.slice(2), command, {
  name: 'my-cli',
  plugins
})
```

This approach keeps your production builds lean while providing developer features during development.

## Minimal Setup

If you need precise control over your CLI's functionality and bundle size, you can use `@gunshi/bone` - Gunshi's bare-bones foundation package.

Unlike the standard `cli()` function which includes plugins automatically, `@gunshi/bone` starts with zero plugins, letting you add only what you need:

::: code-group

```sh [npm]
npm install --save @gunshi/bone @gunshi/plugin-global @gunshi/plugin-renderer
```

```sh [pnpm]
pnpm add @gunshi/bone @gunshi/plugin-global @gunshi/plugin-renderer
```

```sh [yarn]
yarn add @gunshi/bone @gunshi/plugin-global @gunshi/plugin-renderer
```

:::

```js
import { cli } from '@gunshi/bone'
import global from '@gunshi/plugin-global'
import renderer from '@gunshi/plugin-renderer'

// Only includes plugins you explicitly add
await cli(process.argv.slice(2), command, {
  name: 'minimal-cli',
  plugins: [
    global(), // Adds --help and --version options
    renderer() // Adds help text formatting
  ]
})
```

This approach gives you explicit control over every aspect of your CLI, making it ideal for applications where bundle size or specific feature control is critical.

Common use cases for `@gunshi/bone`:

* Embedded CLIs with size constraints
* Custom implementations of help or version handling
* Testing plugin interactions in isolation
* Applications requiring precise control over all CLI behavior

## Next Steps

Now that you understand the plugin system basics, you can explore more advanced topics and start building with Gunshi's plugin ecosystem.

To deepen your understanding of the plugin system:

* **TypeScript Support**: Explore type-safe plugin usage in the [Type System Guide](../advanced/type-system.md)
* **Context Extensions**: Learn how plugins extend functionality through [Context Extensions](../advanced/context-extensions.md)

Ready to create your own plugins?

* **Plugin Development**: Build custom plugins with the [Plugin Development Guide](../plugin/introduction.md)

---

---
url: /guide/advanced/type-system.md
---
# Type System

Gunshi v0.27 introduces a powerful type parameter system that provides comprehensive type safety across all core functions: `cli`, `define`, `lazy`, and `plugin`.

This enhancement brings TypeScript's full type-checking capabilities to your CLI applications, ensuring compile-time safety for command arguments and plugin extensions.

This guide focuses on type safety for command definitions and their arguments. If you're creating custom plugins and need to understand the `plugin` function's type system, refer to the [Plugin Type System](../plugin/type-system.md) guide.

> \[!NOTE]
> Some code examples in this guide include TypeScript file extensions (`.ts`) in `import`/`export` statements. If you use this pattern in your plugin, you'll need to enable `allowImportingTsExtensions` in your `tsconfig.json`.

## Overview of v0.27 Type System

The v0.27 release provides comprehensive type safety through:

* **Core Functions**: `define` and `lazy` provide excellent type inference for standard commands
* **Plugin Extension Support**: `defineWithTypes` and `lazyWithTypes` enable type declarations for plugin extensions
* **Unified Type System (GunshiParams)**: A coherent type system for arguments and extensions
* **CLI Entry Point Types**: Type parameters for the `cli` function's entry command
* **Enhanced TypeScript Inference**: Automatic type inference reduces boilerplate while maintaining safety

## Understanding `GunshiParams`

`GunshiParams` is the core type that provides type safety for command arguments and plugin extensions. At its simplest, it ensures that your command context has properly typed `values` (from args) and `extensions` (from plugins).

Before diving into the implementation details, let's start with a simple example that demonstrates how `GunshiParams` provides type safety for command arguments:

```ts
// Simple usage - just arguments
type SimpleParams = GunshiParams<{
  args: { port: { type: 'number' } }
}>

// With extensions from plugins
type FullParams = GunshiParams<{
  args: { port: { type: 'number' } }
  extensions: { logger: Logger }
}>
```

The actual type definition uses TypeScript's conditional types to provide flexibility:

```ts
export interface GunshiParams<
  P extends {
    args?: Args
    extensions?: ExtendContext
  } = {
    args: Args
    extensions: {}
  }
> {
  /**
   * Command argument definitions.
   */
  args: P extends { args: infer A extends Args } ? A : Args
  /**
   * Command context extensions.
   */
  extensions: P extends { extensions: infer E extends ExtendContext } ? E : {}
}
```

## Core Functions: `define` and `lazy`

### The `define` Function

The `define` function is the primary way to create commands in Gunshi. For most use cases, the basic usage with automatic type inference is sufficient. Advanced usage with type parameters is useful when you need explicit type control or are working with complex type definitions.

#### Basic Usage

When your command doesn't use plugin extensions, `define` provides excellent automatic type inference:

```ts
import { define } from 'gunshi'

// Standard command definition with automatic type inference
export const serverCommand = define({
  name: 'server',
  description: 'Start the development server',
  args: {
    port: { type: 'number', default: 3000 },
    host: { type: 'string', default: 'localhost' },
    verbose: { type: 'boolean', short: 'V' }
  },
  run: ctx => {
    // ctx.values is automatically inferred as { port?: number; host?: string; verbose?: boolean }
    const { port, host, verbose } = ctx.values

    console.log(`Starting server on ${host}:${port}`)
    if (verbose) {
      console.log('Verbose mode enabled')
    }
  }
})
```

The basic usage covers most scenarios where you're defining commands with inline arguments and don't need to share type definitions across multiple commands.

#### Advanced Usage with Type Parameters

When you need explicit type control or are working with pre-defined argument configurations, `define` accepts `GunshiParams` compatible type parameter:

```ts [commands/server.ts]
import { define } from 'gunshi'

// Define args separately
export const serverArgs = {
  port: { type: 'number', default: 3000 },
  host: { type: 'string', default: 'localhost' }
} as const

export const serverCommand = define<{ args: typeof serverArgs }>({
  name: 'server',
  args: serverArgs,
  run: ctx => {
    // ctx.values is typed based on ServerParams
    console.log(`Server: ${ctx.values.host}:${ctx.values.port}`)
  }
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/type-system/define).

This advanced approach is particularly useful when you want to reuse argument definitions across multiple commands or need to export types for use in other modules.

### The `lazy` Function

The `lazy` function enables code-splitting while maintaining type safety. Like `define`, it works well with automatic type inference for most cases. Advanced usage provides explicit type control when needed.

#### Basic Usage

For commands without plugin extensions, `lazy` automatically infers types from your definition:

```js
import { lazy } from 'gunshi'

// Lazy-loaded command with automatic type inference
export const buildCommand = lazy(
  async () => {
    // Heavy dependencies can be loaded here when needed
    const { build } = await import('./build.js')

    return async ctx => {
      // ctx.values is automatically inferred from args definition below
      const { target, minify } = ctx.values

      console.log(`Building for ${target}...`)
      if (minify) {
        console.log('Minification enabled')
      }

      return build({ target, minify })
    }
  },
  {
    name: 'build',
    description: 'Build the project',
    args: {
      target: { type: 'string', required: true, choices: ['dev', 'prod'] },
      minify: { type: 'boolean', default: false }
    }
  }
)
```

This basic usage is ideal for most lazy-loaded commands where you want to defer loading dependencies until the command is actually executed.

#### Advanced Usage with Pre-defined Arguments

When working with pre-defined argument configurations or when you need to explicitly type your command runner, you can structure your lazy command as follows:

```ts [commands/build.ts]
import { lazy } from 'gunshi'

// Pre-defined arguments
export const buildArgs = {
  target: { type: 'enum', required: true, choices: ['dev', 'prod'] },
  minify: { type: 'boolean', default: false }
} as const

// Create the lazy command with explicit typing
export const buildCommand = lazy<{ args: typeof buildArgs }>(
  async () => {
    // Heavy dependencies can be loaded here when needed
    const { bundle } = await import('./utils.ts')

    return async ctx => {
      // Inference of args values
      const { target, minify } = ctx.values
      // Implementation
      return bundle({ target, minify })
    }
  },
  {
    name: 'build',
    args: buildArgs
  }
)
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/type-system/lazy).

## Plugin Extensions and Architectural Constraints

### Understanding the Timing Constraint

Gunshi's architecture intentionally separates command definition from plugin installation:

1. **Command Definition Time**: When you call `define()` or `lazy()` in your code, plugins haven't been installed yet
2. **CLI Execution Time**: When `cli()` runs, plugins are installed and extensions become available
3. **The Gap**: Commands can't know what extensions will be available at definition time

This architectural design enables flexible command configuration but creates a challenge: how can commands safely use plugin extensions that don't exist yet?

### The Solution: Type Declaration Functions

`defineWithTypes` and `lazyWithTypes` solve this by allowing you to declare expected extensions at command definition time. These functions provide type safety for plugin extensions that will be available when the command actually runs.

This separation is crucial because:

* It maintains modularity - commands don't depend on specific plugin implementations
* It allows flexible plugin configuration - different CLI instances can use different plugins
* It enables type safety - TypeScript knows what extensions to expect even though they're not yet available

## Functions for Plugin Extensions: `defineWithTypes` and `lazyWithTypes`

When your command needs to use plugin extensions, use these specialized functions that allow you to declare expected extension types.

### The `defineWithTypes` Function

Use `defineWithTypes` when your command needs plugin extensions. It uses a currying approach where you specify the extensions type, and args are automatically inferred:

```ts [commands/server.ts]
import { defineWithTypes } from 'gunshi'
import type { AuthExtension } from '../plugin.ts'

// Define your extensions type
type ServerExtensions = {
  auth: AuthExtension
}

// Use defineWithTypes - specify only extensions, args are inferred!
export const serverCommand = defineWithTypes<{ extensions: ServerExtensions }>()({
  name: 'server',
  description: 'Start the development server',
  args: {
    port: { type: 'number', default: 3000 },
    host: { type: 'string', default: 'localhost' },
    verbose: { type: 'boolean', short: 'V' }
  },
  run: ctx => {
    // ctx.values is automatically inferred as { port?: number; host?: string; verbose?: boolean }
    const { port, host, verbose } = ctx.values

    // ctx.extensions is typed as ServerExtensions
    // Optional chaining (?.) is used because plugins may not be installed
    if (!ctx.extensions.auth?.isAuthenticated()) {
      throw new Error('Please login first')
    }

    const user = ctx.extensions.auth?.getUser()
    console.log(`Server started by ${user.name} on ${host}:${port}`)

    if (verbose) {
      console.log('Verbose mode enabled')
    }
  }
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/type-system/define-with-types).

#### Flexible Type Parameters

`defineWithTypes` supports multiple scenarios for different use cases:

```ts
// Case 1: Extensions only (most common)
// You want to use plugin extensions in your CommandRunner implementation.
// Args are automatically inferred from the inline definition
const cmd1 = defineWithTypes<{ extensions: MyExtensions }>()({
  name: 'server',
  args: { port: { type: 'number' } }, // args types are inferred
  run: ctx => {
    // ctx.extensions is typed, ctx.values is inferred from args
    /* ... */
  }
})

// Case 2: Args only (when using pre-defined args)
// Your args are defined in a variable, not inline in the define function.
// Pre-defined args variables need explicit type specification for proper inference
const myArgs = {
  port: { type: 'number' },
  host: { type: 'string' }
} as const

const cmd2 = defineWithTypes<{ args: typeof myArgs }>()({
  name: 'process',
  args: myArgs, // Using pre-defined args variable
  run: ctx => {
    // ctx.values is typed based on myArgs
    /* ... */
  }
})

// Case 3: Both args and extensions (special case)
// You need plugin extensions AND you're using pre-defined args variables
const cmd3 = defineWithTypes<{
  args: typeof myArgs
  extensions: MyExtensions
}>()({
  name: 'hybrid',
  args: myArgs, // Using pre-defined args variable
  run: ctx => {
    // Both ctx.values and ctx.extensions are typed
    /* ... */
  }
})
```

### The `lazyWithTypes` Function

The `lazyWithTypes` function maintains type safety for lazy-loaded commands that use plugin extensions:

```ts [commands/build.ts]
import { lazyWithTypes } from 'gunshi'
import type { LoggerExtension } from '../plugin.ts'

export const buildArgs = {
  target: { type: 'enum', required: true, choices: ['dev', 'prod'] },
  minify: { type: 'boolean', default: false }
} as const

// Define extensions for the command
type BuildExtensions = {
  logger: LoggerExtension
}

// Use lazyWithTypes with extensions - args are automatically inferred
export const buildCommand = lazyWithTypes<{
  args: typeof buildArgs
  extensions: BuildExtensions
}>()(
  async () => {
    // Heavy dependencies can be loaded here when needed
    return async ctx => {
      // ctx.values is automatically inferred from args definition below
      const { target, minify } = ctx.values

      // Use typed extensions
      ctx.extensions.logger?.log(`Building for ${target}...`)

      if (minify) {
        ctx.extensions.logger?.log('Minification enabled')
      }
    }
  },
  {
    name: 'build',
    description: 'Build the project',
    args: buildArgs
  }
)
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/type-system/lazy-with-types).

#### Flexible Type Parameters

Similar to `defineWithTypes`, `lazyWithTypes` supports flexible type parameters:

```ts
// Most common: specify only extensions
lazyWithTypes<{ extensions: BuildExtensions }>()( ... )

// When using pre-defined args: specify args explicitly
lazyWithTypes<{ args: typeof buildArgs }>()( ... )

// Full control: specify both (when using pre-defined args AND extensions)
lazyWithTypes<{ args: typeof buildArgs; extensions: BuildExtensions }>()( ... )
```

## The `cli` Function Type Parameters

The `cli` function provides type safety for your entry command. The type parameter defines the type for the entry command's context, determining the types of `ctx.values` and `ctx.extensions` that the entry command's runner function receives:

```ts
import { cli } from 'gunshi'
import logger from './plugin.ts'

import type { LoggerExtension } from './plugin.ts'

const entryArgs = {
  verbose: { type: 'boolean', short: 'V' },
  output: { type: 'string', default: 'json' }
} as const

// `cli` function with type-safe `args` and `extensions`
await cli<{ args: typeof entryArgs; extensions: { logger: LoggerExtension } }>(
  process.argv.slice(2),
  {
    name: 'main',
    description: 'CLI with type-safe extensions',
    args: entryArgs,
    run: async ctx => {
      if (ctx.values.verbose) {
        ctx.extensions.logger?.log(`Processing in verbose mode...`)
      }
      console.log(`Output format: ${ctx.values.output}`)
    }
  },
  {
    name: 'mycli',
    version: '1.0.0',
    plugins: [logger()]
  }
)
```

## Combining Multiple Plugin Types

When working with multiple plugins, you often need to combine their extension types to create a comprehensive type definition for your commands. TypeScript's intersection operator (`&`) provides a clean way to merge multiple plugin extension types.

### Using TypeScript's Intersection Operator (&)

The `&` operator creates an intersection type that combines multiple type definitions. This is particularly useful when your command needs to access extensions from multiple plugins.

#### With Official Gunshi Plugins

When using official Gunshi plugins that provide plugin IDs, combine their extensions using Record types. Let's break this down step by step:

**Step 1: Import Plugin IDs and Types**

First, import the plugin IDs and extension types from the official plugins. Each plugin provides a unique identifier and type definition:

```ts
// Import plugin identifiers
import { pluginId as globalId } from '@gunshi/plugin-global'
import { pluginId as rendererId } from '@gunshi/plugin-renderer'
import { pluginId as i18nId } from '@gunshi/plugin-i18n'

// Import type definitions
import type { GlobalExtension, PluginId as GlobalId } from '@gunshi/plugin-global'
import type { UsageRendererExtension, PluginId as RendererId } from '@gunshi/plugin-renderer'
import type { I18nExtension, PluginId as I18nId } from '@gunshi/plugin-i18n'
```

**Step 2: Combine Extension Types**

Next, create a combined type that includes all the plugin extensions your command will use. The Record types map each plugin ID to its corresponding extension:

```ts
// Combine multiple plugin extension types using intersection (&)
type CombinedExtensions = Record<GlobalId, GlobalExtension> &
  Record<RendererId, UsageRendererExtension> &
  Record<I18nId, I18nExtension>
```

**Step 3: Define the Command with Combined Extensions**

Finally, use `defineWithTypes` to create a command that can access all the combined plugin extensions with full type safety:

```ts
// Use defineWithTypes with combined extensions
export default defineWithTypes<{ extensions: CombinedExtensions }>()({
  name: 'greet',
  args: {
    name: { type: 'string', required: true }
  },
  run: async ctx => {
    // Access i18n plugin extension
    const locale = ctx.extensions[i18nId]?.locale
    if (locale) {
      console.log(`Current locale: ${locale.toString()}`)
    }

    // Access renderer plugin extension
    const message = ctx.extensions[rendererId]?.text('welcome')
    if (message) {
      console.log(message)
    }

    // Access environment properties directly on context (not through extensions)
    console.log(`Running in ${ctx.env.name || 'unknown'} environment`)
  }
})
```

#### With Custom Plugins

Custom plugins provide plugin IDs and types. Import both to create fully type-safe command definitions:

```ts [commands/query.ts]
import { defineWithTypes } from 'gunshi'
import { pluginId as authId } from '../plugins/auth.ts'
import { pluginId as databaseId } from '../plugins/database.ts'
import { pluginId as loggerId } from '../plugins/logger.ts'

import type { AuthExtension, PluginId as AuthId } from '../plugins/auth.ts'
import type { DatabaseExtension, PluginId as DatabaseId } from '../plugins/database.ts'
import type { LoggerExtension, PluginId as LoggerId } from '../plugins/logger.ts'

type CombinedExtensions = Record<LoggerId, LoggerExtension> &
  Record<AuthId, AuthExtension> &
  Record<DatabaseId, DatabaseExtension>

export default defineWithTypes<{ extensions: CombinedExtensions }>()({
  name: 'query',
  description: 'Query database tables',
  args: {
    table: { type: 'string', required: true }
  },
  run: async ctx => {
    // All extensions and arguments are fully typed
    ctx.extensions[loggerId]?.log(`Querying ${ctx.values.table}`)

    // Check read permissions for the specific table
    if (!ctx.extensions[authId]?.hasPermission('read', ctx.values.table)) {
      throw new Error(`No read access to table: ${ctx.values.table}`)
    }

    // Perform the query using the database extension
    const dataset = await ctx.extensions[databaseId]?.query(ctx.values.table)
    console.log(`Retrieved records from ${ctx.values.table}`, dataset)
  }
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/type-system/combine).

Both approaches achieve the same goal: combining multiple plugin extensions with full type safety. Use Record types when working with official plugins that provide plugin IDs, and direct intersection types for custom plugins.

## Choosing the Right Function

### Use `define` or `lazy` when:

* Your command doesn't use plugin extensions
* You only need type safety for command arguments
* This is the most common use case

### Use `defineWithTypes` or `lazyWithTypes` when:

* Your command uses plugin extensions
* You need to declare expected extension types
* You want IntelliSense for plugin APIs

The choice is straightforward: if you need plugin extensions, use the `WithTypes` variants; otherwise, use the standard functions for simpler, cleaner code.

---

---
url: /guide/advanced/parser-combinators.md
---
# Parser Combinators

Parser combinators provide a functional, composable approach to defining type-safe argument schemas in Gunshi. Instead of writing plain object configurations, you can use factory functions that generate schemas with full type inference.

This approach brings several advantages:

* **Composable building blocks**: Combine simple parsers to create complex schemas
* **Type-safe by design**: Full TypeScript type inference without manual annotations
* **Reusable schema groups**: Define common configurations once, use them everywhere
* **Functional programming style**: Chain and compose operations naturally

## Import Paths

Parser combinators are available through two import paths:

```ts
// From the main gunshi package
import { string, integer, boolean, ... } from 'gunshi/combinators'

// Or as a standalone package for minimal bundle size
import { string, integer, boolean, ... } from '@gunshi/combinators'
```

The standalone `@gunshi/combinators` package is ideal when you only need combinator functionality without the full gunshi CLI framework.

> \[!NOTE]
> The `@gunshi/combinators` package needs to be installed separately: `npm install @gunshi/combinators`. The `gunshi/combinators` import path is available as part of the main `gunshi` package.

## Traditional vs Combinator Approach

Let's compare the traditional object-based approach with parser combinators to understand the difference:

### Traditional Approach

```ts [traditional.ts]
import { define } from 'gunshi'

const command = define({
  name: 'serve',
  args: {
    host: {
      type: 'string',
      short: 'h',
      description: 'Host to bind',
      default: 'localhost'
    },
    port: {
      type: 'number',
      short: 'p',
      description: 'Port number',
      default: 8080,
      min: 1,
      max: 65535
    },
    verbose: {
      type: 'boolean',
      short: 'v',
      description: 'Enable verbose output'
    }
  },
  run: ctx => {
    // Implementation
  }
})
```

### Combinator Approach

```ts [combinators.ts]
import { define } from 'gunshi'
import { string, integer, boolean, withDefault, short } from 'gunshi/combinators'

const command = define({
  name: 'serve',
  args: {
    host: withDefault(short(string({ description: 'Host to bind' }), 'h'), 'localhost'),
    port: withDefault(
      short(
        integer({
          min: 1,
          max: 65535,
          description: 'Port number'
        }),
        'p'
      ),
      8080
    ),
    verbose: short(boolean({ description: 'Enable verbose output' }), 'v')
  },
  run: ctx => {
    // ctx.values.host is typed as string (non-optional due to withDefault)
    // ctx.values.port is typed as number (non-optional due to withDefault)
    // ctx.values.verbose is typed as boolean | undefined
  }
})
```

The combinator approach offers better composability and type inference, while maintaining the same runtime behavior.

## Base Combinators

Base combinators create the fundamental argument types. Each returns a `CombinatorSchema` that can be used directly or modified with other combinators.

### string()

Creates a string argument parser with optional validation:

```ts [string-example.ts]
import { define } from 'gunshi'
import { string } from 'gunshi/combinators'

const command = define({
  name: 'example',
  args: {
    // Basic string
    name: string(),

    // String with constraints
    username: string({
      minLength: 3,
      maxLength: 20,
      pattern: /^[a-zA-Z0-9_]+$/,
      description: 'Username (alphanumeric and underscore only)'
    }),

    // String with description
    email: string({
      pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
      description: 'Email address'
    })
  },
  run: ctx => {
    console.log(`Name: ${ctx.values.name}`)
    console.log(`Username: ${ctx.values.username}`)
    console.log(`Email: ${ctx.values.email}`)
  }
})
```

### number()

Creates a numeric argument parser with optional range validation:

```ts [number-example.ts]
import { define } from 'gunshi'
import { number } from 'gunshi/combinators'

const command = define({
  name: 'example',
  args: {
    // Any number
    value: number(),

    // Number with range
    percentage: number({
      min: 0,
      max: 100,
      description: 'Percentage value (0-100)'
    })
  },
  run: ctx => {
    console.log(`Value: ${ctx.values.value}`)
    console.log(`Percentage: ${ctx.values.percentage}%`)
  }
})
```

### integer()

Creates an integer-only parser, rejecting decimal values:

```ts [integer-example.ts]
import { define } from 'gunshi'
import { integer } from 'gunshi/combinators'

const command = define({
  name: 'server',
  args: {
    // Port number must be an integer
    port: integer({
      min: 1,
      max: 65535,
      description: 'Server port'
    }),

    // Worker count
    workers: integer({
      min: 1,
      description: 'Number of worker processes'
    })
  },
  run: ctx => {
    console.log(`Starting server on port ${ctx.values.port}`)
    console.log(`Using ${ctx.values.workers} workers`)
  }
})
```

### float()

Creates a floating-point number parser:

```ts [float-example.ts]
import { define } from 'gunshi'
import { float } from 'gunshi/combinators'

const command = define({
  name: 'calculate',
  args: {
    // Accepts decimal values
    rate: float({
      min: 0.0,
      max: 1.0,
      description: 'Interest rate (0.0 to 1.0)'
    }),

    // Scientific notation supported
    threshold: float({
      description: 'Threshold value'
    })
  },
  run: ctx => {
    console.log(`Rate: ${ctx.values.rate}`)
    console.log(`Threshold: ${ctx.values.threshold}`)
  }
})
```

### boolean()

Creates a boolean flag parser:

```ts [boolean-example.ts]
import { define } from 'gunshi'
import { boolean } from 'gunshi/combinators'

const command = define({
  name: 'build',
  args: {
    // Simple boolean flag
    minify: boolean(),

    // Boolean with negatable option
    cache: boolean({
      negatable: true,
      description: 'Enable caching (use --no-cache to disable)'
    })
  },
  run: ctx => {
    if (ctx.values.minify) {
      console.log('Minification enabled')
    }

    // With negatable, can explicitly disable
    if (ctx.values.cache === false) {
      console.log('Cache explicitly disabled')
    }
  }
})
```

### choice()

Creates an enum-like parser with literal type inference. The `choice()` combinator only accepts string values. For numeric or other types, combine with `map()` to transform the parsed string value:

```ts [choice-example.ts]
import { define } from 'gunshi'
import { choice, map } from 'gunshi/combinators'

const command = define({
  name: 'deploy',
  args: {
    // Use 'as const' for literal type inference
    environment: choice(['development', 'staging', 'production'] as const, {
      description: 'Deployment environment'
    }),

    // Map numeric values from string choices
    logLevel: map(
      choice(['0', '1', '2', '3'] as const, {
        description: 'Log level (0=error, 1=warn, 2=info, 3=debug)'
      }),
      v => parseInt(v, 10)
    )
  },
  run: ctx => {
    // ctx.values.environment is typed as 'development' | 'staging' | 'production' | undefined
    console.log(`Deploying to ${ctx.values.environment}`)

    // ctx.values.logLevel is typed as number | undefined
    if (ctx.values.logLevel !== undefined) {
      console.log(`Log level: ${ctx.values.logLevel}`)
    }

    // Type-safe switch statements
    switch (ctx.values.environment) {
      case 'production':
        console.log('Running production checks...')
        break
      case 'staging':
        console.log('Deploying to staging environment')
        break
      case 'development':
        console.log('Deploying to dev environment')
        break
    }
  }
})
```

> \[!TIP]
> Always use `as const` with choice arrays to get literal type inference. Without it, TypeScript will infer a general string or number type instead of the specific literal values.

### positional()

Creates a positional argument that can optionally use a parser:

```ts [positional-example.ts]
import { define } from 'gunshi'
import { positional, integer, unrequired } from 'gunshi/combinators'

const command = define({
  name: 'copy',
  args: {
    // Simple positional argument (string by default)
    source: positional({ description: 'Source file' }),

    // Positional with type parser
    count: positional(
      integer({
        min: 1,
        description: 'Number of copies'
      })
    ),

    // Optional positional argument
    query: unrequired(
      positional({
        description: 'Query to use instead of reading stdin'
      })
    )
  },
  run: ctx => {
    console.log(`Copying ${ctx.values.source} ${ctx.values.count} times`)
  }
})

// Usage: copy file.txt 3
```

### combinator()

Creates custom parsers for specialized types:

```ts [custom-combinator.ts]
import { define } from 'gunshi'
import { combinator } from 'gunshi/combinators'

const command = define({
  name: 'schedule',
  args: {
    // Parse dates
    date: combinator({
      parse: (value: string) => {
        const date = new Date(value)
        if (isNaN(date.getTime())) {
          throw new Error(`Invalid date: ${value}`)
        }
        return date
      },
      metavar: 'date',
      description: 'Schedule date (YYYY-MM-DD or ISO 8601)'
    }),

    // Parse comma-separated values
    tags: combinator({
      parse: (value: string) => value.split(',').map(s => s.trim()),
      metavar: 'tag1,tag2,...',
      description: 'Comma-separated tags'
    }),

    // Parse JSON
    config: combinator({
      parse: (value: string) => {
        try {
          return JSON.parse(value)
        } catch (e) {
          throw new Error(`Invalid JSON: ${e.message}`)
        }
      },
      metavar: 'json',
      description: 'JSON configuration'
    })
  },
  run: ctx => {
    // ctx.values.date is typed as Date
    // ctx.values.tags is typed as string[]
    // ctx.values.config is typed as any (or use generics for specific types)
    console.log(`Scheduled for ${ctx.values.date?.toISOString()}`)
    console.log(`Tags: ${ctx.values.tags?.join(', ')}`)
  }
})
```

## Modifier Combinators

Modifier combinators wrap base combinators to change their behavior or add constraints.

### required()

Makes an argument mandatory:

```ts [required-example.ts]
import { define } from 'gunshi'
import { string, required } from 'gunshi/combinators'

const command = define({
  name: 'login',
  args: {
    // Username is required
    username: required(string({ description: 'Username' })),

    // Password is optional
    password: string({ description: 'Password (will prompt if not provided)' })
  },
  run: ctx => {
    // ctx.values.username is typed as string (not optional)
    // ctx.values.password is typed as string | undefined
    console.log(`Logging in as ${ctx.values.username}`)
  }
})
```

### unrequired()

Explicitly marks an argument as optional. This is useful when you want to override a `required()` field from a base schema using `extend()`, or when you want a positional argument that may be omitted:

```ts [unrequired-example.ts]
import { define } from 'gunshi'
import { string, positional, required, unrequired, extend, args } from 'gunshi/combinators'

// Base schema with required field
const base = args({
  name: required(string())
})

// Override to make it optional in specific context
const relaxed = extend(base, {
  name: unrequired(string()),
  query: unrequired(positional({ description: 'Optional query' }))
})

const command = define({
  name: 'example',
  args: relaxed,
  run: ctx => {
    // ctx.values.name is now string | undefined
    // ctx.values.query is now string | undefined
    console.log(`Name: ${ctx.values.name || 'Anonymous'}`)
  }
})
```

### withDefault()

Provides a default value, making the argument always defined:

```ts [default-example.ts]
import { define } from 'gunshi'
import { string, integer, boolean, withDefault } from 'gunshi/combinators'

const command = define({
  name: 'server',
  args: {
    // Always has a value
    host: withDefault(string(), 'localhost'),
    port: withDefault(integer({ min: 1, max: 65535 }), 3000),
    debug: withDefault(boolean(), false)
  },
  run: ctx => {
    // All values are non-optional due to defaults
    // ctx.values.host is typed as string
    // ctx.values.port is typed as number
    // ctx.values.debug is typed as boolean
    console.log(`Server: ${ctx.values.host}:${ctx.values.port}`)
    if (ctx.values.debug) {
      console.log('Debug mode enabled')
    }
  }
})
```

### short()

Adds a single-character alias:

```ts [short-example.ts]
import { define } from 'gunshi'
import { string, boolean, short } from 'gunshi/combinators'

const command = define({
  name: 'example',
  args: {
    // -v for --verbose
    verbose: short(boolean(), 'v'),

    // -o for --output
    output: short(string({ description: 'Output file' }), 'o')
  },
  run: ctx => {
    if (ctx.values.verbose) {
      console.log('Verbose mode enabled')
    }
  }
})

// Usage: example -v -o result.txt
// Or: example --verbose --output result.txt
```

### describe()

Adds or updates the description of an argument:

```ts [describe-example.ts]
import { define } from 'gunshi'
import { string, required, describe } from 'gunshi/combinators'

const command = define({
  name: 'example',
  args: {
    // Add description to an existing combinator
    file: describe(required(string()), 'Path to the input file'),

    // Override existing description
    output: describe(string({ description: 'Old description' }), 'New description for output file')
  },
  run: ctx => {
    console.log(`Processing ${ctx.values.file}`)
  }
})
```

### hidden()

Marks an argument schema as hidden from generated usage/help output.

Use this for deprecated or internal options that should remain parseable:

```ts [hidden-example.ts]
import { define } from 'gunshi'
import { string, hidden } from 'gunshi/combinators'

const command = define({
  name: 'example',
  args: {
    publicMode: string(),

    // Kept for backward compatibility, but hidden from help
    legacyMode: hidden(string({ description: 'Deprecated internal flag' }))
  },
  run: ctx => {
    if (ctx.values.legacyMode) {
      console.log('legacy mode enabled')
    }
  }
})
```

### multiple()

Allows multiple values for an argument:

```ts [multiple-example.ts]
import { define } from 'gunshi'
import { string, integer, multiple } from 'gunshi/combinators'

const command = define({
  name: 'process',
  args: {
    // Accept multiple files
    files: multiple(string({ description: 'Input files' })),

    // Multiple ports
    ports: multiple(integer({ min: 1, max: 65535 }))
  },
  run: ctx => {
    // ctx.values.files is typed as string[] | undefined
    // ctx.values.ports is typed as number[] | undefined

    if (ctx.values.files) {
      console.log(`Processing ${ctx.values.files.length} files`)
      ctx.values.files.forEach(file => console.log(`  - ${file}`))
    }
  }
})

// Usage: process --files a.txt --files b.txt --ports 8080 --ports 8081
```

### map()

Transforms the parsed value:

```ts [map-example.ts]
import { define } from 'gunshi'
import { string, integer, map } from 'gunshi/combinators'

const command = define({
  name: 'convert',
  args: {
    // Convert to uppercase
    name: map(string(), s => s.toUpperCase()),

    // Transform number to percentage
    fraction: map(integer({ min: 0, max: 100 }), n => n / 100),

    // Parse and transform in one step
    size: map(string(), s => {
      const match = s.match(/^(\d+)(K|M|G)?$/i)
      if (!match) throw new Error('Invalid size format')

      const num = parseInt(match[1])
      const unit = match[2]?.toUpperCase()

      switch (unit) {
        case 'K':
          return num * 1024
        case 'M':
          return num * 1024 * 1024
        case 'G':
          return num * 1024 * 1024 * 1024
        default:
          return num
      }
    })
  },
  run: ctx => {
    // ctx.values.name is uppercase
    // ctx.values.fraction is between 0 and 1
    // ctx.values.size is in bytes
    console.log(`Name: ${ctx.values.name}`)
    console.log(`Fraction: ${ctx.values.fraction}`)
    console.log(`Size: ${ctx.values.size} bytes`)
  }
})

// Usage: convert --name hello --fraction 50 --size 10M
```

## Schema Composition

Schema composition combinators help you build reusable and maintainable argument configurations.

### args()

Creates a type-safe schema object (identity function at runtime, but preserves types):

```ts [args-example.ts]
import { define } from 'gunshi'
import { args, string, boolean, short } from 'gunshi/combinators'

// Define reusable schema groups
const debugOptions = args({
  verbose: short(boolean(), 'v'),
  debug: boolean(),
  logLevel: string()
})

const networkOptions = args({
  host: string(),
  port: integer(),
  timeout: integer()
})

// Use directly in command definition
const command = define({
  name: 'example',
  args: debugOptions, // Can use args() result directly
  run: ctx => {
    if (ctx.values.verbose) {
      console.log('Verbose output enabled')
    }
  }
})
```

### merge()

Combines multiple schemas with last-write-wins for conflicts:

```ts [merge-example.ts]
import { define } from 'gunshi'
import { args, merge, string, boolean, integer, withDefault, short } from 'gunshi/combinators'

// Common options used across commands
const common = args({
  verbose: short(boolean(), 'v'),
  quiet: short(boolean(), 'q'),
  config: string({ description: 'Config file path' })
})

// Network-related options
const network = args({
  host: withDefault(string(), 'localhost'),
  port: withDefault(integer({ min: 1, max: 65535 }), 8080),
  secure: boolean()
})

// Database options
const database = args({
  dbHost: withDefault(string(), 'localhost'),
  dbPort: withDefault(integer(), 5432),
  dbName: required(string())
})

// Compose different combinations for different commands
const serverCommand = define({
  name: 'server',
  args: merge(common, network),
  run: ctx => {
    console.log(`Server at ${ctx.values.host}:${ctx.values.port}`)
  }
})

const migrateCommand = define({
  name: 'migrate',
  args: merge(common, database),
  run: ctx => {
    console.log(`Migrating database ${ctx.values.dbName}`)
  }
})

// Merge all for complex commands
const fullCommand = define({
  name: 'full',
  args: merge(
    common,
    network,
    database,
    args({
      // Add command-specific options
      workers: integer({ description: 'Number of workers' })
    })
  ),
  run: ctx => {
    // Has access to all merged options
    console.log('Running with full configuration')
  }
})
```

### extend()

Overrides specific fields in a base schema:

```ts [extend-example.ts]
import { define } from 'gunshi'
import { args, extend, string, integer, boolean, required, withDefault } from 'gunshi/combinators'

// Base configuration
const baseConfig = args({
  name: string(),
  port: withDefault(integer(), 8080),
  debug: boolean()
})

// Production config: make name required, restrict port range
const productionConfig = extend(baseConfig, {
  name: required(string({ description: 'Service name (required)' })),
  port: required(
    integer({
      min: 443,
      max: 443,
      description: 'HTTPS port only'
    })
  ),
  debug: withDefault(boolean(), false) // Debug off by default in production
})

// Development config: relaxed settings
const developmentConfig = extend(baseConfig, {
  port: withDefault(integer({ min: 3000, max: 9999 }), 3000),
  debug: withDefault(boolean(), true) // Debug on by default in development
})

const prodCommand = define({
  name: 'start-prod',
  args: productionConfig,
  run: ctx => {
    // ctx.values.name is required (string)
    // ctx.values.port is required and must be 443
    console.log(`Production service ${ctx.values.name} on port ${ctx.values.port}`)
  }
})

const devCommand = define({
  name: 'start-dev',
  args: developmentConfig,
  run: ctx => {
    // More relaxed requirements for development
    console.log(`Development server on port ${ctx.values.port}`)
  }
})
```

## Complete Example

Here's a comprehensive example showing various combinator features working together:

```ts [cli.ts]
import { cli, define } from 'gunshi'
import {
  args,
  boolean,
  choice,
  combinator,
  extend,
  integer,
  map,
  merge,
  multiple,
  positional,
  required,
  short,
  string,
  withDefault
} from 'gunshi/combinators'

// Define reusable schema groups
const commonOptions = args({
  verbose: short(boolean({ description: 'Verbose output' }), 'v'),
  quiet: short(boolean({ description: 'Suppress output' }), 'q'),
  color: withDefault(choice(['auto', 'always', 'never'] as const), 'auto')
})

const networkOptions = args({
  host: withDefault(string({ description: 'Host to bind' }), '0.0.0.0'),
  port: withDefault(
    integer({
      min: 1,
      max: 65535,
      description: 'Port number'
    }),
    3000
  ),
  secure: boolean({ description: 'Use HTTPS' })
})

// Custom combinator for parsing duration
const duration = combinator({
  parse: (value: string) => {
    const match = value.match(/^(\d+)(ms|s|m|h)$/)
    if (!match) {
      throw new Error('Invalid duration format (use: 100ms, 5s, 2m, 1h)')
    }

    const num = parseInt(match[1])
    const unit = match[2]

    switch (unit) {
      case 'ms':
        return num
      case 's':
        return num * 1000
      case 'm':
        return num * 60 * 1000
      case 'h':
        return num * 60 * 60 * 1000
      default:
        return num
    }
  },
  metavar: '<duration>',
  description: 'Duration (e.g., 100ms, 5s, 2m, 1h)'
})

// Main command definition
const command = define({
  name: 'serve',
  description: 'Start a development server',

  args: merge(
    commonOptions,
    networkOptions,
    args({
      // Additional command-specific options
      entry: required(positional({ description: 'Entry file to serve' })),

      watch: multiple(string({ description: 'Directories to watch' })),

      timeout: withDefault(duration, 30000), // 30 seconds default

      mode: choice(['development', 'production', 'test'] as const, { description: 'Server mode' }),

      headers: map(multiple(string()), headers => {
        // Transform array of "key:value" strings to object
        const result: Record<string, string> = {}
        headers?.forEach(header => {
          const [key, value] = header.split(':')
          if (key && value) {
            result[key.trim()] = value.trim()
          }
        })
        return result
      })
    })
  ),

  run: ctx => {
    const { entry, host, port, secure, verbose, quiet, mode, timeout, watch, headers } = ctx.values

    if (!quiet) {
      console.log(`Starting ${mode || 'development'} server`)
      console.log(`Entry: ${entry}`)
      console.log(`Address: ${secure ? 'https' : 'http'}://${host}:${port}`)
      console.log(`Timeout: ${timeout}ms`)

      if (watch && watch.length > 0) {
        console.log(`Watching: ${watch.join(', ')}`)
      }

      if (headers && Object.keys(headers).length > 0) {
        console.log('Custom headers:')
        Object.entries(headers).forEach(([key, value]) => {
          console.log(`  ${key}: ${value}`)
        })
      }
    }

    if (verbose) {
      console.log('\nFull configuration:')
      console.log(JSON.stringify(ctx.values, null, 2))
    }
  }
})

// Execute the CLI
await cli(process.argv.slice(2), command, {
  name: 'serve-cli',
  version: '1.0.0'
})
```

Usage examples:

```sh
# Basic usage with required entry file
$ serve index.html

# Specify host and port
$ serve index.html --host localhost --port 8080

# Production mode with HTTPS
$ serve dist/index.html --mode production --secure

# Watch multiple directories with custom timeout
$ serve src/index.js --watch src --watch public --timeout 1m

# Add custom headers
$ serve index.html --headers "Cache-Control: no-cache" --headers "X-Custom: value"

# Verbose output
$ serve index.html -v
```

> \[!TIP]
> The complete example code is available [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/combinators).

## Type Inference

Parser combinators provide excellent TypeScript type inference:

```ts
import { define } from 'gunshi'
import { string, integer, boolean, withDefault, required, multiple } from 'gunshi/combinators'

const command = define({
  name: 'example',
  args: {
    // Type: string | undefined
    optional: string(),

    // Type: string (non-optional due to required)
    mandatory: required(string()),

    // Type: string (non-optional due to withDefault)
    withDef: withDefault(string(), 'default'),

    // Type: string[] | undefined
    multi: multiple(string()),

    // Type: number (non-optional, with constraints)
    port: withDefault(integer({ min: 1, max: 65535 }), 8080)
  },
  run: ctx => {
    // TypeScript knows all the types automatically
    // No manual type annotations needed!
    const { optional, mandatory, withDef, multi, port } = ctx.values
  }
})
```

## Guidelines

When using parser combinators, consider these guidelines:

1. **Start simple**: Begin with base combinators and add modifiers as needed
2. **Compose for reusability**: Create schema groups with `args()` for common option sets
3. **Use `withDefault` for better UX**: Provide sensible defaults to reduce required user input
4. **Leverage type safety**: Let TypeScript infer types rather than adding manual annotations
5. **Custom combinators for domain logic**: Use `combinator()` for specialized parsing needs
6. **Consistent naming**: Use descriptive names for your schema groups
7. **Test compositions**: Verify that merged and extended schemas behave as expected

## Migration from Traditional Approach

If you have existing commands using the traditional object approach, you can gradually migrate to combinators:

```ts
// Before: Traditional approach
const oldCommand = define({
  args: {
    port: {
      type: 'number',
      short: 'p',
      default: 8080,
      min: 1,
      max: 65535,
      description: 'Port number'
    }
  }
})

// After: Combinator approach
import { integer, withDefault, short } from 'gunshi/combinators'

const newCommand = define({
  args: {
    port: withDefault(
      short(
        integer({
          min: 1,
          max: 65535,
          description: 'Port number'
        }),
        'p'
      ),
      8080
    )
  }
})
```

Both approaches are fully compatible and can be mixed within the same application. Choose the approach that best fits your team's preferences and coding style.

---

---
url: /guide/advanced/command-hooks.md
---
# Command Hooks

Gunshi provides powerful lifecycle hooks that allow you to intercept and control command execution at various stages.

These hooks enable advanced scenarios like logging, monitoring, validation, and error handling.

## Understanding Command Lifecycle

The command execution lifecycle in Gunshi follows these stages:

```mermaid
graph TD
    Start([Start]) --> A[User Input]
    A --> B[Parse Arguments]
    B --> C[Apply Plugins]
    C --> D[Resolve Command]
    D --> E[Resolve Arguments]
    E --> F[Create Command Context]
    F --> G[onBeforeCommand Hook]
    G --> H{Success?}
    H -->|Yes| I[Execute Command]
    H -->|Error| K[onErrorCommand Hook]
    I --> J{Success?}
    J -->|Yes| L[onAfterCommand Hook]
    J -->|Error| K
    L --> M{Success?}
    M -->|Yes| N[Return Result]
    M -->|Error| K
    K --> O[Throw Error]
    N --> P([End])
    O --> P

    style G fill:#468c56,color:white
    style L fill:#468c56,color:white
    style K fill:#468c56,color:white
```

## Available Hooks

Gunshi provides three main lifecycle hooks:

* **`onBeforeCommand`**: Executes before the command runs
* **`onAfterCommand`**: Executes after successful command completion
* **`onErrorCommand`**: Executes when a command throws an error

Argument validation failures are also treated as command errors. Gunshi renders the validation
error message first, then calls `onErrorCommand` and rejects the `cli()` promise.

## Basic Hook Usage

### Setting Up Hooks

The following example demonstrates how to configure lifecycle hooks when initializing your CLI application.

In this setup, we define three hooks that will execute at different stages of the command lifecycle:

```ts [cli.ts]
import { cli, define } from 'gunshi'

const command = define({
  name: 'server',
  run: () => {
    console.log('Starting server...')
  }
})

await cli(process.argv.slice(2), command, {
  name: 'my-app',
  version: '1.0.0',

  // Define lifecycle hooks
  onBeforeCommand: ctx => {
    console.log(`About to run: ${ctx.name}`)
  },

  onAfterCommand: (ctx, result) => {
    console.log(`Command ${ctx.name} completed successfully`)
  },

  onErrorCommand: (ctx, error) => {
    console.error(`Command ${ctx.name} failed:`, error)
  }
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/command-hooks).

### Hook Parameters

Each lifecycle hook receives specific parameters that provide context about the command execution.

The `CommandContext` parameter is read-only and contains all command metadata, while `onAfterCommand` also receives the command result and `onErrorCommand` receives the thrown error:

```ts
{
  // Before command execution
  onBeforeCommand?: (ctx: Readonly<CommandContext>) => Awaitable<void>

  // After successful execution
  onAfterCommand?: (ctx: Readonly<CommandContext>, result: string | undefined) => Awaitable<void>

  // On command error
  onErrorCommand?: (ctx: Readonly<CommandContext>, error: Error) => Awaitable<void>
}
```

> \[!NOTE]
> The `CommandContext` object provides comprehensive information about command execution. For the complete CommandContext API reference including all properties and types, see the [CommandContext interface documentation](/api/default/interfaces/CommandContext.md).

With an understanding of how hooks work and their parameters, let's explore how they differ from and interact with plugin decorators.

### Handling Argument Validation Errors

When argument validation fails, Gunshi renders the validation error message before calling
`onErrorCommand`. You can detect this case with `ctx.validationError`:

```ts
import { cli, define } from 'gunshi'

const command = define({
  name: 'deploy',
  args: {
    id: {
      type: 'string',
      required: true
    }
  },
  run: ctx => {
    console.log(`Deploying ${ctx.values.id}`)
  }
})

let validationFailed = false

try {
  await cli(process.argv.slice(2), command, {
    onErrorCommand: (ctx, error) => {
      if (ctx.validationError === error) {
        validationFailed = true
        process.exitCode = 2
      }
    }
  })
} catch (error) {
  if (!validationFailed) {
    throw error
  }
}
```

## Hooks vs Decorators

Gunshi provides two distinct mechanisms for controlling command execution:

1. **CLI-level Hooks**: Lifecycle hooks that run **before and after** command execution
   * `onBeforeCommand`: Pre-execution processing (logging, validation, initialization)
   * `onAfterCommand`: Post-success processing (cleanup, metrics recording)
   * `onErrorCommand`: Error handling (error logging, rollback)

2. **Plugin Decorators**: **Wrap** the command itself to modify its behavior
   * `decorateCommand`: Wraps command runner to add or modify functionality
   * Multiple plugins can chain decorators (decorator pattern)

> \[!TIP]
> The `decorateCommand` method is a powerful plugin API that allows wrapping command execution to add or modify functionality. It enables plugins to implement cross-cutting concerns like authentication, logging, and transaction management. For comprehensive information about how to use decorators in plugins, see the [Plugin Decorators documentation](/guide/plugin/decorators.md).

### Execution Flow

The following diagram illustrates how hooks and decorators interact during command execution:

```mermaid
graph TD
    A[onBeforeCommand Hook] --> B{Success?}
    B -->|Yes| C[Plugin Decorators Chain]
    B -->|Error| G[onErrorCommand Hook]

    C --> D[Decorated Command Runner]
    D --> E{Success?}

    E -->|Yes| F[onAfterCommand Hook]
    E -->|Error| G

    F --> H{Success?}
    H -->|Yes| I[Return Result]
    H -->|Error| G

    G --> J[Throw Error]

    style A fill:#468c56,color:white
    style F fill:#468c56,color:white
    style G fill:#468c56,color:white
    style C fill:#7EA6E0,color:white
    style D fill:#7EA6E0,color:white
```

### Detailed Execution Sequence

1. **`onBeforeCommand` Hook** - Pre-execution setup and validation
2. **Plugin Decorator Chain** - Command wrapping by plugins
   * Applied in reverse order (LIFO - last registered, first executed)
   * Each decorator wraps the next runner in the chain
3. **Command Runner** - Actual command execution
4. **`onAfterCommand` Hook** - Post-success processing
5. **`onErrorCommand` Hook** - Error handling when exceptions occur

### Plugin Decorator Example

The following example demonstrates how to use the `decorateCommand` method in a plugin to measure command execution time:

```ts
import { plugin } from 'gunshi/plugin'

// Using decorateCommand in a plugin
export default plugin({
  id: 'timing-plugin',
  setup: ctx => {
    // Wrap command execution to measure execution time
    ctx.decorateCommand(baseRunner => {
      return async commandCtx => {
        const start = Date.now()
        try {
          const result = await baseRunner(commandCtx)
          console.log(`Execution time: ${Date.now() - start}ms`)
          return result
        } catch (error) {
          console.log(`Failed after: ${Date.now() - start}ms`)
          throw error
        }
      }
    })
  }
})
```

> \[!NOTE]
> Plugins don't have CLI-level hooks (`onBeforeCommand`, etc.). Instead, they use the `decorateCommand` method to wrap command execution and add custom logic. This allows plugins to extend and modify command behavior through the decorator pattern.

## Practical Use Cases

> \[!TIP]
> The following examples use plugin extensions through `ctx.extensions`. Extensions are how plugins add functionality to the command context, allowing you to access plugin-provided features like logging, metrics, authentication, and database connections. For comprehensive information about working with extensions, including type-safe patterns and best practices, see the [Context Extensions documentation](./context-extensions.md).

### Logging and Monitoring

Implement comprehensive logging across all commands:

```ts
import { cli } from 'gunshi'
import logger, { pluginId as loggerId } from '@my/plugin-logger'

await cli(process.argv.slice(2), commands, {
  name: 'my-app',

  // Install logger plugin
  plugins: [logger()],

  onBeforeCommand: ctx => {
    const logger = ctx.extensions[loggerId]
    // Log command start with arguments
    logger?.info('Command started', {
      command: ctx.name,
      args: ctx.values,
      timestamp: new Date().toISOString()
    })
  },

  onAfterCommand: (ctx, result) => {
    const logger = ctx.extensions[loggerId]
    // Log successful completion
    logger?.info('Command completed', {
      command: ctx.name,
      duration: Date.now() - logger?.startTime,
      result: typeof result
    })
  },

  onErrorCommand: (ctx, error) => {
    const logger = ctx.extensions[loggerId]
    // Log errors with full context
    logger?.error('Command failed', {
      command: ctx.name,
      error: error.message,
      stack: error.stack,
      args: ctx.values
    })
  }
})
```

### Performance Monitoring

Track command execution times and performance metrics:

```ts
import { cli } from 'gunshi'
import metrics, { pluginId as metricsId } from '@my/plugin-metrics'

await cli(process.argv.slice(2), commands, {
  name: 'my-app',

  // Install metrics plugin
  plugins: [metrics()],

  onBeforeCommand: ctx => {
    const metrics = ctx.extensions[metricsId]
    // Start tracking command execution
    metrics?.startTracking({
      command: ctx.name,
      args: ctx.values,
      environment: process.env.NODE_ENV
    })
  },

  onAfterCommand: async (ctx, result) => {
    const metrics = ctx.extensions[metricsId]
    // Record successful completion
    const duration = metrics?.endTracking()

    // Send metrics to monitoring service
    await metrics?.send({
      command: ctx.name,
      status: 'success',
      duration,
      memoryUsage: process.memoryUsage(),
      resultSize: result?.length || 0
    })
  },

  onErrorCommand: async (ctx, error) => {
    const metrics = ctx.extensions[metricsId]
    // Record failure metrics
    const duration = metrics?.endTracking()

    // Send error metrics with additional context
    await metrics?.send({
      command: ctx.name,
      status: 'failed',
      duration,
      error: error.message,
      errorType: error.constructor.name,
      stackTrace: error.stack
    })
  }
})
```

### Validation and Guards

Use hooks to implement global validation or access control:

```ts
import { cli } from 'gunshi'
import auth, { pluginId as authId } from '@my/plugin-auth'

await cli(process.argv.slice(2), commands, {
  name: 'my-app',

  // Install auth plugin
  plugins: [
    auth({
      publicCommands: ['help', 'version', 'login'],
      tokenSource: ['env:AUTH_TOKEN', 'args:token']
    })
  ],

  onBeforeCommand: async ctx => {
    const auth = ctx.extensions[authId]

    // Skip auth for public commands
    if (auth?.isPublicCommand(ctx.name)) {
      return
    }

    // Verify authentication
    const token = auth?.getToken()
    if (!token) {
      throw new Error('Authentication required. Please run "login" first.')
    }

    const user = await auth?.verifyToken(token)
    if (!user) {
      throw new Error('Invalid or expired token. Please login again.')
    }

    // Store user info for command use
    await auth?.setCurrentUser(user)
  },

  onAfterCommand: async ctx => {
    const auth = ctx.extensions[authId]
    // Clean up sensitive data after command execution
    await auth?.clearSession()
  },

  onErrorCommand: async (ctx, error) => {
    const auth = ctx.extensions[authId]
    // Log security-related errors
    if (error.message.includes('Authentication') || error.message.includes('token')) {
      await auth?.logSecurityEvent({
        type: 'auth_failure',
        command: ctx.name,
        timestamp: new Date().toISOString()
      })
    }
  }
})
```

### Transaction Management

Implement database transactions or rollback mechanisms:

```ts
import { cli } from 'gunshi'
import database, { pluginId as dbId } from '@my/plugin-database'

await cli(process.argv.slice(2), commands, {
  name: 'my-app',

  // Install database plugin with transaction support
  plugins: [
    database({
      connectionString: process.env.DATABASE_URL,
      transactionalCommands: ['create', 'update', 'delete', 'migrate']
    })
  ],

  onBeforeCommand: async ctx => {
    const db = ctx.extensions[dbId]

    // Start transaction for data-modifying commands
    if (db?.isTransactionalCommand(ctx.name)) {
      const transaction = await db.beginTransaction()

      // Store transaction ID for tracking
      await db?.setCurrentTransaction(transaction.id)

      console.log(`Transaction ${transaction.id} started for command: ${ctx.name}`)
    }
  },

  onAfterCommand: async (ctx, result) => {
    const db = ctx.extensions[dbId]
    const transaction = db?.getCurrentTransaction()

    if (transaction) {
      // Commit on success
      await db.commit(transaction.id)
      console.log(`Transaction ${transaction.id} committed successfully`)

      // Clean up transaction reference
      await db.clearCurrentTransaction()
    }
  },

  onErrorCommand: async (ctx, error) => {
    const db = ctx.extensions[dbId]
    const transaction = db?.getCurrentTransaction()

    if (transaction) {
      // Rollback on error
      await db?.rollback(transaction.id)
      console.error(`Transaction ${transaction.id} rolled back due to error:`, error.message)

      // Log the failed transaction for audit
      await db?.logTransactionFailure({
        id: transaction.id,
        command: ctx.name,
        error: error.message,
        timestamp: new Date().toISOString()
      })

      // Clean up transaction reference
      await db?.clearCurrentTransaction()
    }
  }
})
```

## Hook Execution Order

When multiple hooks and decorators are present, they execute in a specific sequence as shown in the Hooks vs Decorators section above.

Understanding this order is crucial for implementing complex behaviors like transaction management or error recovery.

For detailed execution flow, refer to the execution diagram in the [Hooks vs Decorators](#hooks-vs-decorators) section.

---

---
url: /guide/advanced/context-extensions.md
---
# Context Extensions

Plugins in Gunshi extend the command context with additional functionality through the extension system.

This guide explains how to leverage these extensions to build more powerful CLI applications.

> \[!TIP]
> This guide assumes familiarity with the basic concepts explained in the [Plugin System](../essentials/plugin-system.md). Context extensions are a core feature of the plugin system, providing the mechanism through which plugins deliver functionality to commands.

## Understanding Context Extensions

The command context (`ctx`) is the central object passed to every command runner.

Plugins enhance this context by adding new capabilities through the extensions property, allowing your commands to access additional functionality like logging, internationalization, or custom services.

Each plugin contributes its own extension under a unique namespace, ensuring clean separation of concerns and preventing conflicts between different plugins.

```ts
import { define } from 'gunshi'

// Basic command context
const command = define({
  run: ctx => {
    // Default context properties
    ctx.name // Command name
    ctx.version // CLI version
    ctx.values // Parsed argument values
    ctx.args // Raw arguments

    // Plugin extensions
    ctx.extensions // Object containing all plugin extensions
  }
})
```

## How Extensions Work

Each plugin registers its extension under a unique identifier (plugin ID) within the `ctx.extensions` object.

This namespacing approach prevents collisions between plugins and makes dependencies explicit.

When a plugin is added to your CLI configuration, its extension becomes available to all commands through this standardized interface:

> \[!TIP]
> For details on how plugin extensions work, see the [Plugin Extensions](../plugin/extensions.md) guide.

```ts
import { define } from 'gunshi'
import { pluginId as globalId } from '@gunshi/plugin-global'

const command = define({
  run: ctx => {
    // Access global plugin extension
    const globalExtension = ctx.extensions[globalId]

    // Use extension methods
    globalExtension.showVersion()
    globalExtension.showHeader()
  }
})
```

## Working with Built-in Plugin Extensions

Gunshi provides several official plugins with pre-built extensions that cover common CLI needs.

Understanding how to use these extensions effectively will accelerate your CLI development.

### Global Plugin Extension

The global plugin (`@gunshi/plugin-global`) provides methods for displaying CLI information:

```ts
import { define } from 'gunshi'
import { pluginId as globalId } from '@gunshi/plugin-global'

const command = define({
  run: ctx => {
    const global = ctx.extensions[globalId]

    // Show version information
    global.showVersion()

    // Show command header
    global.showHeader()

    // Show usage information
    global.showUsage()

    // Show validation errors
    if (ctx.validationError) {
      global.showValidationErrors(ctx.validationError)
    }
  }
})
```

> \[!NOTE]
> For a complete list of official plugins and their features, see the [Plugin List](../plugin/list.md) guide.

### Renderer Plugin Extension

The renderer plugin (`@gunshi/plugin-renderer`) provides text rendering capabilities:

```ts
import { define } from 'gunshi'
import { pluginId as rendererId } from '@gunshi/plugin-renderer'

const command = define({
  run: async ctx => {
    // Check if renderer extension is available
    const renderer = ctx.extensions[rendererId]

    if (renderer) {
      // Get translated text
      const helpText = await renderer.text('HELP')

      // Load subcommands for display
      const commands = await renderer.loadCommands()
    }
  }
})
```

> \[!NOTE]
> The renderer plugin is typically added by the global plugin when used together. For detailed information about the renderer plugin API, see the [Renderer Plugin documentation](https://github.com/kazupon/gunshi/tree/main/packages/plugin-renderer)

## Using Optional Plugin Extensions

Beyond the core plugins, Gunshi's ecosystem includes optional plugins for specialized functionality.

These extensions follow the same patterns but may not be present in all CLI configurations.

### I18n Plugin Extension

The i18n plugin provides translation capabilities through context extensions:

```ts
import { define } from 'gunshi'
import { pluginId as i18nId } from '@gunshi/plugin-i18n'

const command = define({
  run: ctx => {
    const i18n = ctx.extensions[i18nId]

    if (i18n) {
      // Access current locale
      console.log(`Running in ${i18n.locale} locale`)

      // Use translation function
      const message = i18n.translate('welcome')
      console.log(message)
    }
  }
})
```

> \[!NOTE]
> For comprehensive i18n usage including `resolveKey`, `defineI18n`, resource management, and working with subcommands, see the [Internationalization guide](./internationalization.md)

## Extension Techniques

The following techniques demonstrate code for working effectively with extensions in various scenarios.

These approaches ensure your commands remain flexible, maintainable, and resilient.

### Safe Extension Access

Extensions may not always be available depending on your CLI configuration and which plugins are installed.

Commands should defensively check for extension existence to prevent runtime errors and provide graceful fallbacks.

This defensive programming approach ensures your CLI remains robust even when optional plugins are not configured:

```ts
import { define } from 'gunshi'
import { pluginId as globalId } from '@gunshi/plugin-global'

const command = define({
  run: async ctx => {
    // Safe access technique
    const global = ctx.extensions[globalId]

    if (global) {
      // Extension is available
      await global.showUsage()
    } else {
      // Fallback behavior
      console.log('Usage information not available')
    }
  }
})
```

### Extension Composition

Commands often benefit from combining multiple plugin extensions to create richer functionality.

Extensions are designed to work together harmoniously, allowing you to compose complex behaviors from simple building blocks.

The following example demonstrates how global display features can be enhanced with dynamic content loading from the renderer extension:

```ts
import { define } from 'gunshi'
import { pluginId as globalId } from '@gunshi/plugin-global'
import { pluginId as rendererId } from '@gunshi/plugin-renderer'

const command = define({
  run: async ctx => {
    const global = ctx.extensions[globalId]
    const renderer = ctx.extensions[rendererId]

    // Combine extensions for rich functionality
    if (global && renderer) {
      // Show header using global extension
      global.showHeader()

      // Load and display commands if renderer is available
      const commands = await renderer.loadCommands()
      console.log('Available commands:', commands)
    }
  }
})
```

### Dynamic Extension Usage

Extensions can be conditionally utilized based on command arguments, environment variables, or other runtime conditions.

This dynamic approach allows your CLI to adapt its behavior to different contexts and user preferences.

The following code shows how to selectively engage extensions based on command flags.
Note the `help` argument: declaring it is what makes `--help` reach this command's runner, because a
command's own argument shadows the global option of the same name. `showUsage()` is asynchronous, so
the runner awaits it.

```ts
import { define } from 'gunshi'
import { pluginId as globalId } from '@gunshi/plugin-global'
import { pluginId as loggerId } from '@my/plugin-logger'

const command = define({
  args: {
    verbose: { type: 'boolean' },
    debug: { type: 'boolean' },
    help: { type: 'boolean' }
  },
  run: async ctx => {
    // Use extensions based on command flags
    if (ctx.values.help) {
      await ctx.extensions[globalId]?.showUsage()
      return
    }

    // Conditional extension usage for verbose mode
    if (ctx.values.verbose) {
      const global = ctx.extensions[globalId]
      global?.showHeader()
      console.log('Running in verbose mode...')
    }

    // Enable debug features if available
    // Check if a hypothetical logger extension exists
    if (ctx.values.debug && ctx.extensions[loggerId]) {
      ctx.extensions[loggerId].setLevel('debug')
    }

    // Your command logic here
    console.log('Command executed')
  }
})
```

## Type-Safe Extensions

Use TypeScript for compile-time safety with extensions:

```ts
import { define } from 'gunshi'
import { pluginId as globalId } from '@gunshi/plugin-global'
import type { GlobalExtension, PluginId as GlobalId } from '@gunshi/plugin-global'

// Define command with typed extensions
const command = define<Record<GlobalId, GlobalExtension>>({
  name: 'app',
  run: ctx => {
    // TypeScript knows about the global extension
    ctx.extensions[globalId].showVersion()
    ctx.extensions[globalId].showUsage()

    // Type errors for unknown extensions
    // ctx.extensions['unknown'].method() // Compile-time error!
  }
})
```

> \[!NOTE]
> For comprehensive type parameter usage including `GunshiParams`, combining multiple plugin types with the intersection (`&`), and advanced type safety techniques, see the [Type System guide](./type-system.md)

## Custom Extension Techniques

Extensions can serve as a foundation for building sophisticated CLI architectures.

The following advanced patterns showcase how to leverage extensions for service layers and architectural concerns.

### Extension as Service Layer

Extensions can act as a service abstraction layer, providing consistent interfaces to external systems like databases, caches, or APIs.

This pattern decouples your command logic from infrastructure concerns and simplifies testing through mockable extensions:

```ts
// Note: These are hypothetical example plugins for illustration purposes
// You would need to create or install actual plugins with these capabilities
import { define } from 'gunshi'
import { pluginId as dbId } from '@my/plugin-db' // Example custom plugin
import { pluginId as cacheId } from '@my/plugin-cache' // Example custom plugin

// With hypothetical database and cache plugins
const command = define({
  run: async ctx => {
    const db = ctx.extensions[dbId]
    const cache = ctx.extensions[cacheId]

    // Check cache first
    const cached = await cache?.get('users')
    if (cached) {
      return cached
    }

    // Fetch from database
    const users = await db?.query('SELECT * FROM users')

    // Cache the result
    await cache?.set('users', users, { ttl: 3600 })

    return users
  }
})
```

### Extension for Cross-Cutting Concerns

Cross-cutting concerns are aspects of your application that affect multiple commands, such as logging, authentication, monitoring, or error tracking.

Extensions provide an ideal mechanism for implementing these concerns consistently across your entire CLI.

By centralizing these capabilities in plugin extensions, you ensure uniform behavior and simplify maintenance.

The following example demonstrates a comprehensive approach to handling logging, authentication, and metrics collection:

```ts
// Note: These are hypothetical example plugins for illustration purposes
import { define } from 'gunshi'
import { pluginId as loggerId } from '@my/plugin-logger'
import { pluginId as authId } from '@my/plugin-auth'
import { pluginId as metricsId } from '@my/plugin-metrics'

const command = define({
  run: async ctx => {
    const logger = ctx.extensions[loggerId]
    const auth = ctx.extensions[authId]
    const metrics = ctx.extensions[metricsId]

    const startTime = Date.now()
    logger?.info('Command started', { command: ctx.name })

    // Check authentication
    if (!auth?.isAuthenticated()) {
      logger?.error('Authentication required')
      throw new Error('Please login first')
    }

    try {
      // Your actual command logic
      // processData is a placeholder for your data processing logic
      const result = await processData(ctx.values)

      // Track success metrics
      metrics?.track('command.success', {
        command: ctx.name,
        duration: Date.now() - startTime
      })

      logger?.info('Command completed successfully')
      return result
    } catch (error) {
      logger?.error('Command failed', { error: error.message })
      metrics?.track('command.failure', {
        command: ctx.name,
        error: error.message
      })
      throw error
    }
  }
})
```

> \[!TIP]
> Learn how to create your own plugins with custom extensions in the [Plugin Development](../plugin/introduction.md) guide.

## Guidelines for Plugin Usage

### 1. Always Import Plugin IDs

Never hardcode plugin ID strings. Always import and use the exported constants to avoid typos and ensure type safety:

```js
// ✅ Good: Import and use plugin ID constants
import i18n, { pluginId as i18nId } from '@gunshi/plugin-i18n'
import global, { pluginId as globalId } from '@gunshi/plugin-global'

// Use the imported IDs
const i18nExt = ctx.extensions[i18nId]
const globalExt = ctx.extensions[globalId]

// ❌ Bad: Hardcoded strings are fragile and error-prone
const i18nExt = ctx.extensions['g:i18n'] // Don't do this!
```

### 2. Handle Optional Plugin Extensions Gracefully

When plugins might not be available, always check for extension existence to avoid runtime errors:

```js
import { pluginId as globalId } from '@gunshi/plugin-global'

run: ctx => {
  // Safe access with optional chaining
  const version = ctx.extensions[globalId]?.showVersion() || 'Version unknown'

  // Or explicit checking for complex logic
  const globalExt = ctx.extensions[globalId]
  if (globalExt) {
    // Plugin is available - use full features
    globalExt.showHeader()
    globalExt.showUsage()
  } else {
    // Graceful fallback
    console.log('Help not available')
  }
}
```

### 3. Use TypeScript for Safety

When using TypeScript, leverage type definitions for compile-time safety:

```ts
import { define } from 'gunshi'
import { pluginId as globalId } from '@gunshi/plugin-global'
import type { GlobalExtension, PluginId as GlobalId } from '@gunshi/plugin-global'

// Type-safe command with extension
const command = define<Record<GlobalId, GlobalExtension>>({
  name: 'deploy',
  run: ctx => {
    // TypeScript ensures type safety
    ctx.extensions[globalId].showVersion()
  }
})
```

> \[!NOTE]
> For advanced TypeScript techniques including combining multiple plugin types and using `GunshiParams`, see the [Type System guide](./type-system.md).

## Troubleshooting

### Extension Not Found

If an extension is not available:

```js
// Debug which extensions are available
console.log('Available extensions:', Object.keys(ctx.extensions))

// Check if plugin was added
if (!ctx.extensions[pluginId]) {
  console.error(`Plugin ${pluginId} not installed`)
  console.error('Add it to your CLI plugins:')
  console.error('plugins: [yourPlugin()]')
}
```

### Type Errors with Extensions

For TypeScript users, ensure proper type definitions:

```ts
// Import types
import type { YourExtension, PluginId } from 'your-plugin'

// Define with proper types
const command = define<Record<PluginId, YourExtension>>({
  // Command definition
})
```

### Extension Method Not Working

Check the plugin documentation for correct usage:

```js
import { pluginId as globalId } from '@gunshi/plugin-global'

// Wrong: Direct method call without checking
ctx.extensions[globalId].showVersion() // May fail if plugin not available

// Right: Store reference and check existence first
const global = ctx.extensions[globalId]
if (global) {
  global.showVersion()
}
```

---

---
url: /guide/advanced/custom-rendering.md
---
# Custom Rendering

Gunshi provides a flexible rendering system that allows you to customize how your CLI displays help text, usage information, and error messages.

## Overview

Gunshi provides three levels of customization, each capable of controlling all rendering components (Header, Usage/Help, and Validation Errors).

When multiple levels define the same renderer, the higher priority level wins.

Customizing rendering offers several benefits:

* **Branding**: Match your CLI's help messages to your project's style
* **Clarity**: Organize information in a way that makes sense for your users
* **Flexibility**: Add custom sections or formatting to help messages
* **Consistency**: Ensure help messages follow your organization's standards

## Three-Level Customization System

```mermaid
graph TB
    subgraph " "
        subgraph "Plugin Level"
            PH[Header]
            PU[Usage/Help]
            PE[Validation Errors]
        end
        subgraph "CLI Level"
            CLH[Header]
            CLU[Usage/Help]
            CLE[Validation Errors]
        end
        subgraph "Command Level"
            CH[Header]
            CU[Usage/Help]
            CE[Validation Errors]
        end
    end

    style CH fill:#468c56,color:white
    style CU fill:#468c56,color:white
    style CE fill:#468c56,color:white
    style CLH fill:#468c56,color:white
    style CLU fill:#468c56,color:white
    style CLE fill:#468c56,color:white
    style PH fill:#468c56,color:white
    style PU fill:#468c56,color:white
    style PE fill:#468c56,color:white
```

The diagram above illustrates Gunshi's three-level rendering customization system.

Each level can independently control three rendering components:

* **Header**: The title section of help text, typically showing the CLI name and version
* **Usage/Help**: The main help content including command syntax, options, and arguments
* **Validation Errors**: Error messages shown when command arguments fail validation

The levels work in a priority hierarchy where:

* **Command Level** (top) has the highest priority and overrides all other levels
* **CLI Level** (middle) provides defaults for all commands in your application
* **Plugin Level** (bottom) adds reusable rendering logic through decorators

## Renderer Resolution

Gunshi checks each customization level in priority order (Command → CLI → Plugin) and uses the first renderer it finds:

```mermaid
graph TD
    Start[Rendering Request] --> P1{Command.rendering defined?}
    P1 -->|Yes| UseCommand[Use Command Rendering]
    P1 -->|No| P2{CLI Options defined?}
    P2 -->|Yes| UseCLI[Use CLI Rendering]
    P2 -->|No| P3{Plugin Decorators?}
    P3 -->|Yes| UsePlugin[Apply Plugin Decorators]
    P3 -->|No| Default[Use Default]

    UseCommand --> Output[Final Output]
    UseCLI --> Output
    UsePlugin --> Output
    Default --> Output

    style UseCommand fill:#468c56,color:white
    style UseCLI fill:#468c56,color:white
    style UsePlugin fill:#468c56,color:white
    style Default fill:#468c56,color:white
```

## How It Works

This example shows the rendering resolution flow when a user runs a command with `--help`:

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant Command
    participant Plugin
    participant Output

    User->>CLI: Run command with --help
    CLI->>Command: Check command.rendering
    alt Has command.rendering
        Command->>Output: Use command renderer
    else Has CLI options
        CLI->>Output: Use CLI renderer
    else Has plugins
        CLI->>Plugin: Apply plugin decorators
        Plugin->>Output: Use decorated renderer
    else
        CLI->>Output: Use default renderer
    end
    Output->>User: Display formatted help
```

## Command-Level Rendering

The most specific way to customize rendering is at the command level. Use this when:

* A specific command needs unique formatting or branding
* Different commands require different help layouts
* You want to override global settings for particular commands

### Understanding Command Context

All renderer functions receive a Command Context object as their first parameter.

This context provides comprehensive information about the current command execution state, including configuration, arguments, environment details, and more.

```js
// Renderer functions receive context as their first argument
renderHeader: ctx => {
  // ctx contains all command execution information
  return `${ctx.env.name} - ${ctx.description}`
}
```

> \[!NOTE]
> The Command Context (`ctx`) is a read-only object that provides access to command metadata, parsed arguments, environment configuration, and plugin extensions. For the complete CommandContext API reference including all properties and types, see the [CommandContext interface documentation](../../api/default/interfaces/CommandContext).

### Basic Example

The following example demonstrates how to customize rendering at the command level for a watch command that needs specialized formatting for its interactive mode.

Notice how the renderer functions receive a Command Context (`ctx`) parameter that provides access to command information:

```js
import { define } from 'gunshi'

const command = define({
  name: 'watch',
  description: 'Watch files and rebuild on changes',

  // Command-specific rendering for interactive watch mode
  rendering: {
    header: ctx => {
      return `👁️  WATCH MODE - Press Ctrl+C to stop`
    },

    usage: ctx => {
      return `Usage: ${ctx.name} [options]

Watch Options:
  --entry <file>     Entry point (default: src/index.ts)
  --out <dir>        Output directory (default: dist)
  --ignore <pattern> Ignore patterns

Keyboard Shortcuts (during watch):
  r - Force rebuild
  c - Clear console
  q - Quit watch mode`
    },

    validationErrors: (ctx, error) => {
      // Watch-specific error formatting
      return `⚠️  Watch mode cannot start:\n${error.errors.map(err => `   • ${err.message}`).join('\n')}`
    }
  },

  run: async ctx => {
    // Command logic ...
  }
})
```

### Practical Examples

Here's how to create custom renderers for specific use cases:

```js
import { cli, define } from 'gunshi'

// Define a custom header renderer with fancy formatting
const customHeaderRenderer = ctx => {
  const lines = []

  // Add a fancy header
  lines.push('╔═════════════════════════════════════════╗')
  lines.push(`║ ${ctx.env.name.toUpperCase().padStart(20).padEnd(39)} ║`)
  lines.push('╚═════════════════════════════════════════╝')

  // Add description and version
  if (ctx.env.description) {
    lines.push(ctx.env.description)
  }

  if (ctx.env.version) {
    lines.push(`Version: ${ctx.env.version}`)
  }

  lines.push('')

  // Return the header as a string
  return lines.join('\n')
}

// Define your command
const command = define({
  name: 'app',
  description: 'My application',
  args: {
    name: {
      type: 'string',
      short: 'n',
      description: 'Name to use'
    }
  },
  run: ctx => {
    // Command implementation
  }
})

// Run the command with the custom header renderer
await cli(process.argv.slice(2), command, {
  name: 'my-app',
  version: '1.0.0',
  description: 'A CLI application with custom usage generation',
  renderHeader: customHeaderRenderer
})
```

When users run `node app.js --help`, they'll see your custom header:

```sh
╔═════════════════════════════════════════╗
║               MY-APP                    ║
╚═════════════════════════════════════════╝
A CLI application with custom usage generation
Version: 1.0.0


USAGE:
  my-app <OPTIONS>

OPTIONS:
  -n, --name <name>          Name to use
  -h, --help                 Display this help message
  -v, --version              Display this version
```

### Disabling Renderers

Set any renderer to `null` to disable it:

```js
rendering: {
  header: null,           // No header
  usage: async () => '...' // Custom usage
}
```

## CLI-Level Rendering

Set default renderers for all commands in your CLI. Use this when:

* You want consistent formatting across your entire application
* All commands should share the same branding or style
* You need a baseline that individual commands can override

### Basic Configuration

```js
import { cli } from 'gunshi'

await cli(process.argv.slice(2), command, {
  name: 'my-cli',
  version: '1.0.0',

  // Apply to all commands
  renderHeader: ctx => {
    return `=== ${ctx.env.name} v${ctx.env.version} ===`
  },

  renderUsage: ctx => {
    return `${ctx.env.name} ${ctx.name || 'command'} [options]`
  },

  renderValidationErrors: (ctx, error) => {
    return `Error: ${error.message}`
  }
})
```

> \[!NOTE]
> `renderValidationErrors` only customizes how validation errors are displayed. Validation failures still reject the `cli()` promise and are passed to `onErrorCommand`. Use `onErrorCommand` if your application needs to set a runtime-specific exit code or suppress the default unhandled error output. For an example, see [Handling Argument Validation Errors](./command-hooks.md#handling-argument-validation-errors).

### Combined Renderers Example

You can combine all three custom renderers for a completely customized help experience:

```js
import { cli, define } from 'gunshi'

// Define a command
const command = define({
  name: 'task-manager',
  description: 'A task management utility',
  args: {
    add: {
      type: 'string',
      short: 'a',
      description: 'Add a new task'
    },
    list: {
      type: 'boolean',
      short: 'l',
      description: 'List all tasks'
    },
    complete: {
      type: 'string',
      short: 'c',
      description: 'Mark a task as complete'
    },
    priority: {
      type: 'string',
      short: 'p',
      description: 'Set task priority (low, medium, high)'
    },
    due: {
      type: 'string',
      short: 'd',
      description: 'Set due date in YYYY-MM-DD format'
    }
  },
  examples: `# Add a new task
$ task-manager --add "Complete the project"

# Add a task with priority and due date
$ task-manager --add "Important meeting" --priority high --due 2023-12-31

# List all tasks
$ task-manager --list

# Mark a task as complete
$ task-manager --complete "Complete the project"`,
  run: ctx => {
    // Command implementation
  }
})

// Define custom usage renderer
const customUsageRenderer = ctx => {
  const lines = []
  lines.push('📋 USAGE:')
  lines.push(`  ${ctx.env.name} [options]`)
  lines.push('')
  lines.push('⚡ QUICK START:')
  lines.push('  Run with --help for detailed options')
  return lines.join('\n')
}

// Define custom validation errors renderer
const customValidationErrorsRenderer = (ctx, error) => {
  const lines = []
  lines.push('❌ VALIDATION ERROR')
  lines.push('────────────────────')

  // Display each validation error
  for (const e of error.errors) {
    lines.push(`  • ${e.message}`)
  }

  lines.push('')
  lines.push('💡 TIP: Use --help to see valid options')
  return lines.join('\n')
}

// Run the CLI with all custom renderers
await cli(process.argv.slice(2), command, {
  name: 'task-manager',
  version: '1.0.0',
  description: 'A task management utility',
  renderHeader: customHeaderRenderer,
  renderUsage: customUsageRenderer,
  renderValidationErrors: customValidationErrorsRenderer
})
```

## Plugin-Level Rendering

Plugins provide the most powerful way to customize rendering across your entire CLI.

They can decorate renderers to add consistent behavior across all commands.

> \[!NOTE]
> Plugin-level rendering has the lowest priority in the rendering hierarchy. Command-level and global-level renderers will override plugin decorators. For detailed information on how renderer decorators work and how to implement them, see the [How Renderer Decorators Work](../plugin/decorators.md#how-renderer-decorators-work) documentation.

### Using the Built-in Renderer Plugin

The `@gunshi/plugin-renderer` package provides enhanced rendering out of the box:

```js
import { cli } from 'gunshi/bone'
import renderer from '@gunshi/plugin-renderer'

await cli(process.argv.slice(2), command, {
  name: 'my-cli',
  plugins: [
    renderer() // Adds enhanced rendering
  ]
})
```

The built-in renderer provides complete rendering implementations with improved formatting and visual hierarchy.

Unlike decorator plugins, it replaces the default rendering entirely.

> \[!TIP]
> For detailed features of the built-in renderer plugin, see the [documentation](https://github.com/kazupon/gunshi/blob/main/packages/plugin-renderer/README.md).

### Creating a Custom Rendering Plugin

When building rendering plugins, use the decorator pattern to enhance existing output:

```js
import { plugin } from 'gunshi/plugin'

const color = plugin({
  id: 'my:color',
  name: 'Color Plugin',

  setup(context) {
    // Decorate header renderer
    context.decorateHeaderRenderer(async (baseRenderer, ctx) => {
      const output = await baseRenderer(ctx)
      if (!output) {
        return ''
      }

      return `\x1b[36m${output}\x1b[0m` // Add cyan color
    })

    // Decorate error renderer
    context.decorateValidationErrorsRenderer(async (baseRenderer, ctx, error) => {
      const output = await baseRenderer(ctx, error)
      if (!output) {
        return ''
      }

      return `\x1b[31m${output}\x1b[0m` // Add red color
    })
  }
})
```

> \[!IMPORTANT]
> Always call `baseRenderer` in your decorators to maintain the plugin chain. This ensures compatibility with other plugins.

### Practical Example: Theme Plugin

Here's a complete theme plugin that enhances all rendering aspects:

```js
import { plugin } from 'gunshi/plugin'

const oceanTheme = plugin({
  id: 'themes:ocean',
  name: 'Ocean Theme',

  setup(context) {
    const colors = {
      header: '\x1b[36m', // Cyan
      usage: '\x1b[34m', // Blue
      error: '\x1b[31m', // Red
      reset: '\x1b[0m'
    }

    // Add wave decoration to headers
    context.decorateHeaderRenderer(async (baseRenderer, ctx) => {
      const output = await baseRenderer(ctx)
      if (!output) return ''

      const waves = '～～～～～'
      return `${colors.header}${waves}\n${output}\n${waves}${colors.reset}`
    })

    // Style usage sections
    context.decorateUsageRenderer(async (baseRenderer, ctx) => {
      const output = await baseRenderer(ctx)
      if (!output) return ''

      return output.replace(/^([A-Z][A-Z\s]+:)$/gm, `${colors.usage}$1${colors.reset}`)
    })

    // Enhance error display
    context.decorateValidationErrorsRenderer(async (baseRenderer, ctx, error) => {
      const output = await baseRenderer(ctx, error)
      if (!output) return ''

      return `${colors.error}⚠️  ERROR\n${output}${colors.reset}`
    })
  }
})
```

### Combining Multiple Rendering Plugins

When using multiple rendering plugins, they execute in the order they are registered.

Each plugin receives the output from the previous one, creating a transformation chain.

Let's create a simple emoji plugin to demonstrate plugin combination:

```js
import { plugin } from 'gunshi/plugin'

// Define a simple emoji plugin using correct decorator API
const emoji = plugin({
  id: 'my:emoji',
  name: 'Emoji Decorator',

  setup(context) {
    // Use the correct decorator method for usage rendering
    context.decorateUsageRenderer(async (baseRenderer, ctx) => {
      const output = await baseRenderer(ctx)
      if (!output) return ''

      // Add emoji indicators to section headers
      return output
        .replace(/^USAGE:/gm, '📖 USAGE:')
        .replace(/^OPTIONS:/gm, '⚙️  OPTIONS:')
        .replace(/^COMMANDS:/gm, '📦 COMMANDS:')
        .replace(/^ARGUMENTS:/gm, '🔤 ARGUMENTS:')
        .replace(/^EXAMPLES:/gm, '💡 EXAMPLES:')
    })
  }
})

// Combine with our ocean theme plugin
await cli(process.argv.slice(2), command, {
  name: 'my-cli',
  plugins: [
    renderer(), // Base renderer
    oceanTheme(), // Apply ocean theme colors
    emoji() // Add emoji indicators
  ]
})
```

#### Understanding the Transformation Chain

Each plugin transforms the output sequentially:

```sh
1. Base renderer output:
   "Usage: my-cli [options]"

2. After oceanThemePlugin:
   "\x1b[38;5;39mUsage: my-cli [options]\x1b[0m"  (colored)

3. After emojiPlugin:
   "📖 \x1b[38;5;39mUsage: my-cli [options]\x1b[0m"  (emoji + colored)
```

> \[!IMPORTANT]
> Plugin order significantly affects the final output. Color plugins should typically come before text modification plugins to ensure ANSI codes don't interfere with pattern matching.

#### Guidelines for Plugin Composition

* **Keep plugins focused**: Each plugin should handle one specific aspect of rendering
* **Consider dependencies**: Some plugins may require others to run first
* **Test combinations**: Verify that your plugins work well together
* **Document requirements**: Clearly state if your plugin expects specific input formats

## Advanced Customization

### Using Colors

You can enhance your custom renderers with colors using libraries like:

* [chalk](https://github.com/chalk/chalk)
* [kleur](https://github.com/lukeed/kleur)
* [picocolors](https://github.com/alexeyraspopov/picocolors)

The following example demonstrates using chalk for colored output:

```js
import { cli } from 'gunshi'
import chalk from 'chalk'

// Custom header renderer with colors
const coloredHeaderRenderer = ctx => {
  const lines = []
  lines.push(chalk.blue('╔═════════════════════════════════════════╗'))
  lines.push(chalk.blue(`║             ${chalk.bold(ctx.env.name.toUpperCase())}                ║`))
  lines.push(chalk.blue('╚═════════════════════════════════════════╝'))

  if (ctx.env.description) {
    lines.push(chalk.white(ctx.env.description))
  }

  if (ctx.env.version) {
    lines.push(chalk.gray(`Version: ${ctx.env.version}`))
  }

  lines.push('')
  return lines.join('\n')
}

// Custom usage renderer with colors
const coloredUsageRenderer = ctx => {
  const lines = []

  lines.push(chalk.yellow.bold('📋 COMMAND USAGE'))
  lines.push(chalk.yellow('═══════════════'))
  lines.push('')

  lines.push(chalk.white.bold('BASIC USAGE:'))
  lines.push(chalk.white(`  $ ${ctx.env.name} [options]`))
  lines.push('')

  if (ctx.args && Object.keys(ctx.args).length > 0) {
    lines.push(chalk.white.bold('OPTIONS:'))

    for (const [key, option] of Object.entries(ctx.args)) {
      const shortFlag = option.short ? chalk.green(`-${option.short}, `) : '    '
      const longFlag = chalk.green(`--${key}`)
      const type = chalk.blue(`[${option.type}]`)
      const required = option.required ? chalk.red(' (required)') : ''

      lines.push(
        `  ${shortFlag}${longFlag.padEnd(15)} ${type.padEnd(10)} ${option.description || key}${required}`
      )
    }

    lines.push('')
  }

  return lines.join('\n')
}

// Run the CLI with colored renderers
await cli(process.argv.slice(2), command, {
  name: 'task-manager',
  version: '1.0.0',
  description: 'A task management utility',
  renderHeader: coloredHeaderRenderer,
  renderUsage: coloredUsageRenderer
})
```

### Working with Command Context

The Command Context object (`ctx`) passed to renderer functions provides access to all information needed to customize your output.

Here are the key property groups and their practical uses:

#### Environment and Metadata

These properties provide information about the CLI and current command:

```js
renderHeader: ctx => {
  // Access CLI-level configuration
  const appName = ctx.env.name // CLI application name
  const version = ctx.env.version // Application version

  // Access command-specific metadata
  const cmdName = ctx.name // Current command name
  const description = ctx.description // Command description

  return `${appName} v${version} - ${cmdName || 'main'}`
}
```

#### Arguments and Values

Access parsed command-line arguments and their values:

```js
renderUsage: ctx => {
  // ctx.args - Command argument schemas
  // ctx.values - Parsed argument values
  // ctx.explicit - Which args were explicitly provided

  const lines = []

  // Show which arguments have default values
  for (const [key, schema] of Object.entries(ctx.args)) {
    const wasProvided = ctx.explicit[key]
    const currentValue = ctx.values[key]

    if (!wasProvided && currentValue !== undefined) {
      lines.push(`  --${key} (default: ${currentValue})`)
    }
  }

  return lines.join('\n')
}
```

#### Positional and Rest Arguments

Handle non-flag arguments:

```js
renderValidationErrors: (ctx, error) => {
  // ctx.positionals - Positional arguments
  // ctx.rest - Arguments after '--' delimiter

  if (ctx.positionals.length > 0) {
    return `Unexpected arguments: ${ctx.positionals.join(', ')}\n${error.message}`
  }

  return error.message
}
```

#### Plugin Extensions

Plugins extend the command context with additional functionality through namespaced extensions.

Each plugin registers its capabilities under a unique plugin ID to prevent conflicts.

When accessing plugin-provided data in custom renderers, you must use the plugin's ID as the namespace key:

```js
import { pluginId as themeId } from '@my/plugin-theme' // Import plugin ID

renderHeader: ctx => {
  // Access plugin extension using its ID as namespace
  const themeExtension = ctx.extensions[themeId]

  // Defensive check for extension availability, if the plugin is optional
  if (themeExtension) {
    return themeExtension.formatHeader(ctx.env.name)
  }

  // Fallback when plugin is not available
  return ctx.env.name
}
```

> \[!TIP]
> For comprehensive guidance on working with plugin extensions including type safety, composition patterns, and troubleshooting, see the [Context Extensions](./context-extensions.md) guide.

For the complete list of available properties and their types, refer to the [CommandContext API reference](../../api/default/interfaces/CommandContext).

### Complete Implementation Example

Here's a comprehensive example of a task manager CLI with fully customized rendering:

```js [cli.js]
import { cli, define } from 'gunshi'

// Custom header renderer
const customHeaderRenderer = ctx => {
  const lines = []
  lines.push('╔═════════════════════════════════════════╗')
  lines.push('║             TASK MANAGER                ║')
  lines.push('╚═════════════════════════════════════════╝')

  if (ctx.env.description) {
    lines.push(ctx.env.description)
  }

  if (ctx.env.version) {
    lines.push(`Version: ${ctx.env.version}`)
  }

  lines.push('')
  return lines.join('\n')
}

// Custom usage renderer
const customUsageRenderer = ctx => {
  const lines = []

  // Add a custom title
  lines.push('📋 COMMAND USAGE')
  lines.push('═══════════════')
  lines.push('')

  // Add basic usage
  lines.push('BASIC USAGE:')
  lines.push(`  $ ${ctx.env.name} [options]`)
  lines.push('')

  // Add options section with custom formatting
  if (ctx.args && Object.keys(ctx.args).length > 0) {
    lines.push('OPTIONS:')

    for (const [key, option] of Object.entries(ctx.args)) {
      const shortFlag = option.short ? `-${option.short}, ` : '    '
      const longFlag = `--${key}`
      const type = `[${option.type}]`

      // Format the option with custom styling
      const formattedOption = `  ${shortFlag}${longFlag.padEnd(15)} ${type.padEnd(10)} ${option.description || key}`
      lines.push(formattedOption)
    }

    lines.push('')
  }

  // Add footer
  lines.push('NOTE: This is a demo application with custom usage formatting.')
  lines.push('For more information, visit: https://github.com/kazupon/gunshi')

  return lines.join('\n')
}

// Custom validation errors renderer
const customValidationErrorsRenderer = (ctx, error) => {
  const lines = []

  lines.push('❌ ERROR:')
  lines.push('═════════')

  for (const err of error.errors) {
    lines.push(`  • ${err.message}`)
  }

  lines.push('')
  lines.push('Please correct the above errors and try again.')
  lines.push(`Run '${ctx.env.name} --help' for usage information.`)

  return lines.join('\n')
}

// Define a command
const command = define({
  name: 'task-manager',
  description: 'A task management utility with custom usage generation',
  args: {
    add: {
      type: 'string',
      short: 'a',
      description: 'Add a new task'
    },
    list: {
      type: 'boolean',
      short: 'l',
      description: 'List all tasks'
    },
    complete: {
      type: 'string',
      short: 'c',
      description: 'Mark a task as complete'
    },
    priority: {
      type: 'string',
      short: 'p',
      description: 'Set task priority (low, medium, high)'
    },
    due: {
      type: 'string',
      short: 'd',
      description: 'Set due date in YYYY-MM-DD format'
    }
  },
  examples: `# Add a new task
$ task-manager --add "Complete the project"

# Add a task with priority and due date
$ task-manager --add "Important meeting" --priority high --due 2023-12-31

# List all tasks
$ task-manager --list

# Mark a task as complete
$ task-manager --complete "Complete the project"`,
  run: ctx => {
    const { add, list, complete, priority, due } = ctx.values

    if (add) {
      console.log(`Adding task: "${add}"`)
      if (priority) console.log(`Priority: ${priority}`)
      if (due) console.log(`Due date: ${due}`)
    } else if (list) {
      console.log('Listing all tasks...')
    } else if (complete) {
      console.log(`Marking task as complete: "${complete}"`)
    } else {
      console.log('No action specified. Run with --help to see usage information.')
    }
  }
})

// Run the command with custom usage generation
await cli(process.argv.slice(2), command, {
  name: 'task-manager',
  version: '1.0.0',
  description: 'A task management utility with custom usage generation',
  // Custom renderers
  renderHeader: customHeaderRenderer,
  renderUsage: customUsageRenderer,
  renderValidationErrors: customValidationErrorsRenderer
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/custom-rendering).

---

---
url: /guide/advanced/internationalization.md
---
# Internationalization

Gunshi provides comprehensive internationalization (i18n) support through the official `@gunshi/plugin-i18n` plugin, allowing you to create command-line interfaces that can be used in multiple languages.

## Why Use Internationalization?

Internationalization offers several benefits:

* **Broader audience**: Make your CLI accessible to users who speak different languages
* **Better user experience**: Users can interact with your CLI in their preferred language
* **Consistency**: Maintain a consistent approach to translations across your application
* **Type safety**: Full TypeScript support for translation keys and interpolation

## Getting Started with i18n Plugin

First, install the i18n plugin and optional resource packages:

```sh
npm install @gunshi/plugin-i18n @gunshi/resources
```

## Basic Internationalization

Here's how to implement basic internationalization using the i18n plugin:

```ts [cli.ts]
import { cli } from 'gunshi'
import resources from '@gunshi/resources'
import i18n, { defineI18nWithTypes, pluginId as i18nId, resolveKey } from '@gunshi/plugin-i18n'

import type { I18nExtension } from '@gunshi/plugin-i18n'

// Define a command with i18n support
const command = defineI18nWithTypes<{ extensions: { [i18nId]: I18nExtension } }>()({
  name: 'greeter',
  args: {
    name: {
      type: 'string',
      short: 'n',
      description: 'Name to greet'
    },
    formal: {
      type: 'boolean',
      short: 'f',
      description: 'Use formal greeting'
    }
  },

  // Define translation resources for the command
  resource: locale => {
    if (locale.toString() === 'ja-JP') {
      return {
        description: '挨拶アプリケーション',
        'arg:name': '挨拶する相手の名前',
        'arg:formal': '丁寧な挨拶を使用する',
        informal_greeting: 'こんにちは',
        formal_greeting: 'はじめまして'
      }
    }

    // Default to English
    return {
      description: 'Greeting application',
      'arg:name': 'Name to greet',
      'arg:formal': 'Use formal greeting',
      informal_greeting: 'Hello',
      formal_greeting: 'Good day'
    }
  },

  // Command execution function
  run: ctx => {
    const { name = 'World', formal } = ctx.values
    const t = ctx.extensions[i18nId].translate

    // Use resolveKey for custom keys with proper namespacing
    const greetingKey = formal
      ? resolveKey('formal_greeting', ctx.name)
      : resolveKey('informal_greeting', ctx.name)

    const greeting = t(greetingKey)
    console.log(`${greeting}, ${name}!`)

    // Show translation information
    const locale = ctx.extensions[i18nId].locale
    console.log(`\nCurrent locale: ${locale}`)

    // Use resolveKey for description as well
    const descKey = resolveKey('description', ctx.name)
    console.log(`Command Description: ${t(descKey)}`)
  }
})

// Run the command with i18n plugin
await cli(process.argv.slice(2), command, {
  name: 'i18n-example',
  version: '1.0.0',
  plugins: [
    i18n({
      // Set locale from environment or default to en-US
      locale: process.env.MY_LANG || 'en-US',
      // Provide built-in translations for common terms.
      // See the support locales: https://github.com/kazupon/gunshi/tree/main/packages/resources#-supported-locales
      builtinResources: resources
    })
  ]
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/internationalization/basic).

> \[!TIP]
> **About the helper functions used in this example:**
>
> * `defineI18nWithTypes`: A type-safe helper for creating commands with i18n support. It ensures proper TypeScript inference for translation keys. [Learn more](#defineI18nWithTypes)
> * `resolveKey`: A utility that handles namespace resolution for custom translation keys in commands and subcommands. Always use this for custom keys to ensure proper namespacing. [Learn more](#resolvekey)

To run this example with different locales:

```sh
# English (default)
node cli.ts --name John

# i18n-example (i18n-example v1.0.0)
#
# Hello, John!
#
# Current locale: en-US
# Command Description: Greeting application

# Japanese
MY_LANG=ja-JP node cli.ts --name 田中 --formal

# i18n-example (i18n-example v1.0.0)
#
# はじめまして, 田中!
#
# Current locale: ja-JP
# Command Description: 挨拶アプリケーション
```

## Using Built-in Resources

The `@gunshi/resources` package provides pre-translated resources for common CLI terms:

```ts
import { cli, define } from 'gunshi'
import i18n from '@gunshi/plugin-i18n'
import resources from '@gunshi/resources'

const command = define({
  name: 'app',
  run: ctx => {
    console.log('Application running')
  }
})

await cli(process.argv.slice(2), command, {
  name: 'my-app',
  version: '1.0.0',
  plugins: [
    i18n({
      locale: 'en-US',
      // Provide built-in translations for common terms.
      // See the support locales: https://github.com/kazupon/gunshi/tree/main/packages/resources#-supported-locales
      builtinResources: resources
    })
  ]
})

// This automatically translates built-in messages like:
// - USAGE, OPTIONS, COMMANDS
// - Help and version descriptions
// - Error messages
```

## Loading Translations from Files

For better organization, load translations from separate files:

```ts [cli.ts]
import i18n, { defineI18nWithTypes, pluginId as i18nId, resolveKey } from '@gunshi/plugin-i18n'
import resources from '@gunshi/resources'
import { cli } from 'gunshi'

import type { I18nExtension } from '@gunshi/plugin-i18n'

const command = defineI18nWithTypes<{ extensions: { [i18nId]: I18nExtension } }>()({
  name: 'greeter',
  args: {
    name: { type: 'string', short: 'n' },
    formal: { type: 'boolean', short: 'f' }
  },

  // Load translations from files
  resource: async locale => {
    if (locale.toString() === 'ja-JP') {
      // Dynamic import for lazy loading
      const jaJP = await import('./locales/ja-JP.json', {
        with: { type: 'json' }
      })
      return jaJP.default
    }

    // Default to English
    const enUS = await import('./locales/en-US.json', {
      with: { type: 'json' }
    })
    return enUS.default
  },

  run: ctx => {
    const { name = 'World', formal } = ctx.values
    const t = ctx.extensions[i18nId].translate

    // Always use resolveKey for custom keys
    const greetingKey = formal
      ? resolveKey('formal_greeting', ctx.name)
      : resolveKey('informal_greeting', ctx.name)

    const greeting = t(greetingKey)
    console.log(`${greeting}, ${name}!`)
  }
})

await cli(process.argv.slice(2), command, {
  name: 'i18n-example',
  version: '1.0.0',
  plugins: [
    i18n({
      locale: process.env.MY_LANG || 'en-US',
      builtinResources: resources
    })
  ]
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/internationalization/loading).

Example locale files:

```json [locales/en-US.json]
{
  "description": "Greeting application",
  "arg:name": "Name to greet",
  "arg:formal": "Use formal greeting",
  "informal_greeting": "Hello",
  "formal_greeting": "Good day"
}
```

```json [locales/ja-JP.json]
{
  "description": "挨拶アプリケーション",
  "arg:name": "挨拶する相手の名前",
  "arg:formal": "丁寧な挨拶を使用する",
  "informal_greeting": "こんにちは",
  "formal_greeting": "はじめまして"
}
```

## Translation with Interpolation

The i18n plugin supports message interpolation for dynamic content:

```ts
import i18n, { defineI18nWithTypes, pluginId as i18nId, resolveKey } from '@gunshi/plugin-i18n'

import type { I18nExtension } from '@gunshi/plugin-i18n'

const command = defineI18nWithTypes<{ extensions: { [i18nId]: I18nExtension } }>()({
  name: 'deploy',
  args: {
    app: { type: 'string', required: true },
    environment: { type: 'string', required: true }
  },
  resource: () => ({
    deploying: 'Deploying {$app} to {$environment}...',
    success: 'Successfully deployed {$app} to {$environment}!',
    error: 'Failed to deploy: {$message}'
  }),
  run: ctx => {
    const t = ctx.extensions[i18nId].translate
    const { app, environment } = ctx.values

    // Use resolveKey for all custom keys
    const deployingKey = resolveKey('deploying', ctx.name)
    const successKey = resolveKey('success', ctx.name)
    const errorKey = resolveKey('error', ctx.name)

    console.log(t(deployingKey, { app, environment }))

    try {
      // Deployment logic
      console.log(t(successKey, { app, environment }))
    } catch (error) {
      console.error(t(errorKey, { message: error.message }))
    }
  }
})
```

Note: Interpolation placeholders use the format `{$variableName}` in the i18n plugin.

## Internationalization with Sub-commands

When working with sub-commands, each command has its own namespace for translations. The `COMMANDS` section of `--help` is localized too: each listed command's description comes from that command's own resource.

```ts [cli.ts]
import i18n, { defineI18nWithTypes, pluginId as i18nId, resolveKey } from '@gunshi/plugin-i18n'
import resources from '@gunshi/resources'
import { cli } from 'gunshi'

import type { I18nExtension } from '@gunshi/plugin-i18n'

// Sub-command with its own translations
const createCommand = defineI18nWithTypes<{ extensions: { [i18nId]: I18nExtension } }>()({
  name: 'create',
  args: {
    name: { type: 'string', required: true }
  },
  resource: locale => {
    return locale.toString() === 'ja-JP'
      ? {
          description: 'リソースを作成',
          'arg:name': 'リソース名',
          creating: '作成中: {$name}',
          success: '作成完了！'
        }
      : {
          description: 'Create a resource',
          'arg:name': 'Resource name',
          creating: 'Creating: {$name}',
          success: 'Created successfully!'
        }
  },
  run: ctx => {
    const t = ctx.extensions[i18nId].translate
    const { name } = ctx.values

    // For custom keys in subcommands, always use resolveKey helper
    const creatingKey = resolveKey('creating', ctx.name)
    const successKey = resolveKey('success', ctx.name)

    console.log(t(creatingKey, { name }))
    console.log(t(successKey))
  }
})

// Main command
const mainCommand = defineI18nWithTypes<{ extensions: { [i18nId]: I18nExtension } }>()({
  name: 'resource-manager',
  resource: () => ({
    description: 'Resource management tool',
    usage_hint: 'Use a sub-command to manage resources'
  }),
  run: ctx => {
    const t = ctx.extensions[i18nId].translate

    // Use resolveKey for main command's custom keys too
    const hintKey = resolveKey('usage_hint', ctx.name)
    console.log(t(hintKey))
  }
})

// Run with i18n plugin
await cli(process.argv.slice(2), mainCommand, {
  name: 'resource-cli',
  version: '1.0.0',
  subCommands: {
    create: createCommand
  },
  plugins: [
    i18n({
      locale: process.env.MY_LANG || 'en-US',
      builtinResources: resources
    })
  ]
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/internationalization/sub-command).

## Helper Functions

The i18n plugin provides helpful utilities for working with translations:

### `defineI18n`

Define an i18n-aware command.

```ts
import { defineI18n } from '@gunshi/plugin-i18n'

const greetCommand = defineI18n({
  name: 'greet',
  description: 'Greet someone',
  args: {
    name: {
      type: 'string',
      description: 'Name to greet'
    }
  },
  resource: locale => {
    switch (locale.toString()) {
      case 'ja-JP': {
        return {
          description: '誰かにあいさつ',
          'arg:name': 'あいさつするための名前'
        }
      }
      // other locales ...
    }
  },
  run: ctx => {
    console.log(`Hello, ${ctx.values.name}!`)
  }
})
```

The difference from the `define` function is that you can define a `resource` option that can load a locale.

### `defineI18nWithTypes`

Define an i18n-aware command with types

This helper function allows specifying the type parameter of `GunshiParams` while inferring the `Args` type, `ExtendContext` type from the definition.

```ts
import { defineI18nWithTypes } from '@gunshi/plugin-i18n'

// Define a command with specific extensions type
type MyExtensions = { logger: { log: (message: string) => void } }

const greetCommand = defineI18nWithTypes<{ extensions: MyExtensions }>()({
  name: 'greet',
  args: {
    name: { type: 'string', description: 'Name to greet' }
  },
  resource: locale => {
    switch (locale.toString()) {
      case 'ja-JP': {
        return {
          description: '誰かにあいさつ',
          'arg:name': 'あいさつするための名前'
        }
      }
      // other locales ...
    }
  },
  run: ctx => {
    // ctx.values is inferred as { name?: string }
    // ctx.extensions is MyExtensions
  }
})
```

### `withI18nResource`

Add i18n resources to existing commands:

```ts
import { define } from 'gunshi'
import { withI18nResource, resolveKey, pluginId as i18nId } from '@gunshi/plugin-i18n'

const existingCommand = define({
  name: 'app',
  run: ctx => {
    const t = ctx.extensions[i18nId]?.translate
    if (t) {
      const messageKey = resolveKey('message', ctx.name)
      console.log(t(messageKey))
    }
  }
})

const existingLocalizableCommand = withI18nResource(existingCommand, locale => ({
  message: 'Hello from i18n!'
}))
```

### `resolveKey`

The `resolveKey` helper ensures proper command namespace handling for custom translation keys:

```ts
import { resolveKey } from '@gunshi/plugin-i18n'

// For a command named 'build'
const key = resolveKey('starting', ctx.name)
// Returns: 'build:starting'
```

## Resource Key Naming Conventions

When defining translation resources, follow these conventions:

* **Command Description**: Use the key `description`
* **Examples**: Use the key `examples`
* **Argument Descriptions**: Prefix with `arg:` (e.g., `arg:name`)
* **Negatable Arguments**: Use `arg:no-<option>` for custom negation descriptions. Without one, the description is composed from the `NEGATABLE` built-in resource of the locale (e.g. `否定可能な -f, --force`), in the help and in shell completion alike
* **Built-in Keys**: Keys like `_:USAGE`, `_:OPTIONS` are handled by built-in resources
* **Custom Keys**: Free naming for your application-specific messages, but always use `resolveKey()` when accessing them

Example:

```js
{
  // Command metadata (accessed with resolveKey)
  "description": "File processor",
  "examples": "$ process --input file.txt",

  // Argument descriptions (must use arg: prefix)
  "arg:input": "Input file path",
  "arg:verbose": "Enable verbose output",
  "arg:no-verbose": "Disable verbose output",

  // Custom application messages (accessed with resolveKey)
  "processing": "Processing file...",
  "complete": "Processing complete!",
  "error_not_found": "File not found: {$path}"
}
```

> \[!IMPORTANT]
> The resource object returned by the `resource` function (or loaded from external files like JSON) **must** be a flat key-value structure. Nested objects are not supported for translations using `translate()`. Keep your translation keys simple and at the top level.

Good Flat structure:

```json
{
  "greeting": "Hello",
  "farewell": "Goodbye"
}
```

Bad Nested structure (won't work with `translate('messages.greeting')`):

```json
{
  "messages": {
    "greeting": "Hello",
    "farewell": "Goodbye"
  }
}
```

## Detecting User Locale

The i18n plugin can automatically detect the user's locale:

```js
import i18n from '@gunshi/plugin-i18n'

// Use various detection methods
await cli(process.argv.slice(2), command, {
  plugins: [
    i18n({
      // From environment variable
      locale: process.env.MY_LANG || 'en-US'
      // Or using Intl.Locale for advanced locale handling
      // locale: new Intl.Locale(process.env.MY_LANG || 'en-US')
    })
  ]
})
```

In Node.js v21 and later, you can also detect locale using the navigator API:

```ts
// In browser or Node.js v21.2.0+ (experimental global navigator), use navigator.language
// Otherwise, fall back to environment- or Intl-based detection
const locale = (() => {
  // Experimental global navigator in Node 21.2.0+
  if (typeof globalThis.navigator !== 'undefined' && navigator.language) {
    return navigator.language
  }
  // Fallback: read locale from environment variables
  const env = process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || 'en-US'
  const base = env.split('.')[0].replace('_', '-')
  try {
    // Normalize and validate with Intl.Locale
    return new Intl.Locale(base).toString()
  } catch {
    return 'en-US'
  }
})()
```

## Custom Translation Adapters

For advanced scenarios requiring custom interpolation syntax or translation logic, you can create custom translation adapters by implementing the TranslationAdapter interface.

This allows full control over how translations are stored, retrieved, and interpolated.

For detailed implementation guidance and examples, see the [Custom Translation Adapter documentation](https://github.com/kazupon/gunshi/tree/main/packages/plugin-i18n#-custom-translation-adapter) in the `@gunshi/plugin-i18n` package.

## Translating Help Messages

The i18n plugin automatically uses your translations for help messages.

When users run `--help` with different locales, they'll see help messages in their language:

English:

```sh
USAGE:
  COMMAND <OPTIONS>

OPTIONS:
  -n, --name <name>      Name to greet
  -f, --formal           Use formal greeting
  -h, --help             Display this help message
  -v, --version          Display version
```

Japanese (with proper locale):

```sh
使用法:
  COMMAND <オプション>

オプション:
  -n, --name <name>     挨拶する相手の名前
  -f, --formal          丁寧な挨拶を使用する
  -h, --help            このヘルプメッセージを表示
  -v, --version         バージョンを表示
```

## Important Notes on Custom Keys

> \[!IMPORTANT]
> **Always use `resolveKey()` for custom translation keys!** This ensures proper namespace handling, especially in sub-commands. Without `resolveKey()`, your translations may not be found.

```ts
// ❌ Wrong - Don't access custom keys directly
const message = t('welcome')

// ✅ Correct - Always use resolveKey for custom keys
const welcomeKey = resolveKey('welcome', ctx.name)
const message = t(welcomeKey)
```

## Migration from v0.26

If you're migrating from Gunshi v0.26 where i18n was built into the CLI options, see the [v0.27 Release Notes](../../release/v0.27.md#internationalization-migration) for detailed migration instructions.

---

---
url: /guide/advanced/ai-agent-detection.md
---
# AI Agent Detection

`gunshi/agent` provides a minimal utility, `getAgentProfile()`, that lets your CLI adjust its UX when running on an AI coding agent (Claude Code, Cursor, Codex, Replit, etc.). It does **not** change Gunshi's behavior automatically. The detection result is a *hint* that your command, plugin, or renderer can opt into.

The `gunshi/agent` entry point and its profile shape are stable. Detection itself is delegated to [`std-env`](https://github.com/unjs/std-env), so recognized agent names and detection rules may evolve independently as the upstream detector is updated.

## Why a separate utility?

AI coding agents typically benefit from terser, machine-friendly CLI output, while human users expect rich, interactive output. `getAgentProfile()` gives you a single switch you can branch on, without spreading environment variable checks across your code.

`gunshi/agent` is intentionally small:

* it does **not** re-export `std-env`'s API
* it does **not** alter Gunshi core behavior
* it is **not** a security boundary — environment variables can be spoofed

## Installation

`gunshi/agent` ships with the `gunshi` package — no extra install is required.

```sh
npm install gunshi
```

## API

### `getAgentProfile()`

The only public export.

```ts
import { getAgentProfile } from 'gunshi/agent'

const profile = getAgentProfile()

if (profile.isAgent) {
  // adjust output for AI agent execution
}
```

The returned profile has just two fields:

```ts
interface AgentProfile {
  isAgent: boolean
  name?: string // detected agent name (when known)
}
```

To get the type without exposing the internal `AgentProfile` interface, use `ReturnType`:

```ts
import { getAgentProfile } from 'gunshi/agent'

type AgentProfile = ReturnType<typeof getAgentProfile>
```

## What the detection result means

The returned profile is not an operating-system signal or proof of who invoked the command. It is a normalized runtime hint derived from the environment by `std-env`. In this guide, "running on an AI coding agent" means that the current process appears to have been launched by, or inherited its environment from, a recognized agent.

Detection can produce false positives or false negatives. Environment variables can be set manually, inherited by unrelated child processes, or omitted by an unknown agent. Do not use the profile for authentication, authorization, sandbox decisions, or any other security boundary.

The profile also does not describe the agent's capabilities. In particular, `isAgent: true` does not guarantee that the caller requires JSON, cannot process colors, or cannot answer a prompt. Treat it as a default-selection hint that explicit CLI options and application configuration can override.

## Supported agents

Detection is delegated to [`std-env`](https://github.com/unjs/std-env), which recognizes agents such as Claude Code, Cursor, Codex, and others. Refer to the upstream documentation for the authoritative detector list and detection rules. New agent names may be added without changing the stable `gunshi/agent` API.

If a specific agent must behave differently, read the value at runtime via `getAgentProfile().name` rather than hard-coding environment variable checks.

### `AI_AGENT` override

As part of its upstream API, `std-env` honors an `AI_AGENT` environment variable as an explicit override:

```sh
AI_AGENT=codex my-cli ...
```

This is useful for testing agent-aware behavior locally, or for declaring a custom agent name. Gunshi does not define or parse this variable itself; it passes the name reported by `std-env` through verbatim without normalizing it.

```ts
// AI_AGENT=my-agent
getAgentProfile()
// → { isAgent: true, name: 'my-agent' }
```

## Turn detection into behavior

Detection is useful when it changes an observable CLI behavior. Common agent-friendly choices include:

* Emit deterministic, machine-readable output with a documented schema.
* Require all necessary values as arguments instead of opening a hidden interactive prompt.
* Keep successful and failed outcomes distinguishable through stable result fields and exit statuses.
* Avoid ANSI colors and terminal-only decoration in machine-readable output.

Gunshi does not apply these policies automatically. Commands and plugins decide which adaptations are appropriate for their CLI. Prefer explicit options such as `--json` or `--no-interactive` when your CLI exposes them, and use agent detection only to choose their defaults.

## Using it in a command

This command requires `--target`, so an agent cannot be left waiting for an implicit prompt. When an agent is detected, the command emits a stable JSON object with an explicit status instead of human-oriented prose.

`ctx.log` is silenced when `usageSilent` is set, so results that an agent or a script must still see go through `console.log`:

```ts
import { define } from 'gunshi'
import { getAgentProfile } from 'gunshi/agent'

export default define({
  name: 'deploy',
  args: {
    target: { type: 'string', required: true }
  },
  run: ctx => {
    const profile = getAgentProfile()

    if (profile.isAgent) {
      // results must still appear when `usageSilent` is set; `ctx.log` would not
      console.log(
        JSON.stringify({
          status: 'success',
          target: ctx.values.target
        })
      )
      return
    }

    console.log(`Deployed to ${ctx.values.target}`)
  }
})
```

Keep the JSON shape stable once consumers depend on it. Do not catch and discard command failures; map them to documented non-zero exit statuses in your runtime entry point so agents, scripts, and people receive the same unambiguous result.

## Using it in a plugin

`gunshi/agent` itself is not a plugin, but you can build one on top of it.

```ts
import { plugin } from 'gunshi/plugin'
import { getAgentProfile } from 'gunshi/agent'

export default function agentAwareRenderer() {
  return plugin({
    id: 'g:agent-aware-renderer',
    setup: ctx => {
      const profile = getAgentProfile()

      if (!profile.isAgent) {
        return
      }

      ctx.decorateUsageRenderer(async base => {
        const rendered = await base()
        // for example, drop ANSI colors and decorations for agent output
        return rendered.replaceAll(/\u001B\[[0-9;]*m/g, '')
      })
    }
  })
}
```

## Branching strategy

Prefer the broad `isAgent` flag over agent-specific names:

```ts
// ✅ Recommended
if (profile.isAgent) {
  emitJson()
}

// ⚠️ Avoid unless you have a known agent-specific constraint
if (profile.name === 'codex' || profile.name === 'claude') {
  emitJson()
}
```

Agent-specific branches are appropriate only when you need to work around a known constraint of a specific agent (for example, an output limit or a missing TTY feature). Otherwise, `isAgent` keeps your code agnostic of the upstream detector list.

## Why Gunshi does not change output automatically

`getAgentProfile()` is a hint. Gunshi's core does not switch usage / validation error / prompt rendering on its own, even when an agent is detected. There are several reasons:

1. **Spoofable**: Agent detection relies on environment variables and is not a security signal.
2. **App-specific**: The "right" agent-friendly output differs per CLI (JSON, NDJSON, plain text, etc.).
3. **Backward compatibility**: Existing CLIs should not silently change their output when run under an agent.
4. **Explicit opt-in**: Renderers, commands, and plugins can opt into agent-aware behavior where it actually matters.

If you need a richer integration (custom renderer decoration, a `--json` flag, etc.), build it on top of `getAgentProfile()` in a plugin. A first-party `@gunshi/plugin-agent` may be added in the future once the desired shape is clearer.

## Need the raw `std-env` API?

`gunshi/agent` only exposes `getAgentProfile()`. If you need `agentInfo`, `detectAgent()`, `agent`, or `isAgent` directly, install `std-env` and import from it explicitly:

```sh
npm install std-env
```

```ts
import { agent, agentInfo, detectAgent, isAgent } from 'std-env'
```

This keeps `gunshi/agent`'s API surface small and stable, while letting power users reach for the underlying detector.

---

---
url: /guide/advanced/docs-gen.md
---
# Documentation Generation

Gunshi provides a powerful feature for automatically generating documentation for your CLI applications.

This guide explains how to use the `generate` function to generate documentation programmatically.

## Using the `generate` Function

The following example demonstrates how to use the `generate` function to programmatically capture usage information for a command and save it to a documentation file:

```ts [cli.ts]
import { define } from 'gunshi'
import { generate } from 'gunshi/generator'
import { promises as fs } from 'node:fs'

import type { Command } from 'gunshi'

// Define your command
const command = define({
  name: 'my-command',
  description: 'A sample command',
  args: {
    input: {
      type: 'string',
      short: 'i',
      description: 'Input file'
    },
    output: {
      type: 'string',
      short: 'o',
      description: 'Output file'
    }
  }
  // ... and define `run`
})

// Generate documentation
async function main() {
  // Generate the usage information
  const usageText: string = await generate(null, command, {
    name: 'my-cli',
    version: '1.0.0',
    description: 'My CLI tool'
  })

  // Now you can use the usage text to generate documentation
  await fs.writeFile('docs/cli-usage.md', `# CLI Usage\n\n\`\`\`sh\n${usageText}\n\`\`\``, 'utf8')

  console.log('Documentation generated successfully!')
}

// Generate!
await main()
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/docs-gen/basic).

The `generate` function programmatically captures usage information for your CLI commands and returns it as a string.

This allows you to generate documentation files, create API documentation, or integrate usage information into your build process.

Unlike the `cli` function which executes commands and prints output to the console, `generate` is designed specifically for documentation generation:

* **Silent Mode**: Internally sets `usageSilent: true` to capture output as a string rather than printing to console. When this flag is set, the internal `ctx.log` function is replaced with a no-op function, preventing console output while still returning the generated usage text
* **No Execution**: Only generates usage text without running command logic. The usage is not asked for through an option, so a command may name its arguments whatever it likes and still be documented: one that declares an argument of its own named `help` or `version` gets a usage all the same, and that usage lists the argument the command declares rather than the global option it replaces
* **Return Value**: Returns the generated usage text as a string (or empty string if generation fails)

The `generate` function takes three parameters:

* `command` (string | null): The sub-command name to generate documentation for. Pass `null` when generating documentation for the entry command or when you don't have sub-commands
* `entry` (Command | LazyCommand): The command object containing the command definition, or a lazy command that will be loaded to get the command
* `opts` (CliOptions): Optional configuration including:
  * `name`: The CLI program name
  * `version`: Version string to display
  * `description`: Program description
  * `subCommands`: Map of sub-commands (if applicable)
  * `renderHeader`, `renderUsage`: Custom renderer functions
  * **Note**: The `usageSilent` option is automatically set to `true` internally, so any value you provide will be overridden

Returns a Promise that resolves to the generated usage text as a string.

If no usage is generated (e.g., when renderUsage is not defined), returns an empty string.

## Generating Documentation for Multiple Commands

When your CLI has sub-commands, you can iterate through them to generate comprehensive documentation.

Here's how to generate documentation for each command separately:

```ts [cli.ts]
import { define } from 'gunshi'
import { generate } from 'gunshi/generator'
import { promises as fs } from 'node:fs'

import type { Command, CliOptions } from 'gunshi'

// Define your commands
const createCommand = define({
  name: 'create',
  description: 'Create a new resource',
  args: {
    name: {
      type: 'string',
      short: 'n',
      required: true,
      description: 'Name of the resource'
    }
  }
  // ... and define `run`
})

const listCommand = define({
  name: 'list',
  description: 'List all resources',
  args: {
    format: {
      type: 'string',
      short: 'f',
      description: 'Output format (json, table)'
    }
  }
  // ... and define `run`
})

// Create a Map of sub-commands
const subCommands = {
  create: createCommand,
  list: listCommand
}

// Define the main command
const mainCommand = define({
  name: 'manage',
  description: 'Manage resources'
  // ... and define `run`
})

// Generate documentation for all commands
async function main() {
  const cliOptions: CliOptions = {
    name: 'my-cli',
    version: '1.0.0',
    description: 'My CLI tool',
    subCommands
  }

  // Generate main help
  const mainUsage = await generate(null, mainCommand, cliOptions)
  await fs.writeFile('docs/cli-main.md', `# CLI Usage\n\n\`\`\`sh\n${mainUsage}\n\`\`\``, 'utf8')

  // Generate help for each sub-command
  for (const name of Object.keys(subCommands)) {
    const commandUsage = await generate(name, mainCommand, cliOptions)
    await fs.writeFile(
      `docs/cli-${name}.md`,
      `# ${name.charAt(0).toUpperCase() + name.slice(1)} Command\n\n\`\`\`sh\n${commandUsage}\n\`\`\``,
      'utf8'
    )
  }

  console.log('All documentation generated successfully!')
}

// Generate!
await main()
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/docs-gen/sub-command).

## Creating Rich Documentation

You can combine the generated usage information with additional content to create rich documentation:

```ts
import { define } from 'gunshi'
import { generate } from 'gunshi/generator'
import { promises as fs } from 'node:fs'

// Generate rich documentation
async function main() {
  const command = define({
    name: 'data-processor',
    description: 'Process data files',
    args: {
      input: {
        type: 'string',
        short: 'i',
        required: true,
        description: 'Input file path'
      },
      format: {
        type: 'string',
        short: 'f',
        description: 'Output format (json, csv, xml)'
      },
      output: {
        type: 'string',
        short: 'o',
        description: 'Output file path'
      }
    }
    // ... and define `run`
  })

  // Generate the usage information
  const usageText = await generate(null, command, {
    name: 'data-processor',
    version: '1.0.0',
    description: 'A data processing utility'
  })

  // Create rich documentation
  const documentation = `
# Data Processor CLI

A command-line utility for processing data files in various formats.

## Installation

\`\`\`sh
npm install -g data-processor
\`\`\`

## Usage

\`\`\`sh
${usageText}
\`\`\`

## Examples

### Convert a CSV file to JSON

\`\`\`sh
data-processor --input data.csv --format json --output data.json
\`\`\`

### Process a file and print to stdout

\`\`\`sh
data-processor --input data.csv
\`\`\`

## Advanced Usage

For more complex scenarios, you can:

1. Chain commands with pipes
2. Use glob patterns for batch processing
3. Configure processing with a config file

## API Reference

The CLI is built on top of the data-processor library, which you can also use programmatically.
  `

  await fs.writeFile('docs/data-processor.md', documentation, 'utf8')
  console.log('Rich documentation generated successfully!')
}

// Generate!
await main()
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/docs-gen/rich).

## Automating Documentation Generation

You can automate documentation generation as part of your build process:

> \[!NOTE]
> The following example uses Node.js-specific `__dirname` approach. For cross-runtime compatibility:
>
> * **Deno**: Use `import.meta.dirname` or `fromFileUrl(import.meta.url)`
> * **Bun**: Use `import.meta.dir` or Node.js-compatible approach

```ts [scripts/generate-docs.ts]
import { generate } from 'gunshi/generator'
import { promises as fs } from 'node:fs'
import { fileURLToPath } from 'node:url'
import path from 'node:path'

import type { Command, CliOptions } from 'gunshi'

// Get the directory of the current module
const __dirname = path.dirname(fileURLToPath(import.meta.url))
const rootDir = path.resolve(__dirname, '..')
const docsDir = path.join(rootDir, 'docs')

// Import your commands
import { mainCommand, subCommands } from '../src/commands.ts'

async function main() {
  const cliOptions: CliOptions = {
    name: 'my-cli',
    version: '1.0.0',
    description: 'My CLI tool',
    subCommands
  }

  // Generate main help
  const mainUsage = await generate(null, mainCommand, cliOptions)

  // Create the CLI reference page
  const cliReference = `# CLI Reference

## Main Command

\`\`\`sh
${mainUsage}
\`\`\`

## Sub-commands

`

  // Add each sub-command
  let fullReference = cliReference
  for (const name of Object.keys(subCommands)) {
    const commandUsage = await generate(name, mainCommand, cliOptions)
    fullReference += `### ${name.charAt(0).toUpperCase() + name.slice(1)}

\`\`\`sh
${commandUsage}
\`\`\`

`
  }

  // Write the documentation
  await fs.writeFile(path.join(docsDir, 'cli-reference.md'), fullReference, 'utf8')
  console.log('Documentation generated successfully!')
}

// Generate!
await main()
```

Then add a script to your `package.json`:

```json [package.json]
{
  "scripts": {
    "docs:generate": "tsx scripts/generate-docs.ts",
    "docs:build": "npm run docs:generate && vitepress build docs"
  }
}
```

## Generating Unix Man Pages

Unix man pages (short for "manual pages") are a traditional form of documentation for command-line tools on Unix-like operating systems.

You can use Gunshi's `generate` function to generate man pages for your CLI applications.

### Introduction to Man Pages

Man pages are the standard documentation format for Unix and Unix-like systems.

They provide comprehensive documentation directly accessible from the command line using the `man` command.

Man pages follow a specific structure with numbered sections (1 for user commands, 2 for system calls, etc.) and standardized formatting conventions.

The most common format for man pages is roff (runoff), though modern tools allow you to write documentation in simpler formats like Markdown and convert them to roff.

### Generating Man Pages with Gunshi

The following example demonstrates how to generate Unix man page documentation using Gunshi's `generate` function with a custom renderer.

The custom renderer (`renderManPageUsage`) creates markdown output that can be converted to the man page format (roff) using tools like `marked-man`.

The renderer function structures the output according to standard man page sections:

* **NAME**: Command name and brief description
* **SYNOPSIS**: Command syntax overview
* **DESCRIPTION**: Detailed command description
* **OPTIONS**: Available command-line options with descriptions
* **EXAMPLES**: Usage examples (references the command's help)
* **AUTHOR**: Author information
* **SEE ALSO**: Related documentation and resources

This approach allows you to maintain man pages alongside your CLI code, ensuring they stay synchronized:

```ts [cli.ts]
import { define } from 'gunshi'
import { generate } from 'gunshi/generator'
import { execFileSync } from 'node:child_process'
import { promises as fs } from 'node:fs'
import path from 'node:path'

import type { CommandContext } from 'gunshi'

// Define custom usage renderer that outputs markdown convertible to man page format (roff) using marked-man
function renderManPageUsage(ctx: CommandContext) {
  const lines: string[] = []

  // NAME
  lines.push(`# ${ctx.name}(1) -- ${ctx.description || 'CLI tool'}`, '')

  // SYNOPSIS
  lines.push('## SYNOPSIS')
  lines.push(`${ctx.env.name} <OPTIONS>`, '')

  // DESCRIPTION
  lines.push('## DESCRIPTION')
  lines.push(ctx.description || '', '')

  // OPTIONS
  lines.push('## OPTIONS')
  for (const [name, schema] of Object.entries(ctx.args)) {
    const options = [`\`--${name}\``]
    if (schema.short) {
      options.unshift(`\`-${schema.short}\``)
    }
    let value = ''
    if (schema.type !== 'boolean') {
      value = schema.default ? `[${name}]` : `<${name}>`
    }
    lines.push(`- ${options.join(', ')}${value ? ` ${value}` : ''}`)
    lines.push(`  ${schema.description || ''}`)
    lines.push('')
  }

  // EXAMPLES
  lines.push('## EXAMPLES')
  lines.push('See command `--help` for examples', '')

  // AUTHOR
  lines.push('## AUTHOR')
  lines.push('Created by yours', '')

  // SEE ALSO
  lines.push('## SEE ALSO')
  lines.push('- man: `man my-tool`', '')
  lines.push('- website: https://my-tools.com/references/cli', '')
  lines.push('- repository: https://github.com/your-username/my-tool', '')

  return Promise.resolve(lines.join('\n'))
}

async function main() {
  const command = define({
    name: 'my-tool',
    description: 'A utility for processing data',
    args: {
      input: {
        type: 'string',
        short: 'i',
        required: true,
        description: 'Input file path'
      },
      output: {
        type: 'string',
        short: 'o',
        description: 'Output file path (defaults to stdout)'
      },
      format: {
        type: 'string',
        short: 'f',
        description: 'Output format (json, yaml, xml)'
      },
      verbose: {
        type: 'boolean',
        short: 'V',
        description: 'Enable verbose output'
      }
    },
    examples: `1. Process a file and output to stdout
$ my-tool --input data.csv

2. Process a file and save to a specific format
$ my-tool --input data.csv --output result.yaml --format yaml

3. Enable verbose output
$ my-tool --input data.csv --verbose`
    // ... and define `run`
  })

  // Generate the usage with custom renderer
  const usageText = await generate(null, command, {
    name: 'my-tool',
    version: '1.0.0',
    description: 'A utility for processing data',
    renderHeader: null, // no display header on console
    renderUsage: renderManPageUsage // set custom usage renderer
  })

  // Prerequisites: Install marked-man for converting markdown to man page format
  // npm install -g marked-man
  // or add it to your project: npm install --save-dev marked-man

  // Write the markdown file
  const mdFile = path.join(process.cwd(), 'my-tool.1.md')
  await fs.writeFile(mdFile, usageText, 'utf8')

  // Convert markdown to man page format using marked-man
  try {
    execFileSync('marked-man', ['--input', mdFile, '--output', 'my-tool.1'])
    console.log('Man page generated successfully: my-tool.1')
  } catch (error) {
    console.error('Error generating man page:', (error as Error).message)
    console.log('Make sure marked-man is installed: npm install -g marked-man')
  }
}

// Generate!
await main()
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/docs-gen/man)

### Installing Man Pages

Once you've generated a man page, you can install it on Unix-like systems:

1. **Local installation** (for development):

   ```sh
   # Copy to your local man pages directory
   cp my-tool.1 ~/.local/share/man/man1/
   # Update the man database
   mandb
   ```

2. **System-wide installation** (for packages):

   ```sh
   # Copy to the system man pages directory (requires sudo)
   sudo cp my-tool.1 /usr/local/share/man/man1/
   # Update the man database
   sudo mandb
   ```

3. **Package installation** (for npm packages):
   Add this to your `package.json`:
   ```json [package.json]
   {
     "man": ["./man/my-tool.1"]
   }
   ```

### Viewing Man Pages

After installation, users can view your man page using:

```sh
man my-tool
```

With the man page generation complete, let's look at broader guidelines for maintaining and generating documentation effectively.

## Documentation Generation Guidelines

When working with Gunshi's documentation generation features, consider these important guidelines:

### Keeping Documentation Current

Automating documentation generation as part of your build process ensures that your documentation stays synchronized with your code. This approach prevents documentation drift and maintains consistency across your project.

### Enhancing Generated Content

The auto-generated usage information provides a solid foundation, but combining it with hand-written examples and detailed explanations creates more valuable documentation. Consider adding context-specific examples that demonstrate real-world use cases.

### Leveraging Custom Renderers

For projects requiring specific documentation formats or styling, custom renderers provide fine-grained control over the output. See [Custom Rendering](./custom-rendering.md) for implementation details.

### Documentation Testing

Including documentation tests in your test suite verifies that the generated documentation accurately reflects your CLI's behavior. This practice helps catch discrepancies between implementation and documentation early in the development process.

---

---
url: /guide/advanced/advanced-lazy-loading.md
---
# Advanced Lazy Loading and Sub-Commands

This guide explores advanced patterns for implementing lazy loading with sub-commands in Gunshi, based on real-world implementations like [pnpmc](https://github.com/kazupon/pnpmc).

## Why Use Advanced Lazy Loading?

While Gunshi's basic lazy loading (covered in [Lazy & Async](../essentials/lazy-async.md)) is powerful, large CLI applications with many sub-commands can benefit from more advanced patterns:

* **Modular Organization**: Separate commands into independent packages or modules
* **On-Demand Loading**: Load command implementations only when explicitly invoked
* **Reduced Memory Footprint**: Minimize memory usage by loading only what's needed
* **Faster Startup**: Improve CLI startup time by deferring command loading
* **Better Maintainability**: Isolate command implementations for easier maintenance

## Real-World Example: pnpmc Pattern

The [pnpmc](https://github.com/kazupon/pnpmc) project (PNPM Catalogs Tooling) demonstrates an effective pattern for organizing a CLI with lazy-loaded sub-commands:

1. **Bundled Metadata, Lazy-Loaded Implementations**:
   * Command metadata (name, description, arguments) is imported directly and bundled with the main CLI package
   * Only the command runners (implementations) are lazy-loaded when executed
   * This allows displaying help information for all commands without loading implementations

2. **Modular Package Structure**:
   * Command metadata is exposed from separate packages via `meta.js` files and imported directly
   * Command implementations are in separate packages and loaded on-demand
   * This separation enables showing usage via `--help` without loading all command code

3. **Custom Loader Implementation**:
   * A custom loader dynamically imports only the command runners when needed
   * Error handling for module resolution failures

Let's explore how to implement this pattern in your own CLI applications.

## Implementation Pattern

### 1. Project Structure

For a CLI with multiple sub-commands, consider organizing your code like this:

```sh
my-cli/
├── packages/
│   ├── cli/                 # Main CLI package
│   │   ├── src/
│   │   │   ├── commands.ts  # Command definitions
│   │   │   ├── loader.ts    # Custom loader
│   │   │   └── cli.ts       # CLI entry point
│   ├── command-a/           # Command A package
│   │   ├── src/
│   │   │   ├── meta.ts      # Command metadata
│   │   │   └── runner.ts    # Command implementation
│   └── command-b/           # Command B package
│       ├── src/
│       │   ├── meta.ts      # Command metadata
│       │   └── runner.ts    # Command implementation
```

### 2. Command Metadata

Define command metadata in a separate file (e.g., `meta.ts`):

```ts [packages/command-a/src/meta.ts]
import { define } from 'gunshi'

export default define({
  name: 'command-a',
  description: 'Performs action A',
  args: {
    input: {
      type: 'string',
      short: 'i',
      description: 'Input file'
    },
    output: {
      type: 'string',
      short: 'o',
      description: 'Output file'
    }
  }
})
```

### 3. Command Implementation

Implement the command in a separate file (e.g., `runner.ts`):

```ts [packages/command-a/src/ruuner.ts]
import meta from './meta.ts'
import type { CommandRunner } from 'gunshi'

export const run: CommandRunner<{ args: typeof meta.args }> = async ctx => {
  const { input, output } = ctx.values
  console.log(`Processing ${input} to ${output}`)
  // Command implementation...
}
```

### 4. Custom Loader

Create a custom loader to dynamically import command implementations:

```ts [packages/cli/src/loader.ts]
import type { CommandRunner, GunshiParamsConstraint } from 'gunshi'

export async function load<G extends GunshiParamsConstraint>(
  pkg: string
): Promise<CommandRunner<G> | null> {
  let mod: Promise<CommandRunner<G> | null> | undefined
  // Dynamic import of the command package
  try {
    mod = await import(pkg).then(m => m.default || m)
  } catch (error: unknown) {
    // Handle module not found errors
    if (isErrorModuleNotFound(error)) {
      mod = Promise.resolve(null)
    }
  }
  if (mod === undefined) {
    throw new Error(`Fatal Error: '${pkg}' Command Runner loading failed`)
  }
  return mod
}

function isErrorModuleNotFound(e: unknown): e is NodeJS.ErrnoException {
  return (
    e instanceof Error &&
    'code' in e &&
    typeof e.code === 'string' &&
    e.code === 'ERR_MODULE_NOT_FOUND'
  )
}
```

### 5. Command Definitions

Define your commands using Gunshi's `lazy` function and your custom loader:

```ts [packages/cli/src/commands.ts]
import { lazy } from 'gunshi'
import { load } from './loader.ts'

// Import command metadata directly - these are bundled with your CLI
import metaCommandA from 'command-a/meta'
import metaCommandB from 'command-b/meta'

// Create lazy-loaded commands
// Note: Only the implementation (runner) is lazy-loaded, not the metadata
export const commandALazy = lazy(
  // This function is only called when the command is executed
  async () => await load('command-a'),
  // Metadata is provided directly and available immediately
  metaCommandA
)

export const commandBLazy = lazy(async () => await load('command-b'), metaCommandB)
```

This approach ensures that:

1. Command metadata is immediately available for generating help text
2. Command implementations are only loaded when the command is actually executed

### 6. CLI Entry Point

Set up your CLI entry point to use the lazy-loaded commands:

```ts [packages/cli/src/cli.ts]
import { cli } from 'gunshi'
import { commandALazy, commandBLazy } from './commands.ts'

async function main() {
  // Load package.json for version info
  const { default: pkgJsonModule } = await import('./package.json', { with: { type: 'json' } })

  // Run the CLI with lazy-loaded commands
  await cli(process.argv.slice(2), commandALazy, {
    name: 'my-cli',
    version: pkgJson.version,
    description: 'My CLI application',
    subCommands: {
      [commandALazy.commandName]: commandALazy,
      [commandBLazy.commandName]: commandBLazy
    }
  })
}

await main()
```

## Advanced Techniques

### On-Demand Sub-Command Loading

For CLIs with many sub-commands, you can implement on-demand sub-command loading:

```ts [packages/cli/src/commands.ts]
import { lazy } from 'gunshi/definition'
import { load } from './loader.ts'

// Function to create a lazy command
function createLazyCommand(name: string) {
  return lazy(
    async () => {
      // Dynamically import metadata and implementation
      const meta = await import(`${name}/meta`).then(m => m.default || m)
      return await load(name)
    },
    { name } // Minimal metadata, rest will be loaded on demand
  )
}

// Create commands map with factory function
export const commands = new Map([
  ['command-a', createLazyCommand('command-a')],
  ['command-b', createLazyCommand('command-b')]
  // Add more commands as needed
])
```

### Package Manager Integration

For CLI tools that integrate with package managers (like pnpmc does with pnpm), you can enhance your loader:

```ts [packages/cli/src/loader.ts]
import { detect, resolveCommand } from 'package-manager-detector'
import { x } from 'tinyexec'
import type { CommandContext, CommandRunner, GunshiParamsConstraint } from 'gunshi'

export async function load<G extends GunshiParamsConstraint>(
  pkg: string
): Promise<CommandRunner<G>> {
  // Detect package manager (npm, yarn, pnpm, etc.)
  const pm = await detect()
  if (pm === null) {
    throw new Error('Fatal Error: Cannot detect package manager')
  }

  // Return a command runner function
  async function runner<G extends GunshiParamsConstraint>(ctx: CommandContext<G>): Promise<void> {
    // Construct the sub-command
    const subCommand = ctx.env.version ? `${pkg}@${ctx.env.version}` : pkg

    // Resolve the command using the package manager
    const resolvedCommand = resolveCommand(pm.agent, 'execute', [subCommand, ...ctx._.slice(1)])
    if (resolvedCommand === null) {
      throw new Error(`Fatal Error: Cannot resolve command '${ctx._[0]}'`)
    }

    // Execute the command
    await x(resolvedCommand.command, resolvedCommand.args, {
      nodeOptions: {
        cwd: ctx.env.cwd,
        stdio: 'inherit',
        env: Object.assign({}, process.env, { CLI_LOADER: 'true' })
      }
    })
  }

  return runner
}
```

When an option appears before a lazy command name or between nested command names, include its
routing metadata in the lazy definition. Gunshi uses only `type`, `short`, `negatable`, and `toKebab`
while selecting a path, then loads the selected command and performs normal value conversion once.
Place loader-only options after the command name. If loading changes the interpretation of a leading
option, Gunshi reports a lazy schema-mismatch error and does not retry another command.

## Performance Considerations

When implementing advanced lazy loading, consider these performance optimizations:

1. **Metadata Size**: Keep command metadata small since it's bundled with your CLI
2. **Metadata/Implementation Separation**: Clearly separate what's needed for help text vs. execution
3. **Dependency Management**: Keep implementation dependencies isolated to each command package
4. **Caching**: Cache loaded command implementations to avoid repeated imports
5. **Error Handling**: Implement robust error handling for implementation loading failures
6. **Startup Time**: Measure and optimize CLI startup time by minimizing what's loaded initially

## Type Safety

Maintain type safety with TypeScript when implementing advanced lazy loading:

```ts [packages/cli/src/commands.ts]
import { define, lazyWithTypes } from 'gunshi/definition'
import { load } from './loader.ts'
import type { CommandRunner } from 'gunshi'

// Define command metadata with type safety
const metaCommandA = define({
  name: 'command-a',
  description: 'Performs action A',
  args: {
    input: {
      type: 'string',
      short: 'i',
      description: 'Input file'
    }
  }
})

// Create type-safe lazy command
const commandALazy = lazyWithTypes<{ args: typeof metaCommandA.args }>()(
  async () => await load('command-a'),
  metaCommandA
)
```

## Conclusion

Advanced lazy loading with sub-commands allows you to build scalable, maintainable CLI applications with optimal performance. By bundling command metadata with your main CLI while lazy-loading command implementations, you can create complex CLIs that:

1. Start up quickly with minimal initial loading
2. Display comprehensive help information for all commands
3. Only load command implementations when they're actually executed

The pattern demonstrated by pnpmc provides a solid foundation for organizing your CLI code, which you can adapt and extend to meet your specific requirements.

---

---
url: /guide/advanced/nested-sub-commands.md
---
# Nested Sub-Commands

Gunshi supports nested sub-commands, allowing you to build hierarchical command trees similar to tools like Git (`git remote add`) or Docker (`docker container ls`).

## Why Use Nested Sub-Commands?

Nested sub-commands are useful when your CLI has command groups with related operations:

* **Organization**: Group related operations under a parent command (e.g., `remote add`, `remote remove`)
* **Discoverability**: Users can explore available operations at each level with `--help`
* **Scalability**: Add new nested commands without cluttering the top-level command list

## Basic Nested Sub-Commands

You can nest sub-commands by adding a `subCommands` property to any command definition:

```ts [cli.ts]
import { cli, define } from 'gunshi'

// Define leaf commands
const addCommand = define({
  name: 'add',
  description: 'Add a remote',
  args: {
    url: { type: 'string', required: true, description: 'Remote URL' }
  },
  run: ctx => {
    console.log(`Adding remote: ${ctx.values.url}`)
  }
})

const removeCommand = define({
  name: 'remove',
  description: 'Remove a remote',
  args: {
    name: { type: 'positional', description: 'Remote name' }
  },
  run: ctx => {
    console.log(`Removing remote: ${ctx.values.name}`)
  }
})

// Define an intermediate command with nested sub-commands
const remoteCommand = define({
  name: 'remote',
  description: 'Manage remotes',
  subCommands: {
    add: addCommand,
    remove: removeCommand
  },
  run: () => {
    console.log('Use: git remote add|remove')
  }
})

// Define the entry command
const entry = define({
  name: 'main',
  description: 'Git-like CLI',
  run: () => {
    console.log('Run --help for available commands')
  }
})

await cli(process.argv.slice(2), entry, {
  name: 'git',
  version: '1.0.0',
  subCommands: {
    remote: remoteCommand
  }
})
```

> \[!TIP]
> The complete example code is [here](https://github.com/kazupon/gunshi/tree/main/playground/advanced/nested-sub-commands).

Now users can run:

```sh
# Execute nested sub-command
$ npx tsx cli.ts remote add --url https://example.com
Adding remote: https://example.com

# Show help for intermediate command
$ npx tsx cli.ts remote --help
Manage remotes

USAGE:
  git remote [COMMANDS] <OPTIONS>

COMMANDS:
  [remote]               Manage remotes
  add <OPTIONS>          Add a remote
  remove <name>          Remove a remote

For more info, run any command with the `--help` flag:
  git remote --help
  git remote add --help
  git remote remove --help

# Show help for leaf command
$ npx tsx cli.ts remote add --help
Add a remote

USAGE:
  git remote add <OPTIONS>

OPTIONS:
  --url <url>          Remote URL
```

## Three or More Levels

You can nest commands to any depth:

```ts
const subSubCommand = define({
  name: 'sub-sub',
  description: 'A deeply nested command',
  run: ctx => {
    // ctx.commandPath will be ['level1', 'level2', 'sub-sub']
    console.log(`Command path: ${ctx.commandPath.join(' > ')}`)
  }
})

const level2Command = define({
  name: 'level2',
  description: 'Second level',
  subCommands: { 'sub-sub': subSubCommand },
  run: () => {}
})

const level1Command = define({
  name: 'level1',
  description: 'First level',
  subCommands: { level2: level2Command },
  run: () => {}
})
```

## Using `commandPath`

The `CommandContext` includes a `commandPath` property that tells you the full path of commands that were resolved:

```ts
const addCommand = define({
  name: 'add',
  description: 'Add a remote',
  run: ctx => {
    console.log(ctx.commandPath) // ['remote', 'add']
    console.log(ctx.callMode) // 'subCommand'
  }
})
```

| Invocation       | `commandPath`       | `callMode`     |
| ---------------- | ------------------- | -------------- |
| `cli`            | `[]`                | `'entry'`      |
| `cli remote`     | `['remote']`        | `'subCommand'` |
| `cli remote add` | `['remote', 'add']` | `'subCommand'` |

## Intermediate Commands

When a user invokes an intermediate command (one that has nested sub-commands) without specifying a child, the intermediate command's `run` function is called with `omitted: true`. In this case, the built-in help system automatically shows a COMMANDS section listing the available nested sub-commands:

```ts
const remoteCommand = define({
  name: 'remote',
  description: 'Manage remotes',
  subCommands: { add: addCommand },
  run: ctx => {
    if (ctx.omitted) {
      // User ran `cli remote` without specifying a sub-command
      // Help is shown automatically with COMMANDS section
      console.log('Please specify a sub-command: add, remove')
    }
  }
})
```

## Nested Sub-Commands with Lazy Loading

For large CLIs, you can combine nested sub-commands with lazy loading:

```ts
import { cli, define, lazy } from 'gunshi'

// Lazy-load the leaf command
const addCommand = lazy(() => import('./commands/remote-add.ts'), {
  name: 'add',
  description: 'Add a remote',
  args: {
    url: { type: 'string', required: true, description: 'Remote URL' }
  }
})

// The parent command can also be lazy-loaded
const remoteCommand = lazy(() => import('./commands/remote.ts'), {
  name: 'remote',
  description: 'Manage remotes',
  subCommands: {
    add: addCommand
  }
})

await cli(process.argv.slice(2), entry, {
  name: 'git',
  subCommands: { remote: remoteCommand }
})
```

> \[!IMPORTANT]
> When using `lazy()` with nested sub-commands, include `args` in the lazy definition (the second argument) if you want argument parsing to work before the command is loaded. The `subCommands` of the definition, like the other properties it declares, is carried over to the lazy command, and is used when the loaded command does not define it.

Options can be placed at the start or between path segments, for example
`remote --config prod.json add origin`. Gunshi uses each candidate command's declared option metadata
to remove option values before matching `remote add`; the option is then parsed once for the selected
leaf. If a lazy parent or leaf can receive a leading option, declare that option in its lazy metadata.
Use `--` when the remaining values must stay in `ctx.rest` rather than being explored as another
sub-command.

## Generating Documentation for Nested Commands

The `generate()` function supports nested command paths:

```ts
import { generate } from 'gunshi/generator'

// Generate help for a nested command using array or space-separated string
const help = await generate(['remote', 'add'], entry, {
  name: 'git',
  subCommands: { remote: remoteCommand }
})

// Or using space-separated string
const help2 = await generate('remote add', entry, { ... })
```

---

---
url: /guide/plugin/introduction.md
---
# Plugin System Introduction

Gunshi's plugin system is a powerful feature that enables you to extend your CLI applications with reusable functionality, type-safe interfaces, and composable behaviors.

This comprehensive system allows you to build modular, maintainable, and extensible command-line tools.

## Why Plugins?

The plugin system addresses several key challenges in CLI development:

### 1. Separation of Concerns

Plugins allow you to separate core command logic from cross-cutting concerns like logging, authentication, database connections, and rendering.

This separation makes your code more organized and easier to maintain.

### 2. Reusability

Once you create a plugin, you can reuse it across multiple commands and even different CLI applications.

This reduces code duplication and development time.

### 3. Type Safety

Gunshi's plugin system is built with TypeScript-first design, providing full type safety for plugin extensions and their interactions.

You get compile-time validation and IntelliSense support throughout your development.

### 4. Ecosystem

The plugin architecture enables a rich ecosystem where developers can share and compose plugins.

Official plugins provide common functionality, while you can create custom plugins for your specific needs.

## Plugin System Concepts

### Plugin Philosophy

Gunshi plugins follow these core principles:

* **Composability**: Plugins can be combined and work together seamlessly
* **Type Safety**: Full TypeScript support with compile-time validation
* **Lifecycle Awareness**: Plugins integrate at specific points in the CLI lifecycle
* **Dependency Management**: Automatic resolution of plugin dependencies
* **Extension Pattern**: Plugins extend command contexts with new capabilities

### Plugin Architecture

```mermaid
graph TD
    A[CLI Application] --> B[Plugin System]
    B --> C[Plugin Registration]
    C --> D[Dependency Resolution]
    D --> E[Setup Phase]
    E --> F[Extension Creation]
    F --> G[Command Execution]

    H[Plugin 1] --> C
    I[Plugin 2] --> C
    J[Plugin 3] --> C

    H -.->|depends on| I
    I -.->|optional| J
```

This diagram illustrates the plugin system's execution flow.

When a CLI application starts, plugins are registered and their dependencies are resolved. During the setup phase, each plugin's initialization code runs.

Extensions are then created and made available to commands during execution.

Plugins can depend on each other (solid lines) or have optional dependencies (dotted lines).

## Package vs Entry Point

Gunshi provides two ways to work with plugins:

### Package: `@gunshi/plugin`

The `@gunshi/plugin` package is a complete plugin development kit:

::: code-group

```sh [npm]
npm install --save @gunshi/plugin
```

```sh [pnpm]
pnpm add @gunshi/plugin
```

```sh [yarn]
yarn add @gunshi/plugin
```

```sh [deno]
deno add jsr:@gunshi/plugin
```

```sh [bun]
bun add @gunshi/plugin
```

:::

Use this package when:

* Building standalone plugin packages
* Creating plugins with complex type definitions
* Developing plugins for distribution
* Need access to all plugin utilities and types

```ts
// Using the package for plugin development
import { plugin } from '@gunshi/plugin'
import type { PluginContext } from '@gunshi/plugin'

export default function myPlugin() {
  return plugin({
    id: 'my-plugin',
    setup: (ctx: PluginContext) => {
      // Plugin implementation
    }
  })
}
```

### Entry Point: `gunshi/plugin`

The `gunshi/plugin` entry point provides essential plugin functionality:

```js
// Using the entry point for simple plugins
import { plugin } from 'gunshi/plugin'

export default plugin({
  id: 'simple',
  setup: ctx => {
    // Simple plugin logic
  }
})
```

Use the entry point when:

* Creating simple, application-specific plugins
* Building inline plugins within your CLI
* Want to minimize external dependencies

## Plugin Ecosystem Overview

### Official Plugins

Gunshi provides several official plugins that cover common CLI needs:

#### Core Plugins (Built-in)

* **`@gunshi/plugin-global`**: Adds `--help`, `--version` options, version, header, usage and validation errors rendering helpers
* **`@gunshi/plugin-renderer`**: Provides usage and help core renderer

#### Optional Plugins

* **`@gunshi/plugin-i18n`**: Internationalization support
* **`@gunshi/plugin-completion`**: Shell completion functionality
* **`@gunshi/plugin-dryrun`**: Dry-run support for explicitly wrapped side-effect operations

### Community Plugins

The plugin architecture enables the community to create and share plugins.

### Custom Plugins

You can create custom plugins tailored to your specific needs:

```ts
// Domain-specific plugin for your application
export default plugin({
  id: 'api',
  extension: () => ({
    client: new ApiClient(),
    authenticate: async (token: string) => {
      // Custom authentication logic
    }
  })
})
```

## Plugin Capabilities

### 1. Add Global Options

Plugins can register global options that will be available to all commands:

```js
setup: ctx => {
  ctx.addGlobalOption('debug', {
    type: 'boolean',
    description: 'Enable debug mode'
  })
}
```

### 2. Register Sub-Commands

Plugins can dynamically register new sub-commands during the setup phase:

```js
setup: ctx => {
  ctx.addCommand('plugin-command', {
    name: 'plugin-command',
    run: ctx => console.log('Plugin command executed')
  })
}
```

### 3. Decorate Renderers

Plugins can enhance or modify the built-in renderers to customize output:

```js
setup: ctx => {
  ctx.decorateUsageRenderer(async (baseRenderer, ctx) => {
    const base = await baseRenderer(ctx)
    return `${base}\n\nEnhanced by plugin`
  })
}
```

### 4. Extend Command Context

Plugins can extend the `CommandContext` with additional functionality that commands can access:

```js
extension: () => ({
  database: new Database(),
  cache: new Cache(),
  logger: new Logger()
})
```

### 5. Intercept Command Execution

Plugins can intercept and modify command execution using decorators:

```js
setup: ctx => {
  ctx.decorateCommand(baseRunner => async ctx => {
    console.log('Before command')
    const result = await baseRunner(ctx)
    console.log('After command')
    return result
  })
}
```

## Getting Started

To start using plugins in your Gunshi CLI:

1. **Use Built-in Plugins**: The default `cli` function includes essential plugins
2. **Add Official Plugins**: Install and configure official plugins as needed
3. **Create Custom Plugins**: Build plugins specific to your application
4. **Share Plugins**: Publish reusable plugins for the community

The following is an example of code for installing the official `@gunshi/plugin-i18n` and application-specific plugins:

```js
import { cli } from 'gunshi'
import i18n from '@gunshi/plugin-i18n'
import custom from './plugins/custom.js'

const entry = ctx => {}

await cli(args, entry, {
  plugins: [i18n({ locale: 'en-US' }), custom()]
})
```

## Next Steps

Now that you understand what plugins are and how they enhance Gunshi CLIs, it's time to start building your own plugins.

The plugin development learning journey follows a progression:

* **[Getting Started](./getting-started.md)** - Create your first plugin with simple examples and learn the basic plugin structure
* **[Plugin Lifecycle](./lifecycle.md)** - Understand when and how plugins execute during CLI runtime
* **[Plugin Dependencies](./dependencies.md)** - Build plugin ecosystems with proper dependency management
* **[Plugin Decorators](./decorators.md)** - Wrap and enhance existing functionality with decorators
* **[Plugin Extensions](./extensions.md)** - Share features across commands through context extensions
* **[Plugin Type System](./type-system.md)** - Ensure type safety throughout your plugin implementation
* **[Plugin Testing](./testing.md)** - Write comprehensive tests for your plugins
* **[Plugin Development Guidelines](./guidelines.md)** - Follow production-ready patterns and conventions
* **[Plugin List](./list.md)** - Explore official and community plugins

Start with [Getting Started](./getting-started.md) to create your first plugin and experience the plugin development workflow firsthand.

---

---
url: /guide/plugin/getting-started.md
---
# Getting Started with Plugin Development

This guide will walk you through creating your first Gunshi plugin, from the simplest possible plugin to more advanced patterns with extensions and decorators.

## Your First Minimal Plugin

Let's start with the absolute minimum (no extension) - a plugin that simply logs when it's loaded:

```js [plugin.js]
import { plugin } from 'gunshi/plugin'

// The simplest possible plugin
export default plugin({
  id: 'hello',
  name: 'Hello Plugin',
  setup: ctx => {
    console.log('Hello from plugin!')
  }
})
```

Use it in your CLI:

```js [cli.js]
import { cli } from 'gunshi'
import hello from './plugin.js'

const entry = () => {}

await cli(process.argv.slice(2), entry, {
  plugins: [hello]
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/plugins/getting-started/first-minimal).

Run your application with plugin:

```sh
# Run the entry with plugin
node cli.js

Hello from plugin!
```

This plugin:

* Has a unique `id` for identification
* Has a human-readable `name`
* Runs its `setup` function during plugin initialization
* Doesn't extend the command context

## Adding Global Options

Let's create a plugin that adds a global `--debug` option to all commands:

```js [plugin.js]
import { plugin } from 'gunshi/plugin'

export default plugin({
  id: 'debug',
  name: 'Debug Plugin',

  setup: ctx => {
    // Add a global option available to all commands
    ctx.addGlobalOption('debug', {
      type: 'boolean',
      short: 'd',
      description: 'Enable debug output'
    })
  }
})
```

Now all commands have access to `--debug`:

```js [cli.js]
import { cli, define } from 'gunshi'
import debug from './plugin.js'

const command = define({
  name: 'build',
  run: ctx => {
    if (ctx.values.debug) {
      console.log('Debug mode enabled')
      console.log('Context:', ctx)
    }
    console.log('Building...')
  }
})

await cli(process.argv.slice(2), command, {
  plugins: [debug]
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/plugins/getting-started/adding-global).

Run your application with plugin:

```sh
# Run command with debug option
node cli.js --debug

Debug mode enabled
Context: ...
...
Building ...
```

## Adding Sub-Commands

Plugins can register sub-commands that become available to the CLI:

```js [plugin.js]
import { plugin } from 'gunshi/plugin'

export default plugin({
  id: 'tools',
  name: 'Developer Tools Plugin',

  setup: ctx => {
    // Add a new sub-command
    ctx.addCommand('clean', {
      name: 'clean',
      description: 'Clean build artifacts',
      args: {
        cache: {
          type: 'boolean',
          description: 'Also clear cache',
          default: false
        }
      },
      run: ctx => {
        console.log('Cleaning build artifacts...')
        if (ctx.values.cache) {
          console.log('Clearing cache...')
        }
        console.log('Clean complete!')
      }
    })

    // Add another sub-command
    ctx.addCommand('lint', {
      name: 'lint',
      description: 'Run linter',
      run: ctx => {
        console.log('Running linter...')
        console.log('No issues found!')
      }
    })
  }
})
```

Now your CLI has additional commands:

```js [cli.js]
import { cli, define } from 'gunshi'
import tools from './plugin.js'

// Main command
const command = define({
  name: 'build',
  run: ctx => console.log('Building project...')
})

await cli(process.argv.slice(2), command, {
  plugins: [tools]
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/plugins/getting-started/adding-sub-commands).

Run your application with the new sub-commands:

```sh
# Run main command
node cli.js
Building project...

# Run plugin's sub-command
node cli.js clean
Cleaning build artifacts...
Clean complete!

# With arguments
node cli.js clean --cache
Cleaning build artifacts...
Clearing cache...
Clean complete!

# Run another sub-command
node cli.js lint
Running linter...
No issues found!
```

The top-level help lists the default command together with commands supplied by the plugin:

```sh
node cli.js --help

COMMANDS:
  [build]
  clean [OPTIONS]          Clean build artifacts
  lint                     Run linter
```

The brackets around `build` indicate that it is the default entry command used when no
sub-command is specified.

## Advanced Plugin Features

Beyond basic setup and global options, plugins can provide much more powerful functionality:

### Extensions

Plugins can extend the command context with new functionality that all commands can use.

```js
// Simple example - adding logging functionality
export default plugin({
  id: 'logger',
  extension: () => ({
    log: msg => console.log(msg)
  })
})

// Commands can then use: ctx.extensions.logger.log('Hello')
```

> \[!TIP]
> Extensions are the core feature for sharing functionality between plugins and commands. Learn more in [Plugin Extensions](./extensions.md).

### Decorators

Plugins can decorate (wrap) existing functionality to enhance behavior:

```js
// Customize how help text is displayed
ctx.decorateUsageRenderer(async (baseRenderer, ctx) => {
  const baseUsage = await baseRenderer(ctx)
  return `${baseUsage}\n\n📚 Documentation: https://example.com/docs`
})
```

> \[!TIP]
> Decorators allow you to wrap commands, renderers, and more. Learn about all decorator types in [Plugin Decorators](./decorators.md).

### Dependencies

Plugins can declare dependencies on other plugins:

```js
export default plugin({
  id: 'auth',
  dependencies: ['logger'], // Requires logger plugin
  setup: ctx => {
    // Logger plugin is guaranteed to be loaded
  }
})
```

> \[!TIP]
> Dependencies ensure plugins load in the correct order. Learn more in [Plugin Dependencies](./dependencies.md).

## Summary

You've now learned the basics of Gunshi plugin development:

* Creating minimal plugins with setup functions
* Adding global options available to all commands
* Registering sub-commands through plugins
* Understanding advanced features (extensions, decorators, dependencies)

These fundamentals provide a solid foundation for building more complex plugins.

## Next Steps

You've created your first Gunshi plugin and learned the fundamental concepts: setup functions, global options, sub-command registration, and basic plugin features.

With these foundations in place, you're ready to understand how plugins integrate with the CLI execution flow.

The next chapter, [Plugin Lifecycle](./lifecycle.md), will show you exactly when and how plugins execute during CLI runtime, giving you the knowledge to build more sophisticated plugins that interact with commands at the right moments.

---

---
url: /guide/plugin/lifecycle.md
---
# Plugin Lifecycle

Understanding the Gunshi lifecycle is crucial for effective plugin development.

This guide explains how plugins integrate with the CLI execution flow and when different plugin features are activated.

## CLI Execution Lifecycle

When a Gunshi CLI application runs, it follows a specific sequence of steps from startup to completion.

The diagram below shows the complete execution flow, with plugin-related steps highlighted in green:

```mermaid
graph TD
    A[A. CLI Start] --> B[B. Load Plugins]
    B --> C[C. Resolve Dependencies]
    C --> D[D. Execute Plugin Setup]
    D --> E[E. Parse Arguments]
    E --> F[F. Resolve Command]
    F --> G[G. Resolve & Validate Args]
    G --> H[H. Create CommandContext<br/>Process each plugin sequentially:<br/>1. Create extension<br/>2. Call onExtension]
    H --> I[I. Execute Command]
    I --> J[J. CLI End]

    style B fill:#468c56,color:white
    style C fill:#468c56,color:white
    style D fill:#468c56,color:white
    style H fill:#468c56,color:white
    style I fill:#468c56,color:white
```

The lifecycle consists of 10 steps (A through J), where plugins are primarily involved in:

* **Steps B-D**: Plugin initialization and setup
* **Step H**: Plugin extension creation and activation during CommandContext creation
* **Step I**: Command execution with plugin decorators applied

## Plugin-Specific Lifecycle Steps

Plugins are primarily involved in specific steps of the CLI lifecycle.

This section focuses on the steps where plugins actively participate.

### Setup Phase (Steps B-D)

During the setup phase, plugins are loaded, dependencies are resolved, and plugin setup functions are executed.

This phase occurs once at CLI initialization.

**What happens in this phase:**

* Plugins configure the CLI by adding options, commands, and decorators
* All modifications are registered but not yet executed
* The `setup()` function runs for each plugin

#### Step B: Load Plugins

Plugins are collected from CLI options and prepared for initialization.

The following code shows how plugins are passed to the CLI function:

```js
import { cli } from 'gunshi'

await cli(args, command, {
  plugins: [
    plugin1(), // Collected
    plugin2(), // Collected
    plugin3() // Collected
  ]
})
```

#### Step C: Resolve Dependencies

Gunshi uses **topological sorting** to resolve plugin dependencies.

The following example demonstrates how plugins with dependencies are resolved in the correct order:

```js
import { plugin } from 'gunshi/plugin'

// Given these plugins:
const pluginA = plugin({
  id: 'a',
  dependencies: ['b', 'c']
})

const pluginB = plugin({
  id: 'b',
  dependencies: ['d']
})

const pluginC = plugin({
  id: 'c'
})

const pluginD = plugin({
  id: 'd'
})

// Resolution order: d → b → c → a
```

> \[!TIP]
> For details on plugin dependency resolution, including circular dependency detection, optional dependencies, see [Plugin Dependencies](./dependencies.md).

#### Step D: Execute Plugin Setup

The `setup` function of each plugin is called in dependency order.

This example shows what actions a plugin can perform during setup:

```js
import { plugin } from 'gunshi/plugin'

const myPlugin = plugin({
  id: 'my-plugin',
  setup: ctx => {
    // This runs during Setup Phase
    console.log('Plugin setting up')

    // Add global options
    ctx.addGlobalOption('verbose', {
      type: 'boolean',
      description: 'Verbose output'
    })

    // Register sub-commands
    ctx.addCommand('plugin-cmd', {
      name: 'plugin-cmd',
      run: ctx => console.log('Plugin command')
    })

    // Add decorators (they stack in LIFO order)
    ctx.decorateCommand(baseRunner => async ctx => {
      console.log('Before command (from plugin)')
      const result = await baseRunner(ctx)
      console.log('After command (from plugin)')
      return result
    })
  }
})
```

A `setup` that throws ends the run: `cli()` rejects with an error naming the plugin, and the error it threw is available as the `cause`. Nothing is installed after it, and no command runs. This matches how a circular or a missing dependency is reported in Step C — a CLI that cannot be assembled is not run.

```sh
Error: Failed to install the plugin `my-plugin`
  [cause]: Error: Global option 'verbose' is already registered
```

Keep `setup` to registration. Work that can fail for reasons outside your control — reading a file, probing the environment, talking to a network — belongs in an extension or a decorator, where it runs per command and can be handled there.

### Command Processing (Steps E-H)

Between the setup phase and execution phase, Gunshi processes the command-line arguments and prepares the execution context:

* **Step E**: Parse command-line arguments into structured tokens
* **Step F**: Resolve which command to execute
* **Step G**: Validate arguments against the command's schema
* **Step H**: Create the CommandContext object

> \[!NOTE]
> These internal processing steps are handled automatically by Gunshi. Plugin developers don't need to interact with these steps directly.

### Execution Phase (Steps H-I)

During the execution phase, the CommandContext is created with plugin extensions, and then the command is executed with all decorators applied.

### Step H: Create CommandContext & Process Plugins

The CommandContext is created and each plugin's extension is initialized:

1. Initialize CommandContext with parsed arguments and values
2. For each plugin (in dependency order):
   * Call the plugin's `extension()` function to create an extension
   * Store the extension in `context.extensions[pluginId]`
   * Immediately call the plugin's `onExtension()` callback if present

This sequential processing ensures extensions from dependencies are available to dependent plugins.

> \[!NOTE]
> For detailed information about the extension lifecycle, including execution order guarantees, the relationship between `extension` and `onExtension`, and code examples, see the [Extension Lifecycle](./extensions.md#extension-lifecycle) section in the Plugin Extensions guide.

### Step I: Execute Command

The command runner executes with:

* All decorators applied in LIFO (Last In, First Out) order
* Full access to all plugin extensions via `ctx.extensions`
* Complete CommandContext with validated arguments

This example illustrates the command execution with decorator wrapping and extension usage:

```js
import { define } from 'gunshi'

// If plugins A, B, C add decorators in that order:
// Execution order: C → B → A → original command → A → B → C

const command = define({
  name: 'build',
  run: ctx => {
    // This is the original command
    ctx.extensions.logger.log('Building project...')
    // Build logic here
  }
})
```

## Extension Lifecycle in Detail

Understanding the relationship between `extension` and `onExtension` is crucial for effective plugin development.

During Step H (Create CommandContext):

* Each plugin is processed sequentially in dependency order
* For each plugin: the `extension` factory is called, then immediately its `onExtension` callback
* This sequential approach ensures that when a plugin's `onExtension` runs, all previous plugins' extensions are already available through `ctx.extensions`

> \[!TIP]
> For a detailed visual representation of the extension lifecycle and execution order guarantees, see [Extension Lifecycle](./extensions.md#extension-lifecycle) in the Plugin Extensions guide.

## Lifecycle with Command Hooks

Gunshi provides Command hooks (`onBeforeCommand`, `onAfterCommand`, `onErrorCommand`) that integrate with the plugin lifecycle.

The following sequence diagram illustrates how these command hooks interact with plugins during command execution:

> \[!TIP]
> For details on Command Hooks, including advanced use cases like logging, performance monitoring, validation guards, and transaction management, see [Command Hooks](../advanced/command-hooks.md).

```mermaid
sequenceDiagram
    participant CLI as CLI
    participant Plugin as Plugin
    participant Command as Command

    CLI->>Plugin: Setup Phase
    Plugin->>CLI: Register decorators

    CLI->>CLI: Create Context
    CLI->>Plugin: Create Extensions
    Plugin->>CLI: Return Extensions

    CLI->>CLI: onBeforeCommand
    CLI->>Plugin: Apply Decorators
    Plugin->>Command: Execute (decorated)
    Command->>Plugin: Return
    Plugin->>CLI: Return
    CLI->>CLI: onAfterCommand

    Note over CLI: Or on error:
    Command-->>CLI: Throw Error
    CLI->>CLI: onErrorCommand
```

This sequence shows:

1. **Setup Phase**: Plugins register their decorators during initialization
2. **Extension Creation**: Plugin extensions are created and returned to the CLI
3. **Command Hooks**: The `onBeforeCommand` hook runs before decorators and command execution
4. **Decorated Execution**: Plugin decorators wrap the command execution
5. **Post-Execution**: The `onAfterCommand` hook runs after successful completion
6. **Error Handling**: The `onErrorCommand` hook catches any errors during execution

## Complete Lifecycle Example

Here's a complete example showing all lifecycle phases including Command Hooks.

Plugin Codes:

```js [lifecycle.js]
import { plugin } from 'gunshi/plugin'

export default plugin({
  id: 'lifecycle',
  dependencies: ['logger'], // Step C: Dependency resolution

  // Step D: Setup execution
  setup: ctx => {
    console.log('1. lifecycle plugin setup phase started')

    // Register global option
    ctx.addGlobalOption('verbose', {
      type: 'boolean',
      alias: 'v',
      description: 'Verbose output'
    })

    // Add sub-command
    ctx.addCommand('status', {
      name: 'status',
      run: ctx => console.log('Status: OK')
    })

    // Register decorators (LIFO order)
    ctx.decorateCommand(runner => async ctx => {
      console.log('5. Command decorator (before)')
      const result = await runner(ctx)
      console.log('7. Command decorator (after)')
      return result
    })

    console.log('2. Setup phase completed')
  },

  // Step H: Extension creation (during CommandContext creation)
  extension: (ctx, cmd) => {
    console.log('3. Extension created for:', cmd.name)

    return {
      demo: () => 'Hello from extension',
      cleanup: () => console.log('9. Extension cleanup')
    }
  },

  // Step H: Post-extension callback (immediately after extension creation)
  onExtension: (ctx, cmd) => {
    console.log('4. All extensions ready')
  }
})
```

Application Codes:

```js [cli.js]
import { cli, define } from 'gunshi'
import logger from './logger.js'
import lifecycle from './lifecycle.js'

// Command definition
const command = define({
  name: 'build',
  args: {
    fail: {
      type: 'boolean'
    }
  },
  run: ctx => {
    console.log('6. Actual command execution')
    console.log('Extension says:', ctx.extensions['lifecycle'].demo())

    // Simulate an error for demonstration
    if (ctx.values.fail) {
      throw new Error('Build failed!')
    }
  }
})

// Running the CLI with Command Hooks
await cli(process.argv.slice(2), command, {
  // Plugin installation
  plugins: [logger, lifecycle],

  // Command Hooks are defined at CLI level
  onBeforeCommand: ctx => {
    console.log('4.5. onBeforeCommand hook')
  },

  onAfterCommand: ctx => {
    console.log('8. onAfterCommand hook')
    // Cleanup can be done here
    ctx.extensions['lifecycle'].cleanup()
  },

  onErrorCommand: (ctx, error) => {
    console.log('8. onErrorCommand hook:', error.message)
    // Error recovery or cleanup
    ctx.extensions['lifecycle'].cleanup()
  }
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/plugins/lifecycle).

Run your application with plugin:

```sh
node cli.js

logger plugin setup phase started
1. lifecycle plugin setup phase started
2. Setup phase completed
3. Extension created for: build
4. All extensions ready
4.5. onBeforeCommand hook
5. Command decorator (before)
6. Actual command execution
Extension says: Hello from extension
7. Command decorator (after)
8. onAfterCommand hook
9. Extension cleanup

node index.js --fail
logger plugin setup phase started
1. lifecycle plugin setup phase started
2. Setup phase completed
3. Extension created for: build
4. All extensions ready
4.5. onBeforeCommand hook
5. Command decorator (before)
6. Actual command execution
Extension says: Hello from extension
8. onErrorCommand hook: Build failed!
9. Extension cleanup
file:///path/to/projects/gunshi/playground/plugins/lifecycle/index.js:19
      throw new Error('Build failed!')
```

## Next Steps

Now that you understand how plugins integrate with the CLI lifecycle—from setup through command execution to cleanup—you're ready to explore how plugins can work together.

The next chapter, [Plugin Dependencies](./dependencies.md), will teach you how to build plugin ecosystems where plugins can depend on and interact with each other, enabling composition patterns for complex CLI applications.

---

---
url: /guide/plugin/dependencies.md
---
# Plugin Dependencies

Gunshi's plugin system includes a sophisticated dependency management system that ensures plugins load in the correct order and can safely interact with each other.

This guide covers everything you need to know about plugin dependencies.

## Understanding Plugin Dependencies

Plugin dependencies allow you to:

* Ensure required plugins are loaded before your plugin
* Access functionality from other plugins
* Build composable plugin ecosystems
* Handle optional features gracefully

## Why Declare Dependencies?

Declaring dependencies explicitly provides several benefits:

1. **Load Order Guarantee**: Ensures your plugin's dependencies are initialized before your plugin runs
2. **Runtime Safety**: Prevents runtime errors from missing required functionality
3. **Clear Documentation**: Makes plugin relationships explicit and discoverable
4. **Type Safety**: Enables TypeScript to validate extension availability at compile time (see [Type-Safe Dependencies](./type-system.md#plugin-with-dependencies))
5. **Error Prevention**: Gunshi can detect missing dependencies and provide helpful error messages

## Dependency Resolution Process

Gunshi uses **topological sorting** to resolve plugin dependencies, ensuring that:

1. Plugins with no dependencies load first
2. Dependent plugins load after their dependencies
3. Circular dependencies are detected and prevented

### Example Dependency Graph

Consider the following plugin dependency relationships:

```mermaid
graph LR
    A[Logger Plugin]
    B[Cache Plugin] --> A
    C[Auth Plugin] --> A
    C --> B
    D[API Plugin] --> C

    style A fill:#4A90E2,stroke:#2E5A8E,stroke-width:2px,color:#fff
    style B fill:#9B59B6,stroke:#633974,stroke-width:2px,color:#fff
    style C fill:#468c56,stroke:#2e5936,stroke-width:2px,color:#fff
    style D fill:#E67E22,stroke:#935014,stroke-width:2px,color:#fff
```

In this dependency graph:

* **Logger Plugin** has no dependencies (it's a base plugin)
* **Cache Plugin** depends on Logger Plugin (needs logging functionality)
* **Auth Plugin** depends on both Logger Plugin and Cache Plugin (needs logging and caching)
* **API Plugin** depends on Auth Plugin (requires authenticated users)

### Resolution Order

Based on the dependency graph above, Gunshi's topological sorting algorithm determines the following loading order:

**Loading order: Logger → Cache → Auth → API**

This ensures that:

1. **Logger** loads first (no dependencies)
2. **Cache** loads after Logger (its dependency is satisfied)
3. **Auth** loads after both Logger and Cache (both dependencies are satisfied)
4. **API** loads last after Auth (its dependency is satisfied)

Note that Logger and Cache must both be loaded before Auth can initialize, as Auth depends on both of them.

## Declaring Dependencies

Plugin dependencies are declared in the plugin configuration using the `dependencies` property.

This property accepts an array of dependency specifications that tell Gunshi which other plugins must be loaded before your plugin can function correctly.

### Dependency Declaration Syntax

Dependencies can be declared in two ways:

```js
// Simple string format for required dependencies
dependencies: ['logger', 'auth']

// Object format for optional dependencies
dependencies: [
  'logger', // Required dependency
  { id: 'cache', optional: true } // Optional dependency
]
```

### Required Dependencies

Required dependencies must be present for your plugin to load. If a required dependency is missing, Gunshi will throw an error during initialization.

> \[!WARNING]
> If you register multiple plugins with the same ID, Gunshi will emit a warning: `Duplicate plugin id detected`. While the plugins will still load, having duplicate IDs can lead to unexpected behavior when accessing extensions or resolving dependencies. Always ensure each plugin has a unique ID.

Declare required dependencies using the `dependencies` array:

```js
import { plugin } from 'gunshi/plugin'

// Simple string dependency
const auth = plugin({
  id: 'auth',
  dependencies: ['logger'], // Requires 'logger' plugin
  setup: ctx => {
    // Logger plugin is guaranteed to be loaded
  }
})

// Multiple dependencies
const api = plugin({
  id: 'api',
  dependencies: ['auth', 'cache', 'logger'],
  setup: ctx => {
    // All three plugins are loaded
  }
})
```

### Optional Dependencies

Optional dependencies allow your plugin to enhance its functionality when certain plugins are available, while still functioning correctly when they're not.

This enables graceful degradation and flexible plugin ecosystems.

#### When to Use Optional Dependencies

Use optional dependencies when:

* Your plugin can provide additional features with another plugin, but doesn't require it
* You want to support multiple plugin configurations
* You're building plugins that adapt to different environments
* You need to maintain backward compatibility

#### Declaring Optional Dependencies

Mark dependencies as optional using the object format:

```js
import { plugin } from 'gunshi/plugin'

const enhanced = plugin({
  id: 'enhanced',
  dependencies: [
    'core', // Required
    { id: 'cache', optional: true }, // Optional
    { id: 'metrics', optional: true } // Optional
  ],
  setup: ctx => {
    // 'core' is guaranteed
    // 'cache' and 'metrics' might not be present
  }
})
```

## Circular Dependencies

A circular dependency occurs when two or more plugins depend on each other, creating a dependency loop that cannot be resolved.

Gunshi's dependency resolution system detects these cycles and prevents them to ensure a stable plugin initialization order.

### Understanding Circular Dependencies

Circular dependencies create logical paradoxes in the loading order:

* Plugin A requires Plugin B to be loaded first
* Plugin B requires Plugin A to be loaded first
* Neither can be loaded before the other

This situation makes it impossible to determine a valid initialization sequence and indicates architectural issues such as tight coupling and reduced reusability.

### Detection and Prevention

Gunshi automatically detects circular dependencies during the resolution phase and will throw an error:

```js
import { plugin } from 'gunshi/plugin'

// This will fail!
const pluginA = plugin({
  id: 'A',
  dependencies: ['B'],
  setup: ctx => {}
})

const pluginB = plugin({
  id: 'B',
  dependencies: ['A'], // Circular!
  setup: ctx => {}
})

// Circular dependency detected: `a -> b -> a`
```

Circular dependencies can also occur in longer chains:

```js
import { plugin } from 'gunshi/plugin'

// Three-way circular dependency
const pluginX = plugin({
  id: 'X',
  dependencies: ['Y'],
  setup: ctx => {}
})

const pluginY = plugin({
  id: 'Y',
  dependencies: ['Z'],
  setup: ctx => {}
})

const pluginZ = plugin({
  id: 'Z',
  dependencies: ['X'], // Creates cycle: X → Y → Z → X
  setup: ctx => {}
})

// Circular dependency detected: `x -> y -> z -> x`
```

### Resolving Circular Dependencies

The most practical and recommended approach to resolve circular dependencies is to extract common functionality into a separate plugin.

This creates a clean architecture where both plugins can depend on the shared functionality without depending on each other.

When two plugins need to share functionality, extract that functionality into a base plugin that both can depend on:

**Problem: Circular dependency between two plugins**

```js
import { plugin } from 'gunshi/plugin'

// ❌ Circular dependency - This will fail!
const pluginA = plugin({
  id: 'plugin-a',
  dependencies: ['plugin-b'], // A needs B
  extension: ctx => ({
    methodA: () => {
      // Uses B's functionality
      return ctx.extensions['plugin-b'].methodB() + ' from A'
    }
  })
})

const pluginB = plugin({
  id: 'plugin-b',
  dependencies: ['plugin-a'], // B needs A
  extension: ctx => ({
    methodB: () => {
      // Uses A's functionality
      return ctx.extensions['plugin-a'].methodA() + ' from B'
    }
  })
})
// Circular dependency detected: `plugin-a -> plugin-b -> plugin-a`
```

**Solution: Extract shared functionality into a common plugin**

```js
import { plugin, cli } from 'gunshi/plugin'

// ✅ Create a common base plugin with shared functionality
const shared = plugin({
  id: 'shared',
  extension: () => ({
    // Shared state and functionality
    data: { value: 0 },
    increment: function () {
      this.data.value++
    },
    getValue: function () {
      return this.data.value
    }
  })
})

// Plugin A now depends only on shared
const pluginA = plugin({
  id: 'plugin-a',
  dependencies: ['shared'],
  extension: ctx => ({
    methodA: () => {
      ctx.extensions.shared.increment()
      return `A: value is ${ctx.extensions.shared.getValue()}`
    }
  })
})

// Plugin B also depends only on shared
const pluginB = plugin({
  id: 'plugin-b',
  dependencies: ['shared'],
  extension: ctx => ({
    methodB: () => {
      const value = ctx.extensions.shared.getValue()
      return `B: current value is ${value}`
    }
  })
})

// Usage - no circular dependency!
await cli(args, command, {
  plugins: [
    shared, // Loads first
    pluginA, // Loads second (depends on shared)
    pluginB // Loads third (depends on shared)
  ]
})
```

This approach offers several benefits:

1. **Clear dependency hierarchy**: shared → pluginA/pluginB (no cycles)
2. **Single responsibility**: Each plugin has a focused purpose
3. **Reusability**: The shared plugin can be used by other plugins
4. **Testability**: Each plugin can be tested independently
5. **Maintainability**: Changes to shared logic are centralized

## Complete Dependency Resolution Example

Here's a complete example demonstrating dependency resolution order with complex dependencies:

logger plugin:

```js [logger.js]
import { plugin } from 'gunshi/plugin'

// Base plugin with no dependencies
export default plugin({
  id: 'logger',
  setup: ctx => {
    console.log('1. Logger plugin loaded')
  },
  extension: () => ({
    log: msg => console.log(`[LOG] ${msg}`)
  })
})
```

cache plugin:

```js [cache.js]
import { plugin } from 'gunshi/plugin'

// Plugin with one required dependency
export default plugin({
  id: 'cache',
  dependencies: ['logger'],
  setup: ctx => {
    console.log('2. Cache plugin loaded (depends on logger)')
  },
  extension: ctx => ({
    get: key => {
      ctx.extensions.logger.log(`Cache get: ${key}`)
      return null
    }
  })
})
```

auth plugin:

```js [auth.js]
import { plugin } from 'gunshi/plugin'

// Plugin with multiple dependencies
export default plugin({
  id: 'auth',
  dependencies: ['logger', 'cache'],
  setup: ctx => {
    console.log('3. Auth plugin loaded (depends on logger, cache)')
  },
  extension: ctx => ({
    isAuthenticated: () => {
      ctx.extensions.logger.log('Checking authentication')
      ctx.extensions.cache.get('auth-token')
      return true
    }
  })
})
```

metrics plugin:

```js [metrics.js]
import { plugin } from 'gunshi/plugin'

// Plugin with optional dependency
export default plugin({
  id: 'metrics',
  dependencies: ['logger', { id: 'cache', optional: true }],
  setup: ctx => {
    console.log('4. Metrics plugin loaded (depends on logger, optionally cache)')
  },
  extension: ctx => ({
    track: event => {
      ctx.extensions.logger.log(`Tracking: ${event}`)
      // Use cache if available
      if (ctx.extensions.cache) {
        ctx.extensions.cache.get(`metrics:${event}`)
      }
    }
  })
})
```

api plugin:

```js [api.js]
import { plugin } from 'gunshi/plugin'

// Plugin that depends on other dependent plugins
export default plugin({
  id: 'api',
  dependencies: ['auth', 'metrics'],
  setup: ctx => {
    console.log('5. API plugin loaded (depends on auth, metrics)')
  },
  extension: ctx => ({
    request: endpoint => {
      if (ctx.extensions.auth.isAuthenticated()) {
        ctx.extensions.metrics.track(`api:${endpoint}`)
        return { success: true }
      }
      return { success: false }
    }
  })
})
```

Last, install all plugins on CLI application:

```js [cli.js]
import { cli, define } from 'gunshi'
import logger from './logger.js'
import cache from './cache.js'
import auth from './auth.js'
import metrics from './metrics.js'
import api from './api.js'

// Command to demonstrate plugin loading
const command = define({
  name: 'demo',
  run: ctx => {
    console.log('\n=== Command execution starts ===')

    // Use various plugin extensions
    ctx.extensions.logger.log('Command running')
    ctx.extensions.api.request('/users')

    console.log('=== Command execution ends ===')
  }
})

// Run with plugins in random order - Gunshi will resolve correct order
await cli(process.argv.slice(2), command, {
  plugins: [
    // Intentionally provide in wrong order
    api, // Depends on auth, metrics
    auth, // Depends on logger, cache
    metrics, // Depends on logger, optionally cache
    logger, // No dependencies
    cache // Depends on logger
  ]
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/plugins/dependencies).

Run your application with plugin:

```sh
node cli.js
1. Logger plugin loaded
2. Cache plugin loaded (depends on logger)
3. Auth plugin loaded (depends on logger, cache)
4. Metrics plugin loaded (depends on logger, optionally cache)
5. API plugin loaded (depends on auth, metrics)

=== Command execution starts ===
[LOG] Command running
[LOG] Checking authentication
[LOG] Cache get: auth-token
[LOG] Tracking: api:/users
[LOG] Cache get: metrics:api:/users
=== Command execution ends ===
```

This example demonstrates:

1. **Topological sorting**: Despite plugins being provided in wrong order, Gunshi resolves them correctly
2. **Dependency chain**: `api` → `auth` → `cache` → `logger` shows multi-level dependencies
3. **Optional dependencies**: `metrics` plugin works with or without `cache`
4. **Load order verification**: Setup messages show the actual resolution order
5. **Runtime interaction**: Extensions can access their dependencies safely

## Next Steps

You've learned how to manage plugin dependencies, including topological sorting, optional dependencies, and runtime interaction patterns. This knowledge enables you to build sophisticated plugin ecosystems where plugins collaborate effectively.

Next, dive into [Plugin Decorators](./decorators.md) to learn how plugins can wrap and enhance existing functionality, adding behaviors like authentication, logging, and caching to commands without modifying their core implementation.

---

---
url: /guide/plugin/decorators.md
---
# Plugin Decorators

Decorators are a powerful mechanism in Gunshi's plugin system that allows you to wrap and enhance existing functionality.

This guide explains how to effectively use decorators in your plugins.

## Understanding Decorator Mechanism

In Gunshi, decorators create a wrapping structure around the original functionality.

Gunshi implements two types of decorators with different processing methods:

* **Command Decorators**: Processed using `reduceRight`, creating a nested wrapper structure
* **Renderer Decorators**: Processed using a `for` loop, building a chain of transformations

## Command Decorators

Command decorators wrap command execution for cross-cutting concerns like logging, authentication, and error handling.

Unlike renderer decorators that only affect output formatting, command decorators can control the entire execution flow, including validation, authentication, logging, and error handling.

### How Command Decorators Work

Command decorators use the `decorateCommand()` method provided by the `PluginContext`.

Each decorator receives a runner function (the next decorator or original command) and returns a new function that wraps it:

```js
ctx.decorateCommand(runner => async ctx => {
  // Pre-execution logic
  console.log('Before command')

  // Call the next decorator or original command
  const result = await runner(ctx)

  // Post-execution logic
  console.log('After command')

  return result
})
```

### Command Decorator Execution Order

Gunshi applies command decorators using the `reduceRight` method, which processes the decorator array from the last element to the first.

This approach creates a nested wrapper structure where the first registered decorator becomes the outermost layer.

The following diagram illustrates the wrapper structure:

```mermaid
graph TB
    A["User Input"] --> B["Decorator A<br/>First registered - Outermost wrapper<br/>&nbsp;"]
    B --> C["Decorator B<br/>Second registered"]
    C --> D["Decorator C<br/>Last registered - Innermost wrapper<br/>&nbsp;"]
    D --> E["Original Command"]
    E --> F["Result"]

    style B fill:#9B59B6,stroke:#633974,stroke-width:2px,color:#fff
    style C fill:#4A90E2,stroke:#2E5A8E,stroke-width:2px,color:#fff
    style D fill:#468c56,stroke:#2e5936,stroke-width:2px,color:#fff
```

### Basic Command Decorator Example

The following example demonstrates the execution order when using `reduceRight`:

```js [plugin.js]
import { plugin } from 'gunshi/plugin'

export default plugin({
  id: 'my-plugin',
  setup(ctx) {
    // Registered first
    ctx.decorateCommand(runner => async ctx => {
      console.log('Decorator A: before')
      const result = await runner(ctx)
      console.log('Decorator A: after')
      return result
    })

    // Registered second
    ctx.decorateCommand(runner => async ctx => {
      console.log('Decorator B: before')
      const result = await runner(ctx)
      console.log('Decorator B: after')
      return result
    })

    // Registered third (executes first!)
    ctx.decorateCommand(runner => async ctx => {
      console.log('Decorator C: before')
      const result = await runner(ctx)
      console.log('Decorator C: after')
      return result
    })
  }
})
```

Application codes:

```js [cli.js]
import { cli } from 'gunshi'
import lifo from './plugin.js'

await cli(
  process.argv.slice(2),
  () => {
    console.log('Original command execution')
  },
  {
    plugins: [lifo]
  }
)
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/plugins/decorators/lifo).

When executed, `reduceRight` creates a wrapper structure where Decorator A wraps B, B wraps C, and C wraps the original command:

```sh
node cli.js
Decorator A: before    # Outermost wrapper executes first
Decorator B: before    # Middle wrapper
Decorator C: before    # Innermost wrapper
Original command execution
Decorator C: after     # Innermost completes first
Decorator B: after     # Middle completes
Decorator A: after     # Outermost completes last
```

### Advanced Command Decorator Example

Here's a complete example demonstrating how multiple command decorators work together for different purposes:

```js [plugin.js]
import { plugin } from 'gunshi/plugin'

const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))

export default plugin({
  id: 'multi-decorator',
  setup(ctx) {
    // First decorator: Logging
    ctx.decorateCommand(runner => async ctx => {
      console.log('[LOG] Command started:', ctx.name)
      const result = await runner(ctx)
      console.log('[LOG] Command completed')
      return result
    })

    // Second decorator: Timing
    ctx.decorateCommand(runner => async ctx => {
      const start = Date.now()
      await sleep(10)
      const result = await runner(ctx)
      console.log(`[TIME] Execution: ${Date.now() - start}ms`)
      return result
    })

    // Third decorator: Error wrapper
    ctx.decorateCommand(runner => async ctx => {
      try {
        console.log('[ERROR] Monitoring enabled')
        return await runner(ctx)
      } catch (error) {
        console.error('[ERROR] Command failed:', error.message)
        throw error
      }
    })
  }
})
```

```js [cli.js]
import { cli, define } from 'gunshi'
import multi from './plugin.js'

const command = define({
  name: 'process',
  run: ctx => {
    console.log('>>> Executing actual command <<<')
    return 'Command result'
  }
})

await cli(process.argv.slice(2), command, {
  plugins: [multi]
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/plugins/decorators/command).

Running `node cli.js` outputs:

```sh
[LOG] Command started: process
[ERROR] Monitoring enabled
>>> Executing actual command <<<
[TIME] Execution: 11ms
[LOG] Command completed
```

> \[!NOTE]
> The `@gunshi/plugin-global` plugin uses a command decorator to intercept `--help` and `--version` options, preventing normal command execution and triggering rendering instead.

## Renderer Decorators

Gunshi provides a powerful API for customizing how your CLI displays information through renderer decorators.

These decorators allow you to wrap and enhance the rendering of headers, usage/help messages, and validation errors, enabling consistent styling, branding, and enhanced user experience across your CLI application.

### How Renderer Decorators Work

Gunshi applies renderer decorators using a standard `for` loop that iterates through the decorator array from first to last.

Each iteration wraps the previous renderer function, building a chain of decorators.

This approach means that each decorator in the array wraps the accumulated result of all previous decorators, with each decorator receiving the previous renderer as its `baseRenderer` parameter.

### Available Renderer Decorator Methods

Gunshi provides three renderer decorator methods via `PluginContext`:

* **`decorateHeaderRenderer`**: Customizes command headers (title/branding)
* **`decorateUsageRenderer`**: Enhances usage and help message display
* **`decorateValidationErrorsRenderer`**: Formats validation error messages

Each decorator receives the base renderer function and must call it to maintain the decorator chain.

This ensures that multiple plugins can cooperatively enhance the output.

### Complete Rendering Customization Example

Here's a comprehensive example showing how to customize all three renderers in a single plugin.

This plugin adds branding to headers, appends metadata to usage messages, and enhances error formatting:

```js [plugin.js]
import { plugin } from 'gunshi/plugin'

export default plugin({
  id: 'custom-renderer',
  setup(ctx) {
    // Add branding to header
    ctx.decorateHeaderRenderer(async (baseRenderer, ctx) => {
      const header = await baseRenderer(ctx)
      return `🚀 My CLI v${ctx.env.version}\n${header}`
    })

    // Append timestamp to usage
    ctx.decorateUsageRenderer(async (baseRenderer, ctx) => {
      const usage = await baseRenderer(ctx)
      return `${usage}\n\nGenerated: ${new Date().toISOString()}`
    })

    // Format validation errors with emoji
    ctx.decorateValidationErrorsRenderer(async (baseRenderer, ctx, error) => {
      const errors = await baseRenderer(ctx, error)
      return `❌ Validation Error:\n${errors}`
    })
  }
})
```

Application code:

```js [cli.js]
import { cli, define } from 'gunshi'
import customRenderer from './plugin.js'

await cli(
  process.argv.slice(2),
  define({
    name: 'build',
    args: {
      output: { type: 'string', required: true }
    },
    run: ctx => console.log(`Building to ${ctx.values.output}`)
  }),
  {
    name: 'my-cli',
    version: '1.0.0',
    plugins: [customRenderer]
  }
)
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/plugins/decorators/renderers).

Run with `--help` to see customized output:

```sh
node cli.js --help
🚀 My CLI v1.0.0
my-cli (my-cli v1.0.0)

USAGE:
  my-cli <OPTIONS>

OPTIONS:
  -h, --help                 Display this help message
  -v, --version              Display this version
  --output <output>


Generated: 2025-08-15T14:26:43.121Z
```

### Multiple Plugin Decorator Execution Order

When multiple plugins register renderer decorators, the order matters.

Gunshi uses two built-in plugins by default: `@gunshi/plugin-global` (adds `--help` and `--version` options) and `@gunshi/plugin-renderer` (provides default rendering).

When you add your own plugins, they interact with these default plugins in a specific order based on how the `for` loop processes the decorators.

#### Plugin Registration and Decorator Chain Building

The following diagram shows how plugins are registered and how the `for` loop builds the decorator chain:

```mermaid
graph TB
    R1["1. plugin-global<br/>Command Decorator"]
    R2["2. plugin-renderer<br/>Renderer Decorators"]
    R3["3. custom-plugin-A<br/>Renderer Decorator"]
    R4["4. custom-plugin-B<br/>Renderer Decorator"]
    R1 --> R2
    R2 --> R3
    R3 --> R4

    style R1 fill:#9B59B6,stroke:#633974,stroke-width:2px,color:#fff
    style R2 fill:#4A90E2,stroke:#2E5A8E,stroke-width:2px,color:#fff
    style R3 fill:#E67E22,stroke:#A35D18,stroke-width:2px,color:#fff
    style R4 fill:#E67E22,stroke:#A35D18,stroke-width:2px,color:#fff
```

```mermaid
graph TB
    E1["Base Renderer<br/>empty string<br/>&nbsp;"]
    E2["plugin-renderer wraps base"]
    E3["custom-A wraps plugin-renderer"]
    E4["custom-B wraps custom-A"]
    E1 --> E2
    E2 --> E3
    E3 --> E4

    style E1 fill:#468c56,stroke:#2e5936,stroke-width:2px,color:#fff
    style E2 fill:#4A90E2,stroke:#2E5A8E,stroke-width:2px,color:#fff
    style E3 fill:#E67E22,stroke:#A35D18,stroke-width:2px,color:#fff
    style E4 fill:#E67E22,stroke:#A35D18,stroke-width:2px,color:#fff
```

#### How Default and Custom Plugins Interact

Here's an example showing how the default Gunshi plugins work together with custom plugins:

custom-plugin-A:

```js [plugin-a.js]
import { plugin } from 'gunshi/plugin'

export default plugin({
  id: 'custom-a',
  setup(ctx) {
    ctx.decorateUsageRenderer(async (baseRenderer, ctx) => {
      const usage = await baseRenderer(ctx) // Call next decorator first
      console.log('[custom-a] Decorating usage')
      return `${usage}\n📦 Enhanced by Plugin A`
    })
  }
})
```

custom-plugin-B:

```js [plugin-b.js]
import { plugin } from 'gunshi/plugin'

export default plugin({
  id: 'custom-b',
  setup(ctx) {
    ctx.decorateUsageRenderer(async (baseRenderer, ctx) => {
      const usage = await baseRenderer(ctx) // Call next decorator first
      console.log('[custom-b] Decorating usage')
      return `${usage}\n🎨 Styled by Plugin B`
    })
  }
})
```

Last, install all plugins on CLI application:

```js [cli.js]
import { cli, define } from 'gunshi' // Includes plugin-global and plugin-renderer by default
import pluginA from './plugin-a.js'
import pluginB from './plugin-b.js'

await cli(
  process.argv.slice(2),
  define({
    name: 'demo',
    run: () => console.log('Demo command')
  }),
  {
    name: 'my-cli',
    version: '1.0.0',
    renderHeader: null, // Disable default header rendering
    // Custom plugins are added after default plugins
    plugins: [pluginA, pluginB]
  }
)
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/plugins/decorators/multiple-order).

#### Execution Flow Breakdown

When you run `node index.js --help`, two different types of decorators work together:

**1. Command Decorator (`@gunshi/plugin-global`):**

* Intercepts the `--help` option
* Calls the renderer functions to generate output

**2. Renderer Decorators (chain built by for loop):**

The `for` loop builds a chain where:

* custom-plugin-B wraps custom-plugin-A
* custom-plugin-A wraps plugin-renderer
* plugin-renderer wraps the base renderer (empty string)

**Execution flow when each decorator calls `baseRenderer` first:**

1. custom-plugin-B decorator starts → calls `baseRenderer`
2. custom-plugin-A decorator starts → calls `baseRenderer`
3. plugin-renderer decorator executes → returns full usage
4. custom-plugin-A continues → logs and adds "📦 Enhanced by Plugin A"
5. custom-plugin-B continues → logs and adds "🎨 Styled by Plugin B"

The console output in this example:

```sh
[custom-a] Decorating usage    // Logs after its baseRenderer returns
[custom-b] Decorating usage    // Logs after its baseRenderer returns
```

And the final rendered output:

```sh
USAGE:
  my-cli <OPTIONS>

OPTIONS:
  -h, --help             Display this help message
  -v, --version          Display this version

📦 Enhanced by Plugin A
🎨 Styled by Plugin B
```

#### Understanding the Chain

The renderer decorator chain works differently than you might expect:

```js
// Actual execution flow for renderer decorators
const base = await baseRenderer(ctx) // Returns ""
const afterRenderer = await rendererDecorator(base, ctx) // Doesn't call base, returns full usage
const afterCustomA = await customADecorator(afterRenderer, ctx) // Adds "Enhanced by Plugin A"
const final = await customBDecorator(afterCustomA, ctx) // Adds "Styled by Plugin B"
```

> \[!NOTE]
> `@gunshi/plugin-global` uses a **command decorator** to handle `--help`/`--version` options, while `@gunshi/plugin-renderer` uses **renderer decorators** to format the output. The base renderer returns an empty string, and `@gunshi/plugin-renderer` provides the actual implementation.

> \[!IMPORTANT]
> Always call `baseRenderer` in your decorator to maintain the decorator chain. While `@gunshi/plugin-renderer` replaces the empty base renderer with full implementation, your custom decorators should enhance the output from previous decorators in the chain.

### Important Considerations

**Always call `baseRenderer` in your decorator to maintain the decorator chain. Skipping it will break other plugins that may depend on the output.**

> \[!NOTE]
> Renderer decorators have the lowest priority in Gunshi's rendering system. Command-level and CLI-level renderers will override plugin decorators. See [Rendering Customization](../advanced/custom-rendering.md) for details on renderer priority.

## Command vs Renderer Decorators

Understanding the difference between these two decorator types is crucial:

| Aspect         | Command Decorator                  | Renderer Decorator                      |
| -------------- | ---------------------------------- | --------------------------------------- |
| **Purpose**    | Wraps command execution            | Wraps output rendering                  |
| **Method**     | `ctx.decorateCommand()`            | `ctx.decorateUsageRenderer()`, etc.     |
| **Can modify** | Command behavior, flow control     | Output formatting only                  |
| **Can access** | Full CommandContext                | CommandContext + render-specific params |
| **Use cases**  | Auth, logging, validation, caching | Styling, i18n, branding                 |

## Next Steps

With decorators, you've learned how to wrap and enhance command behavior and rendering output. This mechanism enables cross-cutting concerns like authentication, logging, and custom formatting without modifying command implementations.

The next chapter, [Plugin Extensions](./extensions.md), will show you how plugins can share functionality with commands through context extensions, creating a communication channel between plugins and the rest of your CLI application.

---

---
url: /guide/plugin/extensions.md
---
# Plugin Extensions

Extensions are the primary mechanism for plugins to add functionality to the command context.

This guide explains how to create and use plugin extensions for type-safe inter-plugin communication.

## What are Extensions?

Extensions allow plugins to inject custom functionality into the `CommandContext` that becomes available to all commands and other plugins.

Each extension is namespaced by the plugin ID to prevent conflicts.

Here's a simple example showing the concept:

```js
import { plugin } from 'gunshi/plugin'
import { define } from 'gunshi'

// Plugin provides an extension
const loggerPlugin = plugin({
  id: 'logger',
  extension: () => ({
    log: msg => console.log(msg),
    error: msg => console.error(msg)
  })
})

// Commands can use the extension
const command = define({
  name: 'deploy',
  run: ctx => {
    // Access extension via plugin ID
    ctx.extensions.logger.log('Starting deployment...')
  }
})
```

Extensions enable:

* **Shared Functionality**: Provide common utilities (logging, caching, database access)
* **Plugin Composition**: Build plugins that work together
* **Type Safety**: Define clear contracts between plugins
* **State Management**: Maintain state across command execution

> \[!NOTE]
> For advanced type safety patterns and type-safe plugin communication, see the [Plugin Type System](./type-system.md) guide.

## Extension Lifecycle

Understanding when and how extensions are created is crucial for effective plugin development.

### Lifecycle Phases

> \[!NOTE]
> The steps mentioned below (H, I) refer to the complete CLI execution lifecycle documented in the [Plugin Lifecycle](./lifecycle.md) guide. Extensions are involved in the Execution Phase, which occurs after plugins are loaded and configured during the Setup Phase.

During command execution, extensions go through three distinct phases:

1. **Extension Creation (Step H)**: The `extension` factory function is called to create each plugin's extension
2. **Post-Extension Hook (Step H)**: The `onExtension` callback is executed after all extensions are created
3. **Command Execution (Step I)**: The actual command runs with all extensions available

The following diagram illustrates the relationship between `extension` and `onExtension`:

```mermaid
graph TD
    subgraph " "
        A1[Plugin A: extension factory] --> A2[Attach to ctx.extensions.A]
        A2 --> A3[Plugin A: onExtension]
        A3 --> B1[Plugin B: extension factory]
        B1 --> B2[Attach to ctx.extensions.B]
        B2 --> B3[Plugin B: onExtension]
        B3 --> C1[Plugin C: extension factory]
        C1 --> C2[Attach to ctx.extensions.C]
        C2 --> C3[Plugin C: onExtension]
    end

    C3 --> CMD[Command Execution]

    style A1 fill:#468c56,color:white
    style B1 fill:#468c56,color:white
    style C1 fill:#468c56,color:white
    style A3 fill:#9B59B6,stroke:#633974,stroke-width:2px,color:#fff
    style B3 fill:#9B59B6,stroke:#633974,stroke-width:2px,color:#fff
    style C3 fill:#9B59B6,stroke:#633974,stroke-width:2px,color:#fff
    style CMD fill:#3498db,color:white
```

### Execution Order Guarantees

Gunshi processes plugins sequentially in dependency order, ensuring dependencies are always resolved before dependents:

1. **Plugins are sorted by dependencies** - Dependencies are processed before plugins that depend on them
2. **For each plugin in order**:
   a. The plugin's `extension` factory is called
   b. The extension result is immediately attached to `ctx.extensions[pluginId]`
   c. The plugin's `onExtension` callback runs (if defined) with access to its own extension and all dependency extensions
3. **Command execution** - The command executes only after all plugins have been processed

This ensures that:

* When a plugin's `onExtension` runs, it has access to:
  * Its own extension (just created)
  * All dependency extensions (already processed)
* Dependencies are always initialized before dependents
* The execution order respects the dependency graph
* Commands have a fully initialized context with all extensions

> \[!IMPORTANT]
> A plugin's `onExtension` callback does NOT have access to extensions from plugins that depend on it, as those are processed later in the sequence.

## Creating Extensions

> \[!TIP]
> **It's strongly recommended to define your extension interfaces using TypeScript.** This benefits all users: end users get IDE autocompletion and compile-time error detection when using your extension, plugin users receive type safety guarantees, and other plugin developers can build on top of your plugin with confidence.

### The `extension` Factory

The `extension` factory function is called during Step H to create an extension object that becomes available through `ctx.extensions`. This is where you can:

* Create fresh instances for each command execution
* Access parsed arguments and command information
* Access extensions from dependent plugins
* Initialize resources synchronously or asynchronously
* Return methods and properties for other plugins and commands to use

```ts [metrics.ts]
import { plugin } from 'gunshi/plugin'

export default plugin({
  id: 'metrics',

  extension: (ctx, cmd) => {
    // Called during Step H: Create Extensions
    // Fresh instance for each command execution

    const startTime = Date.now()
    const commandName = cmd.name || 'root'

    // Access parsed command-line arguments
    const verbose = ctx.values.verbose === true

    // Return the extension object (can be sync or async)
    return {
      recordMetric: (name: string, value: number) => {
        if (verbose) {
          console.log(`[${commandName}] ${name}: ${value}`)
        }
      },
      getElapsedTime: () => Date.now() - startTime
    }
  }
})
```

### The `onExtension` Hook

The `onExtension` callback runs after all extensions are created and attached to the context. This is where you can:

* Access your own extension via `ctx.extensions`
* Interact with other plugin extensions
* Perform initialization that depends on the complete context
* Set up resources needed before command execution

```ts [database.ts]
import { plugin } from 'gunshi/plugin'

export default plugin({
  id: 'database',
  dependencies: [
    { id: 'logger', optional: true } // Optional dependency
  ],

  extension: () => {
    // Create the extension object
    const pool = createPool()

    return {
      query: (sql: string) => pool.query(sql),
      connect: () => pool.connect(),
      disconnect: () => pool.disconnect()
    }
  },

  onExtension: async (ctx, cmd) => {
    // Called during Step H: Execute onExtension
    // All extensions are now available

    // Access your own extension
    const db = ctx.extensions.database

    // Interact with other extensions if available
    // Note: ctx.extensions.logger is only available here if the logger plugin
    // was processed before this plugin (as a dependency or earlier in registration)
    if (ctx.extensions.logger) {
      ctx.extensions.logger.log('Database plugin initialized')
    }

    // Perform command-specific initialization
    if (cmd.name === 'migrate' || cmd.name === 'seed') {
      await db.connect()

      if (ctx.extensions.logger) {
        ctx.extensions.logger.log('Database connected')
      }
    }
  }
})
```

### Basic Extension

Start with a simple extension that provides basic functionality:

```ts [logger.ts]
import { plugin } from 'gunshi/plugin'

// Define the extension interface
export interface LoggerExtension {
  log: (message: string) => void
  error: (message: string) => void
  warn: (message: string) => void
  debug: (message: string) => void
}

// Export for other plugins to use
export const pluginId = 'logger' as const
export type PluginId = typeof pluginId

// Implement the extension
export default plugin({
  id: pluginId,
  extension: (): LoggerExtension => ({
    log: msg => console.log(msg),
    error: msg => console.error(msg),
    warn: msg => console.warn(msg),
    debug: msg => console.debug(msg)
  })
})
```

### Using Command Context and Parameters

Extensions can access the `ctx` and `cmd` parameters to adapt their behavior based on command-line arguments and command configuration:

```ts [cache.ts]
import { plugin } from 'gunshi/plugin'

export interface CacheExtension {
  get: <T>(key: string) => T | undefined
  set: <T>(key: string, value: T) => void
  clear: () => void
  size: () => number
}

export default plugin({
  id: 'cache',

  extension: (ctx, cmd) => {
    // Create command-specific cache
    const cache = new Map<string, unknown>()
    const commandName = cmd.name || 'global'
    const debug = ctx.values.debug === true

    return {
      get: <T>(key: string): T | undefined => {
        const value = cache.get(key) as T | undefined
        if (debug && value !== undefined) {
          console.log(`[${commandName}] Cache hit: ${key}`)
        }
        return value
      },

      set: <T>(key: string, value: T) => {
        cache.set(key, value)
        if (debug) {
          console.log(`[${commandName}] Cache set: ${key}`)
        }
      },

      clear: () => cache.clear(),
      size: () => cache.size
    }
  }
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/plugins/extensions).

### Reading a Global Option Your Plugin Registered

A global option is merged into the arguments of every command, and a command may declare an argument of its own under the same name. The command's argument then **replaces** the global option, and `ctx.values[name]` holds the command's value — not your plugin's flag. Reading it anyway makes the plugin act on a value that was never meant for it.

`ctx.env.globalOptions` says which global options are in effect for the command that is running:

```ts [debug.ts]
import { plugin } from 'gunshi/plugin'

const OPTION_NAME = 'debug'

export default plugin({
  id: 'debug',

  setup: ctx => {
    ctx.addGlobalOption(OPTION_NAME, { type: 'boolean', description: 'Enable debug output' })
  },

  extension: ctx => {
    // `undefined` when the context was built on its own, as in a plugin's own unit tests
    const inEffect = ctx.env.globalOptions?.has(OPTION_NAME) ?? true
    if (!inEffect) {
      console.warn(
        `The command "${ctx.name ?? ''}" declares an argument called "${OPTION_NAME}", which replaces the global option of this plugin.`
      )
    }

    const debug = inEffect && ctx.values[OPTION_NAME] === true
    return {
      log: (message: string) => {
        if (debug) {
          console.log(`[debug] ${message}`)
        }
      }
    }
  }
})
```

Three things are worth keeping to:

* **Fall back to "in effect" when the map is absent.** A `CommandContext` built directly with `createCommandContext()` carries no `globalOptions`, and a plugin's own tests usually do that.
* **Say something when the name was taken.** It is the author of the CLI who can fix it, and nothing else tells them. Use `console.warn`, because `ctx.log` is silenced by `usageSilent`.
* **Offer a way out.** A plugin that lets the option be renamed — `dryrun({ name: 'pretend' })`, say — should name that in the warning.

The schema in the map is the one in effect, which may differ from the one you registered: a global option gives up its short name to an argument of the command that claims the same letter, and it is still in effect under its long name.

`@gunshi/plugin-dryrun` is the worked example of all of this.

## Next Steps

You've mastered extensions—the powerful mechanism for sharing functionality between plugins and commands. With extensions, your plugins can provide APIs, services, and utilities that enhance the entire CLI ecosystem.

Now it's time to ensure your plugins are type-safe. The next chapter, [Plugin Type System](./type-system.md), will show you how to leverage TypeScript's type system to create plugins with compile-time safety and excellent IDE support.

---

---
url: /guide/plugin/type-system.md
---
# Plugin Type System

Gunshi's plugin system leverages TypeScript's advanced type system to provide complete type safety.

This guide explains how to create type-safe plugins with proper type definitions.

## Introduction

Gunshi is designed with a **TypeScript-first** philosophy, providing:

* **Type inference** for plugin extensions and dependencies
* **Compile-time validation** of plugin interactions
* **IntelliSense support** throughout development
* **Type-safe plugin communication** between plugins

This guide focuses on TypeScript's type system for plugin development.

## Basic Type Definitions

Every type-safe plugin starts with two fundamental type definitions:

### Plugin ID and Extension Interface

The following code shows how to define and export a plugin's ID and extension interface in a separate types file:

```ts [types.ts]
// Define and export your plugin's types
export const pluginId = 'mycompany:logger' as const
export type PluginId = typeof pluginId

export interface LoggerExtension {
  log: (message: string) => void
  error: (message: string) => void
  warn: (message: string) => void
  debug: (message: string) => void
}
```

**Key principles:**

* Literal types (`as const`) enable TypeScript to track specific plugin IDs
  * Without `as const`, TypeScript widens the type to `string`, losing the specific ID value
  * Literal types allow TypeScript to infer the exact key when accessing `ctx.extensions['mycompany:logger']`
  * This enables autocomplete for available extensions and compile-time validation of plugin ID references
* Exported types allow other plugins and commands to reference your plugin
* Well-defined interfaces provide IntelliSense and compile-time validation

> \[!TIP]
> Plugin consumers can use these exported interfaces to type their command context's extensions, enabling type-safe access to plugin functionality in their command runners. For detailed usage patterns of type-safe command definitions with plugin extensions, see [Advanced Type System](../advanced/type-system.md).

## The `plugin` Function Type Parameters

The `plugin` function uses TypeScript's generics to ensure complete type safety through four type parameters:

```ts
plugin<
  DependencyExtensions, // Extensions from dependencies
  PluginId, // Literal plugin ID
  Dependencies, // Dependency array type
  Extension // This plugin's extension type
>(options)
```

Each parameter serves a specific purpose:

* **DependencyExtensions**: Types of extensions this plugin depends on
* **PluginId**: The literal type of this plugin's ID
* **Dependencies**: The literal type of the dependencies array
* **Extension**: The type of extension this plugin provides

### Why These Type Parameters Are Necessary

While TypeScript can infer some types automatically, explicitly specifying all four type parameters provides several critical benefits:

1. **Complete Type Safety**: Ensures that dependency access in your extension is fully typed
2. **Compile-time Validation**: Catches plugin ID mismatches and missing dependencies before runtime
3. **Better IntelliSense**: Provides accurate autocompletion for `ctx.extensions` access
4. **Clear API Contracts**: Makes plugin dependencies and provided extensions explicit

### What Happens When Type Parameters Are Omitted

If you omit type parameters, TypeScript falls back to default or inferred types:

```ts
import { plugin } from 'gunshi/plugin'

// Without type parameters - loses type safety
const plugin1 = plugin({
  id: 'my-plugin',
  dependencies: ['other-plugin'],
  extension: ctx => ({
    method: () => {
      // ctx.extensions['other-plugin'] is typed as 'any'
      const other = ctx.extensions['other-plugin'] // No type checking!
      return other.someMethod() // No IntelliSense, no error if method doesn't exist
    }
  })
})

// With type parameters - full type safety
const plugin2 = plugin<
  { 'other-plugin': OtherExtension },
  'my-plugin',
  ['other-plugin'],
  MyExtension
>({
  id: 'my-plugin',
  dependencies: ['other-plugin'],
  extension: ctx => ({
    method: () => {
      // ctx.extensions['other-plugin'] is typed as OtherExtension
      const other = ctx.extensions['other-plugin'] // Fully typed!
      return other.someMethod() // IntelliSense works, compile error if method doesn't exist
    }
  })
})
```

Without explicit type parameters:

* Dependencies are not type-checked against actual usage
* Extension access returns `any` type, losing all type safety
* Plugin IDs are treated as generic strings rather than literal types
* No compile-time validation of plugin interactions

## Progressive Type Safety Examples

Let's explore these type parameters through increasingly complex examples:

### 1. Simple Plugin (No Dependencies)

This example demonstrates a basic plugin without any dependencies, using only the essential type parameters:

```ts
import { plugin } from 'gunshi/plugin'
import { pluginId } from './types.ts'

import type { PluginId, LoggerExtension } from './types.ts'

export default function logger() {
  return plugin<{}, PluginId, [], LoggerExtension>({
    id: pluginId,
    name: 'Logger Plugin',

    extension: (): LoggerExtension => ({
      log: msg => console.log(`[LOG] ${msg}`),
      error: msg => console.error(`[ERROR] ${msg}`),
      warn: msg => console.warn(`[WARN] ${msg}`),
      debug: msg => console.debug(`[DEBUG] ${msg}`)
    })
  })
}
```

### 2. Plugin with Dependencies

This example shows how to declare and use dependencies with proper type definitions:

```ts [api.ts]
import { plugin } from 'gunshi/plugin'
import { pluginId as loggerId } from '@mycompany/plugin-logger'
import { pluginId as authId } from '@mycompany/plugin-auth'

import type { LoggerExtension } from '@mycompany/plugin-logger'
import type { AuthExtension } from '@mycompany/plugin-auth'

export const pluginId = 'mycompany:api' as const
export type PluginId = typeof pluginId

export interface ApiExtension {
  get: <T = unknown>(endpoint: string) => Promise<T>
  post: <T = unknown>(endpoint: string, data: unknown) => Promise<T>
}

// Define dependency types using object notation
type DependencyExtensions = {
  [loggerId]: LoggerExtension
  [authId]: AuthExtension
}

// Define dependencies array
const dependencies = [loggerId, authId] as const
type Dependencies = typeof dependencies

export default function api() {
  return plugin<DependencyExtensions, PluginId, Dependencies, ApiExtension>({
    id: pluginId,
    dependencies,

    extension: ctx => {
      const logger = ctx.extensions[loggerId] // Fully typed!
      const auth = ctx.extensions[authId] // Fully typed!

      return {
        get: async endpoint => {
          logger.log(`GET ${endpoint}`)
          const token = auth.getToken()
          // Implementation...
        },
        post: async (endpoint, data) => {
          logger.log(`POST ${endpoint}`)
          // Implementation...
        }
      }
    }
  })
}
```

### 3. Plugin with Optional Dependencies

Gunshi supports both required and optional plugin dependencies with full type safety.

The following example shows how to define both required and optional dependencies with their corresponding TypeScript types:

```ts [metrics.ts]
import { plugin } from 'gunshi/plugin'
import { pluginId as loggerId } from './logger.ts'
import { pluginId as cacheId } from './cache.ts'

import type { LoggerExtension } from './logger.ts'
import type { CacheExtension } from './cache.ts'

// Type definition: cache is optional
type DependencyExtensions = {
  [loggerId]: LoggerExtension
  [cacheId]?: CacheExtension // Optional with ?
}

// Runtime declaration: must match types
const dependencies = [
  loggerId, // Required
  { id: cacheId, optional: true } // Optional
] as const

export const pluginId = 'mycompany:metrics' as const
export type PluginId = typeof pluginId

export interface MetricsExtension {
  // ...
}

export default function metrics() {
  return plugin<DependencyExtensions, typeof pluginId, typeof dependencies, MetricsExtension>({
    id: pluginId,
    dependencies,

    extension: ctx => {
      const logger = ctx.extensions[loggerId] // Always defined
      const cache = ctx.extensions[cacheId] // Possibly undefined

      return {
        track: (event: string) => {
          logger.log(`Event: ${event}`)

          // Safe optional access
          if (cache) {
            cache.set(`event:${event}`, Date.now())
          }
        }
      }
    }
  })
}
```

### 4. Dependency Chain

Plugins can depend on other plugins that have their own dependencies.

This example demonstrates a three-level dependency chain where each plugin builds on the previous ones:

```ts [base.ts]
// No dependencies
export const baseId = 'base' as const
export interface BaseExtension {
  getConfig: () => Config
}
```

```ts [logger.ts]
import { plugin } from 'gunshi/plugin'
import { baseId } from './base.ts'

import type { BaseExtension } from './base.ts'

// Depends on base
export const loggerId = 'logger' as const
export interface LoggerExtension {
  log: (msg: string) => void
}

const loggerDeps = [baseId] as const

export default plugin<
  { [baseId]: BaseExtension },
  typeof loggerId,
  typeof loggerDeps,
  LoggerExtension
>({
  id: loggerId,
  dependencies: loggerDeps,
  extension: ctx => {
    const config = ctx.extensions[baseId].getConfig()
    return {
      log: msg => {
        if (config.verbose) console.log(msg)
      }
    }
  }
})
```

```ts [api.ts]
import { plugin } from 'gunshi/plugin'
import { baseId } from './base.ts'
import { loggerId } from './logger.ts'

import type { BaseExtension } from './base.ts'
import type { LoggerExtension } from './logger.ts'

export const apiId = 'api' as const

export interface ApiExtension {
  request: (url: string) => Promise<void> | void
}

// Depends on both
const apiDeps = [baseId, loggerId] as const

export default plugin<
  {
    [baseId]: BaseExtension
    [loggerId]: LoggerExtension
  },
  typeof apiId,
  typeof apiDeps,
  ApiExtension
>({
  id: apiId,
  dependencies: apiDeps,
  extension: ctx => {
    const logger = ctx.extensions[loggerId]
    const config = ctx.extensions[baseId].getConfig()

    return {
      request: async (url: string) => {
        logger.log(`API Request: ${url}`)
        // Implementation...
      }
    }
  }
})
```

## Complete Example

This example demonstrates all concepts together: type definitions, all four type parameters, and dependency management.

The following code shows a production-ready API plugin with proper type exports, dependency handling, and complete implementation:

```ts [types.ts]
// Type definitions for the API plugin
export const pluginId = 'mycompany:api' as const
export type PluginId = typeof pluginId

export interface ApiExtension {
  get: <T = unknown>(endpoint: string) => Promise<T>
  post: <T = unknown>(endpoint: string, data: unknown) => Promise<T>
  delete: (endpoint: string) => Promise<void>
}
```

```ts [api.ts]
import { plugin } from 'gunshi/plugin'
import { pluginId } from './types.ts'
import { pluginId as loggerId } from './logger.ts'
import { pluginId as authId } from './auth.ts'

import type { PluginId, ApiExtension } from './types.ts'
import type { LoggerExtension } from './logger.ts'
import type { AuthExtension } from './auth.ts'

// Re-export for consumers
export * from './types.ts'

// Define dependency types
type DependencyExtensions = {
  [loggerId]: LoggerExtension // Required
  [authId]: AuthExtension // Required
}

// Define dependencies array
const dependencies = [loggerId, authId] as const
type Dependencies = typeof dependencies

// Export the plugin factory
export default function api(baseUrl: string) {
  return plugin<DependencyExtensions, PluginId, Dependencies, ApiExtension>({
    id: pluginId,
    name: 'API Plugin',
    dependencies,

    extension: ctx => {
      const logger = ctx.extensions[loggerId]
      const auth = ctx.extensions[authId]

      async function request<T = unknown>(
        method: string,
        endpoint: string,
        data?: Record<string, unknown>
      ) {
        const url = `${baseUrl}${endpoint}`

        // Make request
        logger.log(`${method} ${url}`)
        const token = auth.getToken()

        // Simulate API call (replace with actual fetch in production)
        const result = await simulateApiCall(method, endpoint, data || {}, token)

        return result as T
      }

      return {
        get: endpoint => request('GET', endpoint),
        post: (endpoint, data) => request('POST', endpoint, data),
        delete: async endpoint => {
          await request('DELETE', endpoint)
        }
      }
    }
  })
}
```

Usage in your CLI application:

```ts [cli.ts]
import { cli, define } from 'gunshi'
import api, { pluginId as apiId } from './api.ts'
import auth from './auth.ts'
import logger from './logger.ts'

import type { Args, GunshiParams } from 'gunshi'
import type { ApiExtension } from './api.ts'

const fetchArgs = {
  endpoint: {
    type: 'string',
    required: true,
    description: 'API endpoint to fetch'
  }
} as const satisfies Args

// Define a command that uses the API plugin
const fetchCommand = define<
  GunshiParams<{
    args: typeof fetchArgs
    extensions: { [apiId]: ApiExtension }
  }>
>({
  name: 'fetch',
  description: 'Fetch data from API',
  args: fetchArgs,
  run: async ctx => {
    const api = ctx.extensions[apiId]
    const data = await api.get(ctx.values.endpoint)
    console.log(JSON.stringify(data, null, 2))
  }
})

// Configure and run CLI
await cli(process.argv.slice(2), fetchCommand, {
  name: 'my-cli',
  version: '1.0.0',
  plugins: [
    // Dependencies must be registered first
    logger(),
    auth({ token: process.env.API_TOKEN }),
    api('https://api.example.com')
  ]
})
```

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/plugins/type-system).

When executed, the plugins work together seamlessly:

```sh
API_TOKEN=xxx npx tsx cli.ts fetch --endpoint /users
my-cli (my-cli v1.0.0)

[LOG] GET https://api.example.com/users
[
  {
    "id": 1,
    "name": "Alice"
  },
  {
    "id": 2,
    "name": "Bob"
  }
]

API_TOKEN=xxx npx tsx cli.ts fetch --endpoint /users/1
my-cli (my-cli v1.0.0)

[LOG] GET https://api.example.com/users/1
{
  "id": 1,
  "name": "Alice"
}
```

## Next Steps

With a strong foundation in type-safe plugin development, you've learned how to create plugins that provide compile-time guarantees and excellent developer experience through TypeScript's type system.

Before sharing your plugins with others, it's crucial to ensure they work correctly. The next chapter, [Plugin Testing](./testing.md), will guide you through comprehensive testing strategies for plugins, including unit tests, integration tests, and testing plugin interactions.

---

---
url: /guide/plugin/testing.md
---
# Plugin Testing

Testing is crucial for ensuring plugin reliability and maintainability. This guide covers practical testing approaches for Gunshi plugins.

> \[!IMPORTANT]
> The code examples in this guide focus on demonstrating testing patterns and techniques. For clarity and brevity, some examples may not include extensive explanations that would normally be present in Gunshi's documentation. The emphasis is on showing practical testing approaches rather than following all documentation style guidelines.

> \[!NOTE]
> This guide uses [Vitest](https://vitest.dev/) as the testing framework. The concepts can be adapted to other testing frameworks.

> \[!NOTE]
> Some code examples include TypeScript file extensions (`.ts`) in `import`/`export` statements. If you use this pattern, enable `allowImportingTsExtensions` in your `tsconfig.json`.

## Plugin Testing Fundamentals

Every Gunshi plugin requires thorough testing to ensure it integrates correctly with the CLI framework and behaves reliably across different scenarios. This section covers the essential concepts and basic testing approaches that form the foundation of plugin testing. You'll learn how to structure tests for plugins, use the testing utilities provided by Gunshi, and establish a solid testing foundation that scales with your plugin's complexity.

### Basic Plugin Structure

The following example demonstrates a minimal plugin structure that serves as our testing subject:

```ts [src/plugin.ts]
import { plugin } from 'gunshi/plugin'

export function myPlugin(options = {}) {
  return plugin({
    id: 'my-plugin',
    name: 'My Plugin',
    extension: (ctx, cmd) => ({
      greet: (name: string) => `Hello, ${name}!`
    })
  })
}
```

### Writing Your First Test

The following test file demonstrates basic plugin testing, including initialization and extension factory verification:

```ts [src/plugin.test.ts]
import { createCommandContext } from 'gunshi/plugin'
import { define } from 'gunshi'
import { describe, expect, test, vi } from 'vitest'
import { myPlugin } from './plugin.ts'

describe('plugin initialization', () => {
  test('create plugin with default options', () => {
    const plugin = myPlugin()

    expect(plugin.id).toBe('my-plugin')
    expect(plugin.name).toBe('My Plugin')
    expect(plugin.extension.factory).toBeDefined()
  })

  test('plugin extension factory creates correct methods', async () => {
    const plugin = myPlugin()
    const mockCommand = define({
      name: 'test',
      description: 'Test command',
      run: vi.fn()
    })

    const mockContext = await createCommandContext({
      command: mockCommand
    })

    const extension = await plugin.extension.factory(mockContext, mockCommand)

    expect(extension.greet).toBeDefined()
    expect(typeof extension.greet).toBe('function')
    expect(extension.greet('World')).toBe('Hello, World!')
  })
})
```

### Moving Beyond Basic Tests

The example above demonstrates fundamental plugin testing. As your plugins grow more complex, you'll need to test additional aspects to ensure reliability and maintainability. The following sections cover comprehensive testing approaches for:

* Plugin configuration - Validating options and handling invalid inputs
* Extension behaviors - Testing complex extension methods and async operations
* Lifecycle management - Verifying setup functions and onExtension callbacks
* Decorator patterns - Testing command and renderer decorators
* Integration scenarios - Ensuring plugins work correctly with real CLI instances

Each section includes practical examples and testing techniques you can adapt to your plugins. To run your tests after implementing them, use:

```sh
# Run all tests
vitest run
```

Let's start by exploring how to test plugin configuration validation.

## Testing Plugin Configuration

Plugins often accept configuration options that modify their behavior, validate input, or declare dependencies on other plugins. Robust configuration testing ensures your plugin handles both valid and invalid inputs gracefully, properly validates options at creation time, and correctly declares its dependencies. This section demonstrates comprehensive approaches to testing all aspects of plugin configuration, from basic validation to complex dependency scenarios.

### Configuration Validation

Plugins should validate configuration during creation:

```ts [src/plugin.ts]
import { plugin } from 'gunshi/plugin'

export function myValidatingPlugin(options: { locale: string; timeout?: number }) {
  if (options.locale && !/^[a-z]{2}-[A-Z]{2}$/.test(options.locale)) {
    throw new Error('Invalid locale format')
  }
  if (options.timeout !== undefined && options.timeout < 0) {
    throw new Error('Timeout must be positive')
  }

  return plugin({
    id: 'validating-plugin',
    name: 'Validating Plugin',
    extension: (ctx, cmd) => ({
      validate: () => true,
      config: options
    })
  })
}
```

### Testing Configuration Behavior

Test your configuration validation logic with these testing approaches:

```ts [src/plugin.test.ts]
import { createCommandContext } from 'gunshi/plugin'
import { describe, expect, test, vi } from 'vitest'
import { myValidatingPlugin } from './plugin.ts'

describe('configuration validation', () => {
  test('validates configuration at creation time', () => {
    expect(() => myValidatingPlugin({ locale: 'invalid' })).toThrow('Invalid locale format')
    expect(() => myValidatingPlugin({ locale: 'en-US', timeout: -1 })).toThrow(
      'Timeout must be positive'
    )
  })

  test('plugin uses configuration in extension', async () => {
    const plugin = myValidatingPlugin({ locale: 'ja-JP', timeout: 5000 })
    const mockCommand = define({ name: 'test', description: 'Test', run: vi.fn() })

    const ctx = await createCommandContext({ command: mockCommand })
    const extension = await plugin.extension.factory(ctx, mockCommand)

    expect(extension.config.locale).toBe('ja-JP')
    expect(extension.config.timeout).toBe(5000)
  })
})
```

### Dependency Declaration

Define a plugin with dependencies using the following structure:

```ts [src/plugin.ts]
import { plugin } from 'gunshi/plugin'

export function myPluginWithDependencies() {
  return plugin({
    id: 'dependent-plugin',
    name: 'Dependent Plugin',
    dependencies: ['plugin-renderer', { id: 'plugin-i18n', optional: true }],
    extension: (ctx, cmd) => ({
      render: () => 'rendered'
    })
  })
}
```

Test dependency declarations:

```ts [src/plugin.test.ts]
import { describe, expect, test } from 'vitest'
import { myPluginWithDependencies } from './plugin.ts'

describe('dependency declaration', () => {
  test('declares dependencies correctly', () => {
    const plugin = myPluginWithDependencies()

    expect(plugin.dependencies).toContain('plugin-renderer')
    const optionalDep = plugin.dependencies?.find(dep => typeof dep === 'object' && dep.optional)
    expect(optionalDep).toEqual({ id: 'plugin-i18n', optional: true })
  })
})
```

## Testing Extensions

Extensions are the heart of Gunshi plugins, providing the actual functionality that commands can use. Testing extensions requires special attention to their interaction with the command context, handling of asynchronous operations, and proper state management. This section explores various patterns for testing extensions using the `createCommandContext` helper, covering both simple synchronous methods and complex asynchronous workflows that interact with external resources.

### Testing with `createCommandContext`

The `createCommandContext` helper provides a complete context for testing extensions:

```ts [src/plugin.test.ts]
import { createCommandContext } from 'gunshi/plugin'
import { expect, test } from 'vitest'
import { myPlugin } from './plugin.ts'

test('extension factory creates correct extension', async () => {
  const plugin = myPlugin({ debug: true })

  const command = define({ name: 'test', description: 'Test', run: vi.fn() })
  const ctx = await createCommandContext({
    command,
    values: { verbose: true },
    cliOptions: {
      version: '1.0.0'
    }
  })

  const extension = await plugin.extension.factory(ctx, command)

  expect(extension.someMethod).toBeDefined()
  const result = extension.someMethod()
  expect(result).toBe('expected value')
})
```

### Testing Complex Extension Methods

The following example demonstrates how to test extension methods that interact with the command context:

```ts [src/plugin.test.ts]
import { createCommandContext } from 'gunshi/plugin'
import { define } from 'gunshi'
import { describe, expect, test, vi } from 'vitest'
import { myPlugin } from './plugin.ts'

describe('extension methods', () => {
  test('showVersion displays version correctly', async () => {
    const plugin = myPlugin()

    const command = define({ name: 'app', description: 'App', run: vi.fn() })
    const ctx = await createCommandContext({
      command,
      cliOptions: { version: '2.0.0', name: 'test-app' }
    })

    const extension = await plugin.extension.factory(ctx, command)
    const result = extension.showVersion()

    expect(result).toBe('2.0.0')
  })

  test('handles missing version', async () => {
    const plugin = myPlugin()

    const command = define({ name: 'app', description: 'App', run: vi.fn() })
    const ctx = await createCommandContext({
      command,
      cliOptions: { version: undefined, name: 'test-app' }
    })

    const extension = await plugin.extension.factory(ctx, command)
    const result = extension.showVersion()

    expect(result).toBe('unknown')
  })
})
```

### Testing Async Extensions

The following examples show how to test asynchronous extension factories that load configuration and handle errors:

```ts [src/plugin.test.ts]
import { createCommandContext } from 'gunshi/plugin'
import { describe, expect, test, vi } from 'vitest'
import myPlugin from './plugin.ts'

describe('async extension', () => {
  test('extension factory loads configuration', async () => {
    const loadConfig = vi.fn().mockReturnValue({
      apiUrl: 'https://api.example.com',
      timeout: 5000
    })
    const plugin = myPlugin({ loadConfig })
    const command = define({ name: 'test', description: 'Test', run: vi.fn() })
    const ctx = await createCommandContext({ command })
    const extension = await plugin.extension.factory(ctx, command)

    expect(loadConfig).toHaveBeenCalled()
    expect(extension.getConfig()).toEqual({
      apiUrl: 'https://api.example.com',
      timeout: 5000
    })
  })

  test('handles initialization errors gracefully', async () => {
    const warnMock = vi.spyOn(console, 'warn').mockImplementation(() => {})
    const loadConfig = vi.fn().mockRejectedValue(new Error('Config not found'))
    const plugin = myPlugin({ loadConfig })
    const command = define({ name: 'test', description: 'Test', run: vi.fn() })
    const ctx = await createCommandContext({ command })
    const extension = await plugin.extension.factory(ctx, command)

    expect(extension.getConfig()).toEqual({
      apiUrl: 'http://localhost:3000',
      timeout: 3000
    })
    expect(warnMock).toHaveBeenCalledWith('Failed to load config:', expect.any(Error))
  })
})
```

## Testing Lifecycle

Gunshi plugins follow a specific lifecycle with distinct phases: initialization through the setup function and post-creation callbacks via onExtension. Understanding and testing these lifecycle hooks is essential for plugins that modify the CLI structure, add global options, or maintain shared state across commands.

This section covers strategies for testing each lifecycle phase and ensuring your plugin integrates seamlessly with the CLI initialization process.

### Testing the `setup` Function

The `setup` function runs when the plugin is registered:

```ts [src/plugin.ts]
import { plugin } from 'gunshi/plugin'

export interface DebuggablePluginOptions {
  enable?: boolean
}

export function debuggablePlugin({ enable = true }: DebuggablePluginOptions) {
  return plugin({
    id: 'debuggable-plugin',
    name: 'Debuggable Plugin',
    setup: ctx => {
      if (enable) {
        ctx.addGlobalOption('debug', {
          type: 'boolean',
          description: 'Enable debug mode',
          default: false
        })
      }
    }
  })
}
```

Test `setup` behavior:

```ts [src/plugin.test.ts]
import { createCommandContext } from 'gunshi/plugin'
import { describe, expect, test, vi } from 'vitest'
import { debuggablePlugin } from './plugin.ts'

// Mockup PluginContext
function mockPluginContext(): PluginContext {
  return {
    subCommands: new Map(),
    globalOptions: new Map(),
    addGlobalOption: vi.fn(),
    addCommand: vi.fn(),
    hasCommand: vi.fn(),
    decorateCommand: vi.fn(),
    decorateUsageRenderer: vi.fn(),
    decorateHeaderRenderer: vi.fn(),
    decorateValidationErrorsRenderer: vi.fn()
  }
}

describe('debuggable plugin', () => {
  test('enable debug option', async () => {
    const mockPluginCtx = mockPluginContext()
    const plugin = debuggablePlugin({ enable: true })

    // Run the plugin setup
    plugin(mockPluginCtx)

    expect(mockPluginCtx.addGlobalOption).toHaveBeenCalledWith(
      'debug',
      expect.objectContaining({ type: 'boolean', description: 'Enable debug mode', default: false })
    )
  })

  test('disable debug option', () => {
    const mockPluginCtx = mockPluginContext()
    const plugin = debuggablePlugin({ enable: false })

    plugin(mockPluginCtx)

    expect(mockPluginCtx.addGlobalOption).not.toHaveBeenCalledWith(
      'debug',
      expect.objectContaining({ type: 'boolean', description: 'Enable debug mode', default: false })
    )
  })
})
```

### Testing the `onExtension` Callback

The `onExtension` callback runs after extensions are created:

```ts [src/plugin.ts]
import { plugin } from 'gunshi/plugin'

interface TrackerState {
  initialized: boolean
  initTime?: number | undefined
  commandName?: string | undefined
}

export function trackerPlugin() {
  const sharedState = {
    initialized: false,
    initTime: null as number | null,
    commandName: null as string | null
  }

  return plugin({
    id: 'tracker-plugin',
    name: 'Tracker Plugin',

    extension: (ctx, cmd) => ({
      get isInitialized() {
        return sharedState.initialized
      },
      getInitTime: () => sharedState.initTime,
      getCommandName: () => sharedState.commandName
    }),

    onExtension: (ctx, cmd) => {
      sharedState.initialized = true
      sharedState.initTime = Date.now()
      sharedState.commandName = cmd.name
    }
  })
}
```

Test `onExtension` behavior:

```ts [src/plugin.test.ts]
import { createCommandContext } from 'gunshi/plugin'
import { describe, expect, test, vi } from 'vitest'
import { trackerPlugin } from './init-tracker.ts'

describe('onExtension callback', () => {
  test('extension not initialized before onExtension', async () => {
    const plugin = trackerPlugin()
    const command = define({ name: 'test', description: 'Test', run: vi.fn() })
    const ctx = await createCommandContext({ command })
    const extension = await plugin.extension.factory(ctx, command)

    expect(extension.isInitialized).toBe(false)
    expect(extension.getInitTime()).toBeUndefined()
  })

  test('onExtension initializes extension', async () => {
    const plugin = trackerPlugin()
    const command = define({ name: 'deploy', description: 'Deploy', run: vi.fn() })
    const ctx = await createCommandContext({ command })
    const extension = await plugin.extension.factory(ctx, command)
    await plugin.extension.onFactory?.(ctx, command)

    expect(extension.isInitialized).toBe(true)
    expect(extension.getInitTime()).toBeGreaterThan(0)
    expect(extension.getCommandName()).toBe('deploy')
  })
})
```

## Testing Decorators

Decorators allow plugins to wrap and enhance existing command runners and renderers, adding functionality like logging, error handling, or output formatting. Testing decorators requires verifying both their enhancement behavior and their ability to properly delegate to the underlying functions. This section demonstrates techniques for testing command and renderer decorators, ensuring they intercept correctly when needed and pass through transparently when appropriate.

### Command Decorator Testing

Test decorators that wrap command runners:

```ts [src/decorator.test.ts]
import { createCommandContext } from 'gunshi/plugin'
import { describe, expect, test, vi } from 'vitest'
import { commandDecorator } from './decorators.ts'

describe('command decorator', () => {
  test('intercepts help option', async () => {
    const usage = 'Usage: test [options]'

    const ctx = await createCommandContext({
      command: { name: 'test', description: 'Test', run: vi.fn() },
      values: { help: true },
      cliOptions: {
        renderUsage: async () => usage
      }
    })

    const baseRunner = vi.fn(() => 'command executed')
    const decoratedRunner = commandDecorator(baseRunner)
    const result = await decoratedRunner(ctx)

    expect(result).toBe(usage)
    expect(baseRunner).not.toHaveBeenCalled()
  })

  test('passes through normally', async () => {
    const ctx = await createCommandContext({
      command: { name: 'test', description: 'Test', run: vi.fn() }
    })

    const baseRunner = vi.fn(() => 'command executed')
    const decoratedRunner = commandDecorator(baseRunner)
    const result = await decoratedRunner(ctx)

    expect(result).toBe('command executed')
    expect(baseRunner).toHaveBeenCalledWith(ctx)
  })
})
```

### Testing Renderer Decorators

The following example shows how to test extensions that interact with renderer decorators:

```ts [src/renderer.test.ts]
import { createCommandContext } from 'gunshi/plugin'
import { expect, test, vi } from 'vitest'
import myPlugin from './plugin.ts'
import { headerRendererDecorator } from './decorators.ts'

import type { PluginId } from './constants.ts'
import type { MyPluginExtension } from './types.ts'

describe('renderer decorators: decorateHeaderRenderer', async () => {
  test('render header with renderHeader option', async () => {
    const plugin = myPlugin()
    const header = 'Test Application v1.0.0'
    const ctx = await createCommandContext<{ extensions: Record<PluginId, MyPluginExtension> }>({
      command: { name: 'app', description: 'App', run: vi.fn() },
      extensions: {
        [plugin.id]: plugin.extension
      },
      cliOptions: {
        renderHeader: async () => header
      }
    })

    const baseRunner = vi.fn<Parameters<typeof headerRendererDecorator>[0]>(
      async () => 'header rendered'
    )
    const rendered = await headerRendererDecorator(baseRunner, ctx)
    expect(rendered).toBe(header)
    expect(baseRunner).not.toHaveBeenCalled()
  })

  test('not render Header without renderHeader option', async () => {
    const plugin = myPlugin()
    const ctx = await createCommandContext<{ extensions: Record<PluginId, MyPluginExtension> }>({
      command: { name: 'app', description: 'App', run: vi.fn() },
      extensions: {
        [plugin.id]: plugin.extension
      }
    })

    const baseRunner = vi.fn<Parameters<typeof headerRendererDecorator>[0]>(
      async () => 'header rendered'
    )
    const rendered = await headerRendererDecorator(baseRunner, ctx)
    expect(rendered).toBe('header rendered')
  })
})
```

## Integration Testing

While unit tests verify individual plugin components, integration tests ensure your plugin works correctly within a complete CLI environment with real command instances and potentially multiple interacting plugins. These tests validate the entire plugin lifecycle from registration through execution, including dependency resolution and inter-plugin communication. This section provides patterns for comprehensive integration testing that catches issues unit tests might miss.

### Testing Complete Plugin Flow

Integration tests verify the entire plugin lifecycle. The following example shows a logging plugin that we'll use for integration testing:

```ts [src/plugin.ts]
import { plugin } from 'gunshi/plugin'

export interface LoggingExtension {
  log: (message: string) => void
}

export function loggingPlugin() {
  return plugin({
    id: 'logging-plugin',
    name: 'Logging Plugin',

    extension: (ctx, cmd) => ({
      log: (message: string) => {
        if (ctx.values.verbose) {
          console.log(`[${cmd.name}] ${message}`)
        }
      }
    }),

    setup(ctx) {
      ctx.addGlobalOption('verbose', {
        type: 'boolean',
        short: 'V',
        description: 'Enable verbose logging'
      })
    }
  })
}
```

Test with real CLI instance:

```ts [src/plugin.test.ts]
import { describe, expect, test, vi } from 'vitest'
import { cli, define } from 'gunshi'
import { loggingPlugin } from './plugin.ts'

describe('plugin integration', () => {
  test('plugin adds global options to CLI', async () => {
    const plugin = loggingPlugin()
    const mockRun = vi.fn(() => 'success')
    const command = define({
      name: 'test-command',
      description: 'Test command',
      run: mockRun
    })
    await cli(['--verbose'], command, {
      plugins: [plugin]
    })

    expect(mockRun).toHaveBeenCalledWith(
      expect.objectContaining({
        values: {
          verbose: true
        }
      })
    )
  })
})
```

### Testing Multiple Plugins

Test plugin interactions with dependencies:

```ts [src/plugin.ts]
import { plugin } from 'gunshi/plugin'

export interface NotificationExtension {
  notify: (message: string) => void
}

const notificationDependencies = [{ id: 'logging-plugin', optional: true }] as const

export function notificationPlugin() {
  return plugin<
    Record<'logging-plugin', LoggingExtension>,
    'notification-plugin',
    typeof notificationDependencies
  >({
    id: 'notification-plugin',
    name: 'Notification Plugin',
    dependencies: notificationDependencies,
    extension: (ctx, cmd) => {
      const logger = ctx.extensions['logging-plugin']?.log
      return {
        notify(message: string) {
          if (logger) {
            logger(`[DEBUG] ${message}`)
          } else {
            console.log(message)
          }
        }
      }
    }
  })
}
```

Test plugin discovery and fallback:

```ts [src/plugin.test.ts]
import { createCommandContext } from 'gunshi/plugin'
import { describe, expect, test, vi } from 'vitest'
import { loggingPlugin, notificationPlugin } from './plugin.ts'

import type { LoggingExtension, NotificationExtension } from './plugin.ts'

describe('plugin interactions', () => {
  test('uses logger when available', async () => {
    const command = define({ name: 'test', description: 'Test', run: vi.fn() })

    const logging = loggingPlugin()
    const notification = notificationPlugin()

    const logSpy = vi.fn()
    vi.spyOn(logging.extension, 'factory').mockImplementation(async () => {
      return { log: logSpy }
    })
    const ctx = await createCommandContext<{
      extensions: Record<'logging-plugin', LoggingExtension> &
        Record<'notification-plugin', NotificationExtension>
    }>({
      command,
      extensions: {
        [logging.id]: logging.extension,
        [notification.id]: notification.extension
      }
    })

    ctx.extensions['notification-plugin'].notify('Hello')
    expect(logSpy).toHaveBeenCalledWith('[DEBUG] Hello')
  })

  test('falls back when logger missing', async () => {
    const command = define({ name: 'test', description: 'Test', run: vi.fn() })
    const notification = notificationPlugin()

    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
    const ctx = await createCommandContext<{
      extensions: Record<'notification-plugin', NotificationExtension>
    }>({
      command,
      extensions: {
        [notification.id]: notification.extension
      }
    })

    ctx.extensions['notification-plugin'].notify('Hello')
    expect(logSpy).toHaveBeenCalledWith('Hello')
  })
})
```

## Testing Techniques Reference

This reference section consolidates the key testing techniques and principles covered throughout this guide into a quick-access format. Use these techniques as templates for your own plugin tests, adapting them to your specific requirements while maintaining the core testing principles that ensure plugin reliability and maintainability.

### Quick Reference

The following code snippets provide quick examples of common testing approaches:

```ts
// Structure validation
expect(plugin.id).toBe('plugin-id')
expect(plugin.dependencies).toContain('dependency-id')

// Configuration validation
expect(() => plugin({ invalid: true })).toThrow()

// Extension testing with createCommandContext
const ctx = await createCommandContext({ command, values, cliOptions })
const extension = await plugin.extension.factory(ctx, command)

// Async extension testing
const loadConfig = vi.fn().mockReturnValue(config)
const plugin = myPlugin({ loadConfig })

// Lifecycle testing
plugin(mockPluginContext)
plugin.extension.onFactory?.(ctx, command)

// Command decorator testing
const commandDecorated = commandDecorator(baseRunner)
const result = await commandDecorated(ctx)

// Renderer decorators testing
const rendered = await rendererDecorator(baseRunner, ctx)

// Integration testing
await cli(['--option'], command, { plugins: [plugin] })

// Multiple plugins
const ctx = await createCommandContext({
  extensions: {
    plugin1: plugin1.extension,
    plugin2: plugin2.extension
  }
})
```

### Key Testing Principles

1. Test behavior, not implementation: Focus on what the plugin does, not how
2. Use createCommandContext: Provides complete type-safe context for testing
3. Test edge cases: Invalid config, missing dependencies, async failures
4. Isolate tests: Each test should be independent and deterministic
5. Mock external dependencies: File system, network calls, timers
6. Test lifecycle hooks: setup, onExtension, decorators
7. Verify integration: Test plugins working together in real CLI

### Common Testing Scenarios

* Plugin initialization with various configurations
* Extension method behavior with different context states
* Async operations and error handling
* Dependency resolution and fallback behavior
* Decorator application and pass-through
* Global option and command registration
* Multi-plugin interactions and discovery

### Type-Safe Testing

The following example demonstrates creating a fully type-safe plugin with compile-time dependency checking:

```ts
import { plugin } from 'gunshi/plugin'
import type { LoggerExtension } from './plugins/logger.ts'
import type { MyExtension } from './types.ts'

const typedPlugin = plugin<{ logger: LoggerExtension }, 'my-plugin', ['logger'], MyExtension>({
  id: 'my-plugin',
  dependencies: ['logger'],
  extension: (ctx, cmd) => ({
    doSomething: () => {
      ctx.extensions.logger.debug('Working')
      return 'done'
    }
  })
})
```

This ensures compile-time type safety for dependencies and extensions.

> \[!TIP]
> The example fully code is [here](https://github.com/kazupon/gunshi/tree/main/playground/plugins/testing).

## Next Steps

Now that you've mastered testing strategies for Gunshi plugins—from unit testing individual components to integration testing with real CLI contexts—you're ready to apply professional development practices.

The next chapter, [Plugin Development Guidelines](./guidelines.md), provides comprehensive guidelines for building production-ready plugins, including performance optimization, error handling strategies, and documentation standards that will help you create robust and maintainable plugins for the Gunshi ecosystem.

---

---
url: /guide/plugin/guidelines.md
---
# Plugin Development Guidelines

This guide provides practical guidelines for developing reliable, maintainable, and performant Gunshi plugins.

While other sections cover implementation details and APIs, this guide focuses on recommended approaches and techniques for production-ready plugins.

> \[!TIP]
> We recommend developing Gunshi plugins with TypeScript for enhanced type safety, better IDE support, and compile-time error detection. All examples and code snippets in this guide are written in TypeScript. While JavaScript plugins are supported, TypeScript helps prevent runtime errors and provides a superior developer experience through auto-completion and type checking.

> \[!NOTE]
> Some code examples in this guide include TypeScript file extensions (`.ts`) in `import`/`export` statements. If you use this pattern in your plugin, you'll need to enable `allowImportingTsExtensions` in your `tsconfig.json`.

## Design Principles

When developing Gunshi plugins, follow these core principles:

* **Single Responsibility**: Each plugin should have one clear purpose
* **Fail Fast**: Validate configuration early and provide clear error messages
* **Graceful Degradation**: Handle optional dependencies and features gracefully
* **Type Safety**: Export type definitions for all public interfaces
* **Performance Conscious**: Use lazy initialization and avoid blocking operations

These principles work together to create a robust plugin ecosystem. Single responsibility prevents conflicts and simplifies debugging.

Early validation saves time by catching errors at initialization. Graceful degradation ensures compatibility across environments.

Type safety prevents runtime errors and improves developer experience. Performance consciousness ensures responsive CLIs with instant feedback.

## Naming Conventions

### Plugin IDs

Use namespaced IDs to prevent conflicts and clearly identify plugin ownership. An id must be a non-empty string; `plugin()` and the installer both reject an empty one.

Namespacing prevents ID collisions in large applications where multiple teams might develop plugins independently.

It enables plugin discovery and filtering by namespace, making it easy to identify official plugins versus third-party extensions.

Additionally, this convention clarifies ownership and responsibility, helping users understand a plugin's source, maintenance status, and trustworthiness at a glance.

The following examples demonstrate different namespacing conventions for plugin IDs:

```ts
// Organization namespace
export const pluginId = 'myorg:logger' as const

// Scoped package format
export const pluginId = '@company/auth' as const

// Official Gunshi plugins
export const pluginId = 'g:i18n' as const
```

### Short Names of Global Options

A short name belongs to one global option for the whole CLI. `-h` and `-v` are taken by `@gunshi/plugin-global`, which is installed before anything else, and any plugin that reaches for a letter another plugin already registered gets its option registered without the short name — with a warning naming both of them. The long name always works.

The plugins of a CLI know nothing of each other, so the author of the CLI is often in no position to resolve the collision. Prefer a plugin that leaves it to them:

```ts
export default function host(options: { short?: string } = {}) {
  return plugin({
    id: 'myorg:host',
    setup: ctx => {
      // no short name unless the CLI asks for one, and never `-h` by default
      ctx.addGlobalOption('host', { type: 'string', short: options.short, description: 'Host' })
    }
  })
}
```

An argument of a command is not subject to this: it claims the letter for itself, and the global option gives it up for that command.

### Package Names

Follow consistent naming for plugin packages:

* Standalone packages: `gunshi-plugin-{feature}`
* Scoped packages: `@{org}/gunshi-plugin-{feature}` or `@{org}/gunshi-plugin`
* Example: `gunshi-plugin-logger`, `@mycompany/gunshi-plugin-auth`, `@feature/gunshi/plugin`

> \[!NOTE]
> Packages following the pattern `@gunshi/plugin-{feature}` (e.g., `@gunshi/plugin-i18n`) are official plugins maintained by the Gunshi team. These are not third-party plugins but are part of the official Gunshi ecosystem. Third-party developers should use their own organization scope or standalone naming as described above.

## Plugin Structure

### `gunshi/plugin` vs `@gunshi/plugin`

When developing Gunshi plugins, you need to import the `plugin` function and related types.

Plugin developers can import from either `gunshi/plugin` or `@gunshi/plugin`. Both provide identical APIs and type definitions.

Use `@gunshi/plugin` when you want to minimize your plugin's dependencies and reduce `node_modules` size, as it's a smaller package that only includes plugin-related functionality.

For plugin development, we recommend using `@gunshi/plugin` to keep your plugin package lightweight.

Here are the two equivalent import options available to plugin developers:

```ts
// Option 1: Import from main gunshi package
import { plugin } from 'gunshi/plugin'

// Option 2: Import from dedicated plugin package
import { plugin } from '@gunshi/plugin'
```

### Factory Function Approach

Create plugins as factory functions to allow configuration at initialization.

This approach enables configuration flexibility by accepting options at plugin creation time, allowing each instance to be configured independently without relying on global state or environment variables.

The factory function should be named after the plugin's primary functionality to make its purpose immediately clear.

**Good naming examples:**

* `logger()` for a logging plugin
* `auth()` for an authentication plugin
* `database()` for a database connection plugin

**Avoid generic names:**

* `createPlugin()` - Too generic
* `setup()` - Unclear purpose
* `init()` - Non-descriptive

Here's a complete factory function implementation:

```ts
export interface LoggerOptions {
  level?: 'debug' | 'info' | 'warn' | 'error'
  format?: 'json' | 'text'
}

export default function logger(options: LoggerOptions = {}) {
  const { level = 'info', format = 'text' } = options

  return plugin({
    id: 'logger',
    extension: () => ({
      log: (message: string) => {
        // Use options to configure behavior
        if (format === 'json') {
          console.log(JSON.stringify({ level, message }))
        } else {
          console.log(`[${level}] ${message}`)
        }
      }
    })
  })
}
```

### Export Types and Constants

Exporting types enables TypeScript consumers to properly type their code, preventing runtime type mismatches in production.

This practice improves IDE autocomplete and IntelliSense, allowing developers to discover your plugin's API more easily.

It also enables compile-time verification of correct plugin usage, catching integration errors during development rather than after deployment.

The following example shows how to properly export types and constants from your plugin:

```ts [types.ts]
export const pluginId = 'myorg:feature' as const
export type PluginId = typeof pluginId

export interface FeatureExtension {
  process: (data: Data) => Promise<Result>
}
```

```ts [index.ts]
export * from './types.ts'
export { default } from './plugin.ts'
```

For detailed type system usage, see [Plugin Type System](./type-system.md).

## Error Handling

### Validate Early, Fail Fast

Early validation helps avoid runtime issues that could occur deep in execution, potentially after performing partial operations or consuming computational resources.

By validating in the factory function, you can provide clearer error messages with full context about invalid configuration and specific steps to fix it.

This approach helps with debugging by catching errors at initialization rather than during command execution, when the source of the problem may be less clear.

The following example demonstrates early validation in the factory function:

```ts
export default function api(endpoint: string) {
  // Validate immediately
  if (!endpoint || !endpoint.startsWith('http')) {
    throw new Error('API plugin requires valid HTTP(S) endpoint URL')
  }

  return plugin({
    id: 'api',
    extension: () => ({
      fetch: async (path: string) => {
        // Endpoint is already validated
        return await fetch(`${endpoint}${path}`)
      }
    })
  })
}
```

The same applies to `setup`: it throws, and the CLI does not start. `cli()` rejects with an error naming your plugin, carrying yours as the `cause`, and no command runs. That is the right outcome for a configuration the CLI cannot be assembled with, so let `setup` throw rather than register half of what it meant to.

For the same reason, keep `setup` to registration. Work that can fail for reasons outside your control — reading a file, probing the environment, talking to a network — belongs in an extension or a decorator, where it runs per command and the failure can be handled there.

### Provide Actionable Error Messages

Clear, actionable error messages reduce debugging time by pointing developers to the root cause and solution.

When errors provide specific context, possible causes, and concrete next steps, developers can more easily diagnose and fix issues independently.

This example shows how to provide helpful error messages with context and solutions:

```ts
extension: ctx => ({
  connect: async (url: string) => {
    try {
      return await establishConnection(url)
    } catch (error) {
      // Provide context and solution
      throw new Error(
        `Failed to connect to ${url}.\n` +
          `Possible causes:\n` +
          `  - Network connectivity issues\n` +
          `  - Invalid URL format\n` +
          `  - Server is not responding\n` +
          `Try: Verify the URL and your network connection`
      )
    }
  }
})
```

### Handle Optional Dependencies Gracefully

Check for optional dependencies before using them.

Graceful dependency handling ensures your plugin works across different environments and configurations, preventing cascading failures when optional plugins are not available.

Choose the appropriate approach based on your needs.

The following example demonstrates different patterns for handling optional dependencies:

```ts
extension: ctx => {
  // Optional dependencies from other plugins
  const logger = ctx.extensions.logger
  const cache = ctx.extensions.cache

  return {
    processData: async (data: Data) => {
      // Use optional chaining (?.) for single operations
      logger?.info(`Processing data: ${data.id}`)

      // Use if statements for complex logic or multiple operations
      if (cache) {
        const cached = await cache.get(data.id)
        if (cached) {
          logger?.info('Cache hit') // Mix patterns when appropriate
          return cached
        }
      }

      // Process the data
      try {
        const result = await doProcessing(data)

        // Conditional block for related operations
        if (cache && result) {
          await cache.set(data.id, result)
          await cache.setExpiry(data.id, 3600)
        }

        logger?.info('Processing completed')
        return result
      } catch (error) {
        logger?.error(`Failed: ${error.message}`)
        throw error
      }
    }
  }
}
```

## Resource Management

After establishing proper error handling, the next important aspect is managing resources effectively.

Proper resource management prevents memory leaks and ensures your plugin releases system resources correctly, especially important when errors occur during execution.

### Clean Up Resources

Proper resource cleanup helps prevent memory leaks in long-running CLI tools.

System resources have practical limits - file handles (typically 1024 per process) and database connections (often 100-200 per server) can be exhausted without proper cleanup.

The following example demonstrates how to implement cleanup mechanisms for managing multiple database connections.

The plugin tracks all created connections in an array and provides a cleanup method that closes them all when the process exits:

```ts
extension: () => {
  const connections: Connection[] = []

  return {
    connect: async () => {
      const conn = await createConnection()
      connections.push(conn)
      return conn
    },

    cleanup: async () => {
      await Promise.all(connections.map(c => c.close()))
      connections.length = 0
    }
  }
}

// Use in `onExtension` or command hooks
onExtension: ctx => {
  process.once('exit', () => ctx.extensions.myPlugin.cleanup())
}
```

### Handle Process Signals

Your plugin should respond to system signals for graceful shutdown. The following code shows how to register cleanup handlers that disconnect from a database when the process receives termination signals (SIGINT from Ctrl+C or SIGTERM from system shutdown):

```ts
onExtension: ctx => {
  const cleanup = async () => {
    await ctx.extensions.database.disconnect()
    process.exit(0)
  }

  process.once('SIGINT', cleanup)
  process.once('SIGTERM', cleanup)
}
```

## Performance Considerations

With proper resource management in place, you can focus on optimizing when and how resources are created and accessed.

The following techniques improve CLI startup time and responsiveness while maintaining the resource cleanup patterns discussed earlier.

### Use Lazy Initialization

Lazy initialization improves CLI startup time by deferring expensive operations until actually needed.

This ensures quick response times for simple commands.

The following example demonstrates how to defer database connection initialization until the first query is executed:

```ts
extension: () => {
  let connection: Database | null = null

  const getConnection = async () => {
    // Only create the connection on first access
    if (!connection) {
      // Expensive operation deferred until actually needed
      connection = await createConnection()
    }
    return connection
  }

  return {
    query: async (sql: string) => {
      // Lazily initialize connection when query is first called
      const conn = await getConnection()
      return conn.execute(sql)
    }
  }
}
```

### Avoid Blocking Operations

Blocking operations freeze the CLI interface and degrade user experience. Use asynchronous operations to maintain interactivity, especially during initialization and command execution.

The following examples contrast blocking and non-blocking approaches to file operations and data processing:

```ts
extension: () => ({
  // Bad: Blocks the entire CLI during initialization
  loadConfig: () => {
    const data = fs.readFileSync('./config.json', 'utf8') // Blocks!
    return JSON.parse(data)
  },

  // Good: Non-blocking async operation
  loadConfig: async () => {
    const data = await fs.promises.readFile('./config.json', 'utf8')
    return JSON.parse(data)
  },

  // Better: Non-blocking with progress feedback
  processLargeDataset: async files => {
    const results = []
    for (const [index, file] of files.entries()) {
      // Process file asynchronously
      const data = await processFile(file)
      results.push(data)
      console.log(`Processing: ${index + 1}/${files.length}`)
    }
    console.log() // New line after progress
    return results
  }
})
```

### Optimize Module Loading

Loading heavy dependencies at startup increases CLI initialization time and memory usage. Use dynamic imports to load heavy dependencies only when needed, keeping the initial load minimal for fast command response.

These examples demonstrate how to use dynamic imports to defer loading heavy dependencies:

```ts
// Bad: Module-level import loads dependency at startup
import ExcelJS from 'exceljs' // 4MB loaded at startup!

extension: () => ({
  generateReport: async data => {
    const workbook = new ExcelJS.Workbook()
    // Generate report...
  }
  // Other methods that don't use ExcelJS...
})

// Good: Dynamic import loads dependency only when needed
extension: () => ({
  generateReport: async data => {
    // Load 4MB dependency only when report is actually generated
    const { Workbook } = await import('exceljs')
    const workbook = new Workbook()
    // Generate report...
  },

  // Better: Combine with user feedback for perceived performance
  exportData: async (format, data) => {
    if (format === 'excel') {
      console.log('Loading Excel export module...')
      const { exportToExcel } = await import('./exporters/excel.js')
      return exportToExcel(data)
    } else if (format === 'pdf') {
      console.log('Loading PDF export module...')
      const { exportToPDF } = await import('./exporters/pdf.js')
      return exportToPDF(data)
    }
    // Default lightweight JSON export
    return JSON.stringify(data)
  }
})
```

For more `extension` lifecycle details, see [Plugin Extensions](./extensions.md).

## Security Considerations

### Validate All Inputs

User input should be validated and sanitized before use.

The following example demonstrates how to validate file paths and extensions to prevent directory traversal attacks and restrict file types:

```ts
extension: () => ({
  readFile: async (path: string) => {
    // Prevent path traversal
    if (path.includes('..') || path.startsWith('/')) {
      throw new Error('Invalid file path')
    }

    // Validate file extension
    const allowed = ['.json', '.yaml', '.yml']
    if (!allowed.some(ext => path.endsWith(ext))) {
      throw new Error('Unsupported file type')
    }

    return await fs.readFile(path, 'utf8')
  }
})
```

### Protect Sensitive Data

Avoid exposing sensitive information in logs or error messages.

This example shows how to handle API keys securely in a plugin, validating them without logging sensitive data:

```ts
export default function auth(apiKey: string) {
  // Validate but don't log the key
  if (!apiKey || apiKey.length < 32) {
    throw new Error('Invalid API key format')
  }

  return plugin({
    id: 'auth',
    extension: () => ({
      request: async (url: string) => {
        try {
          return await fetch(url, {
            headers: { Authorization: `Bearer ${apiKey}` }
          })
        } catch (error) {
          // Don't include the API key in errors
          throw new Error(`Request failed: ${error.message}`)
        }
      }
    })
  })
}
```

### Prevent Prototype Pollution

Prototype pollution occurs when user-controlled data modifies `Object.prototype`, potentially injecting properties that affect all objects in your application.

This vulnerability is particularly dangerous in CLI tools that process configuration files or user-provided options, as attackers can manipulate command behavior through crafted inputs.

Use `Object.create(null)` to create objects without a prototype chain when handling user input:

```ts
extension: () => {
  // Vulnerable: Regular object inherits from Object.prototype
  const userOptions = {} // Can be polluted via __proto__ or constructor

  // Safe: Object without prototype chain
  const safeOptions = Object.create(null)

  return {
    parseConfig: config => {
      // Safe storage for user-provided data
      const settings = Object.create(null)

      // Safely merge user config with defaults
      for (const key in config) {
        // Only copy own properties, not inherited ones
        if (Object.prototype.hasOwnProperty.call(config, key)) {
          // Prevent __proto__ and constructor pollution
          if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
            continue
          }
          settings[key] = config[key]
        }
      }

      return settings
    },

    // Safe command registry without prototype chain
    createCommandMap: commands => {
      const commandMap = Object.create(null)

      for (const cmd of commands) {
        commandMap[cmd] = true
      }

      // Safe to check user input against this map
      return commandMap
    }
  }
}
```

Use `Object.create(null)` specifically when:

* Storing user-provided configuration or options
* Creating lookup maps from external input
* Building registries from dynamic data
* Merging multiple configuration sources

Regular object literals are safe for:

* Internal plugin state
* Hardcoded configurations
* Type-checked interfaces

## Testing Strategies

Focus testing on your plugin's extension factory and how it interacts with the command context.

This ensures your plugin properly integrates with Gunshi's lifecycle and handles command metadata correctly.

The following example demonstrates how to test your plugin's extension factory and its interaction with the command context:

```ts
import { describe, test, expect, vi } from 'vitest'
import myPlugin from './plugin.ts'

describe('Plugin Extension', () => {
  test('extension factory creates correct methods', async () => {
    const plugin = myPlugin({ debug: true })

    // Mock a command context to simulate Gunshi's runtime environment
    const mockContext = {
      name: 'test-command',
      values: { verbose: true },
      log: vi.fn(),
      extensions: {}
    }

    const mockCommand = { name: 'test', run: vi.fn() }

    // Verify the extension factory returns all required plugin methods
    const extension = await plugin.extension(mockContext, mockCommand)
    expect(extension.process).toBeDefined()
    expect(typeof extension.process).toBe('function')

    // Verify the plugin correctly uses context.log when debug is enabled
    extension.process('data')
    expect(mockContext.log).toHaveBeenCalledWith('[DEBUG]', 'data')
  })
})
```

For test helpers, lifecycle testing, and integration testing strategies, see [Plugin Testing](./testing.md).

## Documentation

Comprehensive documentation is crucial for plugin adoption and maintenance.

This section provides guidelines and real examples from official Gunshi plugins to help you create effective documentation.

### Module-Level Documentation

Start your main plugin file with module-level JSDoc that explains the plugin's purpose and provides a complete usage example.

The following example from `@gunshi/plugin-global` demonstrates this approach:

````ts
/**
 * The entry point of global options plugin
 *
 * @example
 * ```js
 * import global from '@gunshi/plugin-global'
 * import { cli } from 'gunshi'
 *
 * const entry = (ctx) => {
 *   // ...
 * }
 *
 * await cli(process.argv.slice(2), entry, {
 *   // ...
 *
 *   plugins: [
 *     global()
 *   ],
 *
 *   // ...
 * })
 * ```
 *
 * @module
 */
````

### Factory Function Documentation

Document your factory function comprehensively, including all parameters and return types. Here's an example from `@gunshi/plugin-i18n`:

```ts
/**
 * i18n plugin
 *
 * @param options - I18n plugin options
 * @returns A defined plugin as i18n
 */
export default function i18n(
  options: I18nPluginOptions = {}
): PluginWithExtension<I18nExtension<DefaultGunshiParams>> {
  // Implementation
}
```

For plugins with required parameters, include validation guidance:

```ts
/**
 * completion plugin
 *
 * @param options - Completion options
 * @returns A defined plugin as completion
 */
export default function completion(options: CompletionOptions = {}): PluginWithoutExtension {
  const config = options.config || {}
  // Validate and use options
}
```

### Extension Interface Documentation

Document all methods and properties exposed through your plugin's extension.

Here's a concise example:

```ts
/**
 * Extended command context utilities available via `CommandContext.extensions['g:i18n']`.
 */
export interface I18nExtension<G extends GunshiParams<any> = DefaultGunshiParams> {
  /** Command locale */
  locale: Intl.Locale

  /** Translate a message with optional interpolation */
  translate: <K>(key: K, values?: Record<string, unknown>) => string

  /** Load command resources for the specified locale */
  loadResource: (
    locale: string | Intl.Locale,
    ctx: CommandContext,
    command: Command
  ) => Promise<boolean>

  // Additional methods follow similar documentation patterns
}
```

For complete examples, see the official plugins' source code.

### Configuration Options Documentation

Document all configuration options with their types, defaults, and purpose:

```ts
/**
 * i18n plugin options
 */
export interface I18nPluginOptions {
  /** Locale to use for translations */
  locale?: string | Intl.Locale

  /** Translation adapter factory */
  translationAdapterFactory?: TranslationAdapterFactory

  /** Built-in localizable resources */
  builtinResources?: Record<string, Record<BuiltinResourceKeys, string>>
}
```

Nested interfaces follow the same documentation pattern with JSDoc comments for each property.

### Type Documentation Guidelines

Export all public types with clear documentation:

```ts
/** The unique identifier for the i18n plugin */
export const pluginId = namespacedId('i18n')
export type PluginId = typeof pluginId

/** Command resource type with dynamic argument keys */
export type CommandResource<G extends GunshiParamsConstraint = DefaultGunshiParams> = {
  description: string
  // Dynamic properties based on command arguments
} & { [key: string]: string }

/** Async function to fetch command resources */
export type CommandResourceFetcher<G extends GunshiParamsConstraint> = (
  ctx: Readonly<CommandContext<G>>
) => Awaitable<CommandResource<G>>
```

For more complex generic types, see official plugin implementations.

### Plugin Dependencies Documentation

Document plugin dependencies clearly:

```ts
return plugin<...>({
  id: pluginId,
  name: 'completion',
  dependencies: [{ id: namespacedId('i18n'), optional: true }] as const
  // ...
})
```

In your README, explain:

* Dependency ID and whether it's optional/required
* Purpose and effect when present
* Any automatic behaviors or integration points

### README Template Structure

> \[!NOTE]
> Gunshi plans to provide official tooling for plugin authors to automatically generate README templates in future releases. This tooling will help scaffold standard README files with the correct structure, sections, and formatting. Until then, the following template demonstrates the recommended structure for plugin README files.

A comprehensive README should follow this structure:

```md [README.md]
# @yourorg/gunshi-plugin-{name}

> Brief description of what your plugin does.

## Installation

\`\`\`sh

### npm

npm install --save @yourorg/gunshi-plugin-{name}
\`\`\`

For other package managers, see [installation guide](./docs/install.md).

## Usage

<!-- eslint-disable markdown/no-missing-label-refs, markdown/no-space-in-emphasis -->

\`\`\`ts
import { cli, define } from 'gunshi'
import myPlugin from '@yourorg/gunshi-plugin-{name}'

const command = define({
name: 'example',
run: ctx => {
ctx.extensions['yourorg:{name}'].someMethod()
}
})

await cli(process.argv.slice(2), command, {
plugins: [myPlugin({ /* options */ })]
})
\`\`\`

<!-- eslint-enable markdown/no-missing-label-refs, markdown/no-space-in-emphasis -->

## Plugin Options

See [API documentation](./docs/api.md) for complete options.

## Examples

See the [examples directory](./examples) for usage examples.

## License

[MIT](http://opensource.org/licenses/MIT)
```

### API Documentation Generation

Generate API documentation directly from your JSDoc comments to maintain a single source of truth.

This approach ensures your documentation stays synchronized with your code, as updates to JSDoc comments automatically reflect in generated documentation.

Various tools can generate documentation from JSDoc comments:

* **[vitepress-api-references](https://github.com/kazupon/vitepress-api-references)** - Recommended for VitePress projects, generates Markdown API references from TypeScript declarations and JSDoc
* **[TypeDoc](https://typedoc.org/)** - A popular documentation generator for TypeScript projects
* **[API Extractor](https://api-extractor.com/)** - Microsoft's tool focusing on API review and documentation for TypeScript libraries

The following example demonstrates configuring `vitepress-api-references`. Create a `scripts/generate-api-reference.ts` file:

```ts [scripts/generate-api-reference.ts]
import { rm } from 'node:fs/promises'
import { generateOxContentApiDocs } from 'vitepress-api-references'

await rm('docs', { recursive: true, force: true })

await generateOxContentApiDocs({
  root: process.cwd(),
  entryPoints: ['./src/index.ts'],
  outDir: 'docs',
  basePath: '/docs',
  extraction: {
    internal: false,
    private: false,
    typeParameters: true
  },
  markdown: {
    pathStrategy: 'typedoc',
    renderStyle: 'markdown',
    indexFormat: 'table',
    parametersFormat: 'table',
    interfacePropertiesFormat: 'table',
    classPropertiesFormat: 'table',
    propertyMembersFormat: 'table',
    typeAliasPropertiesFormat: 'table',
    enumMembersFormat: 'table',
    renderStats: false,
    renderGeneratedBy: false
  },
  nav: { enabled: false },
  escapeHeadingAngleBrackets: true
})
```

Add documentation scripts to your `package.json`:

```json [package.json]
{
  "scripts": {
    "docs": "tsx ./scripts/generate-api-reference.ts",
    "docs:clean": "rm -rf docs"
  },
  "devDependencies": {
    "tsx": "^4.0.0",
    "vitepress-api-references": "^0.1.0"
  }
}
```

This configuration extracts documentation from your JSDoc comments and TypeScript types, generating comprehensive API documentation without manual maintenance.

The generated documentation includes all exported functions, interfaces, types, and their associated JSDoc descriptions, ensuring consistency between code and documentation.

## Next Steps

Following these guidelines ensures your plugins are production-ready, maintainable, and provide excellent developer experience. You've learned naming conventions, error handling patterns, performance considerations, and documentation strategies.

Now that you understand how to build high-quality plugins, explore the existing ecosystem to see these principles in action and find plugins that can enhance your CLI.

The next chapter on [Plugin List](./list.md) showcases official plugins maintained by the Gunshi team and community contributions.

---

---
url: /guide/plugin/list.md
---
# Plugin List

Gunshi provides official plugins that address common CLI development needs. See [Using Plugins](./getting-started.md) for how to use plugins in your application.

## Official Plugins

### [@gunshi/plugin-global](https://github.com/kazupon/gunshi/tree/main/packages/plugin-global)

Adds global `--help` and `--version` options to all commands.

### [@gunshi/plugin-renderer](https://github.com/kazupon/gunshi/tree/main/packages/plugin-renderer)

Provides default rendering for usage, help text, and validation errors.

### [@gunshi/plugin-i18n](https://github.com/kazupon/gunshi/tree/main/packages/plugin-i18n)

Provides internationalization support for CLI applications.

### [@gunshi/plugin-completion](https://github.com/kazupon/gunshi/tree/main/packages/plugin-completion)

Provides shell completion functionality for bash, zsh, and fish.

### [@gunshi/plugin-dryrun](https://github.com/kazupon/gunshi/tree/main/packages/plugin-dryrun)

Adds a `--dry-run` option and helpers for printing planned side-effect operations without executing them.

### [@gunshi/plugin-suggestion](https://github.com/kazupon/gunshi/tree/main/packages/plugin-suggestion)

Adds Levenshtein-based suggestions for unknown long options and unknown commands.

## Community Plugins

> \[!NOTE]
> Welcome your plugins! Submit a PR to add your plugin to this list.

## Where to Go From Here

* **Use official plugins**: Integrate these plugins into your CLI applications for enhanced functionality
* **Study implementations**: Review the source code of official plugins to learn implementation patterns
* **Create your own**: Apply what you've learned to build custom plugins for your specific needs
* **Share with the community**: Publish your plugins and submit a PR to add them to this list

---

---
url: /api/agent.md
---
# agent

The entry point for AI agent detection utilities.

Detection is delegated to [std-env](https://github.com/unjs/std-env).
The `gunshi/agent` API exposes a stable, minimal profile while the recognized
agent names and detection rules may evolve with the upstream detector.

## Example

```js
import { getAgentProfile } from 'gunshi/agent'
```

## Functions

| Function | Description |
| ------ | ------ |
| [getAgentProfile](/api/agent/functions/getAgentProfile.md) | Get the AI coding agent profile of the current process. |

---

---
url: /api/agent/functions/getAgentProfile.md
---
# Function: getAgentProfile()

Get the AI coding agent profile of the current process.

The detection itself is delegated to `std-env`. This function only converts
the upstream `agentInfo` into Gunshi's minimal AgentProfile shape.

## Signature

```ts
export function getAgentProfile(): AgentProfile
```

## Returns

`AgentProfile` — An AgentProfile describing whether the process is running on an AI coding agent and, if so, which agent was detected.

## Examples

```js
import { getAgentProfile } from 'gunshi/agent'

const profile = getAgentProfile()

if (profile.isAgent) {
  // adjust output for AI agent execution
}
```

---

---
url: /api/combinators.md
---
# combinators

Parser combinator entry point.

This entry point exports composable combinator factory functions for building
type-safe argument schemas. These combinators produce [ArgSchema](/api/default/interfaces/ArgSchema.md) objects
that can be used anywhere regular argument schemas are accepted.

## Example

```ts
import { string, integer, boolean, required, withDefault, short } from 'gunshi/combinators'
import { define, cli } from 'gunshi'

const command = define({
  name: 'serve',
  args: {
    host: withDefault(string(), 'localhost'),
    port: withDefault(integer({ min: 1, max: 65535 }), 8080),
    verbose: short(boolean(), 'v')
  },
  run: ctx => {
    console.log(`Listening on ${ctx.values.host}:${ctx.values.port}`)
  }
})
```

## Functions

| Function | Description |
| ------ | ------ |
| [args](/api/combinators/functions/args.md) | Type-safe schema factory. |
| [boolean](/api/combinators/functions/boolean.md) | Create a boolean argument schema. |
| [choice](/api/combinators/functions/choice.md) | Create an enum-like argument schema with literal type inference. |
| [combinator](/api/combinators/functions/combinator.md) | Create a custom argument schema with a user-defined parse function. |
| [describe](/api/combinators/functions/describe.md) | Set a description on a combinator schema for help text generation. |
| [extend](/api/combinators/functions/extend.md) | Extend a schema by overriding or adding fields. |
| [float](/api/combinators/functions/float.md) | Create a floating-point argument schema with optional range validation. |
| [hidden](/api/combinators/functions/hidden.md) | Hide a combinator schema from generated help or usage output. |
| [integer](/api/combinators/functions/integer.md) | Create an integer argument schema with optional range validation. |
| [map](/api/combinators/functions/map.md) | Transform the output of a combinator schema. |
| [merge](/api/combinators/functions/merge.md) | Compose multiple [Args](/api/default/interfaces/Args.md) schemas into one. |
| [multiple](/api/combinators/functions/multiple.md) | Mark a combinator schema as accepting multiple values. |
| [number](/api/combinators/functions/number.md) | Create a number argument schema with optional range validation. |
| [positional](/api/combinators/functions/positional.md) | Create a positional argument schema. |
| [required](/api/combinators/functions/required.md) | Mark a combinator schema as required. |
| [short](/api/combinators/functions/short.md) | Set a short alias on a combinator schema. |
| [string](/api/combinators/functions/string.md) | Create a string argument schema with optional validation. |
| [unrequired](/api/combinators/functions/unrequired.md) | Mark a combinator schema as not required. |
| [withDefault](/api/combinators/functions/withDefault.md) | Set a default value on a combinator schema. |

## Interfaces

| Interface | Description |
| ------ | ------ |
| [BaseOptions](/api/combinators/interfaces/BaseOptions.md) | Common options shared by all base combinators. |
| [BooleanOptions](/api/combinators/interfaces/BooleanOptions.md) | Options for the [boolean](/api/combinators/functions/boolean.md) combinator. |
| [CombinatorOptions](/api/combinators/interfaces/CombinatorOptions.md) | Options for the [combinator](/api/combinators/functions/combinator.md) factory function. |
| [FloatOptions](/api/combinators/interfaces/FloatOptions.md) | Options for the [float](/api/combinators/functions/float.md) combinator. |
| [IntegerOptions](/api/combinators/interfaces/IntegerOptions.md) | Options for the [integer](/api/combinators/functions/integer.md) combinator. |
| [NumberOptions](/api/combinators/interfaces/NumberOptions.md) | Options for the [number](/api/combinators/functions/number.md) combinator. |
| [StringOptions](/api/combinators/interfaces/StringOptions.md) | Options for the [string](/api/combinators/functions/string.md) combinator. |

## Type Aliases

| Type Alias | Description |
| ------ | ------ |
| [Combinator](/api/combinators/type-aliases/Combinator.md) | A combinator produced by combinator factory functions. |
| [CombinatorSchema](/api/combinators/type-aliases/CombinatorSchema.md) | A schema produced by combinator factory functions. Any [ArgSchema](/api/default/interfaces/ArgSchema.md) whose parse function returns `T` qualifies. The `parse` of [ArgSchema](/api/default/interfaces/ArgSchema.md), which returns `any`, is left out, so that a schema fits only where the values that it parses do: `integer()` is not a `CombinatorSchema<string>`. |

---

---
url: /api/combinators/functions/args.md
---
# Function: args()

Type-safe schema factory.

Returns the input unchanged at runtime, but provides type inference
so that `satisfies Args` is not needed.

## Signature

```ts
export declare function args<T extends Args>(fields: T): T
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` *extends* [`Args`](/api/default/interfaces/Args.md) | The exact schema type. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `fields` | `T` | The argument schema object. |

## Returns

`T` — The same schema object with its type inferred.

## Examples

```ts
const common = args({
  verbose: boolean(),
  help: short(boolean(), 'h')
})
```

---

---
url: /api/combinators/functions/boolean.md
---
# Function: boolean()

## Call Signature

```ts
export declare function boolean<const R extends boolean>(opts: BooleanOptions & {
  required: R;
}): WithRequiredOption<CombinatorSchema<boolean>, R>
```

Create a boolean argument schema.

Boolean arguments are existence-based. The resolver passes `"true"` or `"false"`
to the parse function based on the presence or negation of the flag, or on an explicit
`=true` / `=false` value. Other inline values are rejected before the parse function is called.

### Type Parameters

| Name | Description |
| --- | --- |
| `R` *extends* `boolean` | The type of `required` in the options, which the schema keeps. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`BooleanOptions`](/api/combinators/interfaces/BooleanOptions.md) & { [`required`](/api/combinators/functions/required.md): `R` } | Boolean options. |

### Returns

`WithRequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`boolean`>, `R`> — A combinator schema for boolean flags.

### Examples

```ts
const args = {
  color: boolean({ negatable: true })
}
// Usage: --color (true), --no-color (false)
```

## Call Signature

```ts
export declare function boolean<const R extends boolean | undefined = boolean | undefined>(opts?: BooleanOptions & {
  required?: R;
}): WithUnrequiredOption<CombinatorSchema<boolean>, R>
```

Create a boolean argument schema.

Boolean arguments are existence-based. The resolver passes `"true"` or `"false"`
to the parse function based on the presence or negation of the flag, or on an explicit
`=true` / `=false` value. Other inline values are rejected before the parse function is called.

### Type Parameters

| Name | Description |
| --- | --- |
| `R` *extends* `boolean \| undefined` = `boolean \| undefined` | The type of `required` in the options, which the schema keeps when it may be `false` but not `true`, as for `optional ? { required: false } : {}`, so that a positional argument with it is optional. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`BooleanOptions`](/api/combinators/interfaces/BooleanOptions.md) & { [`required`](/api/combinators/functions/required.md)?: `R` } | Boolean options. *(optional)* |

### Returns

`WithUnrequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`boolean`>, `R`> — A combinator schema for boolean flags.

### Examples

```ts
const args = {
  color: boolean({ negatable: true })
}
// Usage: --color (true), --no-color (false)
```

## Call Signature

```ts
export declare function boolean(opts?: BooleanOptions): CombinatorSchema<boolean>
```

Create a boolean argument schema.

Boolean arguments are existence-based. The resolver passes `"true"` or `"false"`
to the parse function based on the presence or negation of the flag, or on an explicit
`=true` / `=false` value. Other inline values are rejected before the parse function is called.

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`BooleanOptions`](/api/combinators/interfaces/BooleanOptions.md) | Boolean options. *(optional)* |

### Returns

[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`boolean`> — A combinator schema for boolean flags.

### Examples

```ts
const args = {
  color: boolean({ negatable: true })
}
// Usage: --color (true), --no-color (false)
```

---

---
url: /api/combinators/functions/choice.md
---
# Function: choice()

## Call Signature

```ts
export declare function choice<const T extends readonly string[], const R extends boolean>(values: T, opts: BaseOptions & {
  required: R;
}): WithRequiredOption<CombinatorSchema<T[number]>, R>
```

Create an enum-like argument schema with literal type inference.

Uses `const T` generic to infer literal union types from the values array.

### Type Parameters

| Name | Description |
| --- | --- |
| `T` *extends* `readonly string[]` | The readonly array of allowed string values. |
| `R` *extends* `boolean` | The type of `required` in the options, which the schema keeps. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `values` | `T` | Allowed values. |
| `opts` | [`BaseOptions`](/api/combinators/interfaces/BaseOptions.md) & { [`required`](/api/combinators/functions/required.md): `R` } | Common options (description, short, hidden, required). |

### Returns

`WithRequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`\[`number`]>, `R`> — A combinator schema that resolves to a union of the allowed values.

### Examples

```ts
const args = {
  level: choice(['debug', 'info', 'warn', 'error'] as const)
}
// typeof values.level === 'debug' | 'info' | 'warn' | 'error'
```

## Call Signature

```ts
export declare function choice<const T extends readonly string[], const R extends boolean | undefined = boolean | undefined>(values: T, opts?: BaseOptions & {
  required?: R;
}): WithUnrequiredOption<CombinatorSchema<T[number]>, R>
```

Create an enum-like argument schema with literal type inference.

Uses `const T` generic to infer literal union types from the values array.

### Type Parameters

| Name | Description |
| --- | --- |
| `T` *extends* `readonly string[]` | The readonly array of allowed string values. |
| `R` *extends* `boolean \| undefined` = `boolean \| undefined` | The type of `required` in the options, which the schema keeps when it may be `false` but not `true`, as for `optional ? { required: false } : {}`, so that a positional argument with it is optional. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `values` | `T` | Allowed values. |
| `opts` | [`BaseOptions`](/api/combinators/interfaces/BaseOptions.md) & { [`required`](/api/combinators/functions/required.md)?: `R` } | Common options (description, short, hidden, required). *(optional)* |

### Returns

`WithUnrequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`\[`number`]>, `R`> — A combinator schema that resolves to a union of the allowed values.

### Examples

```ts
const args = {
  level: choice(['debug', 'info', 'warn', 'error'] as const)
}
// typeof values.level === 'debug' | 'info' | 'warn' | 'error'
```

## Call Signature

```ts
export declare function choice<const T extends readonly string[]>(values: T, opts?: BaseOptions): CombinatorSchema<T[number]>
```

Create an enum-like argument schema with literal type inference.

Uses `const T` generic to infer literal union types from the values array.

### Type Parameters

| Name | Description |
| --- | --- |
| `T` *extends* `readonly string[]` | The readonly array of allowed string values. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `values` | `T` | Allowed values. |
| `opts` | [`BaseOptions`](/api/combinators/interfaces/BaseOptions.md) | Common options (description, short, hidden, required). *(optional)* |

### Returns

[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`\[`number`]> — A combinator schema that resolves to a union of the allowed values.

### Examples

```ts
const args = {
  level: choice(['debug', 'info', 'warn', 'error'] as const)
}
// typeof values.level === 'debug' | 'info' | 'warn' | 'error'
```

---

---
url: /api/combinators/functions/combinator.md
---
# Function: combinator()

## Call Signature

```ts
export declare function combinator<T, const R extends boolean>(config: CombinatorOptions<T> & {
  required: R;
}): WithRequiredOption<CombinatorSchema<T>, R>
```

Create a custom argument schema with a user-defined parse function.

This is the most general custom combinator. Use it when none of the built-in
base combinators ([string](/api/combinators/functions/string.md), [number](/api/combinators/functions/number.md), [integer](/api/combinators/functions/integer.md),
[float](/api/combinators/functions/float.md), [boolean](/api/combinators/functions/boolean.md), [choice](/api/combinators/functions/choice.md)) fit your needs.

The returned schema has `type: 'custom'`.

### Type Parameters

| Name | Description |
| --- | --- |
| `T` | The parsed value type. |
| `R` *extends* `boolean` | The type of `required` in the configuration, which the schema keeps. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `config` | [`CombinatorOptions`](/api/combinators/interfaces/CombinatorOptions.md)<`T`> & { [`required`](/api/combinators/functions/required.md): `R` } | Configuration with a parse function and optional metavar. |

### Returns

`WithRequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`>, `R`> — A combinator schema that resolves to the parse function's return type.

### Examples

```ts
const date = combinator({
  parse: (value) => {
    const d = new Date(value)
    if (isNaN(d.getTime())) {
      throw new Error('Invalid date format')
    }
    return d
  },
  metavar: 'date'
})
```

## Call Signature

```ts
export declare function combinator<T, const R extends boolean | undefined = boolean | undefined>(config: CombinatorOptions<T> & {
  required?: R;
}): WithUnrequiredOption<CombinatorSchema<T>, R>
```

Create a custom argument schema with a user-defined parse function.

This is the most general custom combinator. Use it when none of the built-in
base combinators ([string](/api/combinators/functions/string.md), [number](/api/combinators/functions/number.md), [integer](/api/combinators/functions/integer.md),
[float](/api/combinators/functions/float.md), [boolean](/api/combinators/functions/boolean.md), [choice](/api/combinators/functions/choice.md)) fit your needs.

The returned schema has `type: 'custom'`.

### Type Parameters

| Name | Description |
| --- | --- |
| `T` | The parsed value type. |
| `R` *extends* `boolean \| undefined` = `boolean \| undefined` | The type of `required` in the configuration, which the schema keeps when it may be `false` but not `true`, as for `optional ? { required: false } : {}`, so that a positional argument with it is optional. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `config` | [`CombinatorOptions`](/api/combinators/interfaces/CombinatorOptions.md)<`T`> & { [`required`](/api/combinators/functions/required.md)?: `R` } | Configuration with a parse function and optional metavar. |

### Returns

`WithUnrequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`>, `R`> — A combinator schema that resolves to the parse function's return type.

### Examples

```ts
const date = combinator({
  parse: (value) => {
    const d = new Date(value)
    if (isNaN(d.getTime())) {
      throw new Error('Invalid date format')
    }
    return d
  },
  metavar: 'date'
})
```

## Call Signature

```ts
export declare function combinator<T>(config: CombinatorOptions<T>): CombinatorSchema<T>
```

Create a custom argument schema with a user-defined parse function.

This is the most general custom combinator. Use it when none of the built-in
base combinators ([string](/api/combinators/functions/string.md), [number](/api/combinators/functions/number.md), [integer](/api/combinators/functions/integer.md),
[float](/api/combinators/functions/float.md), [boolean](/api/combinators/functions/boolean.md), [choice](/api/combinators/functions/choice.md)) fit your needs.

The returned schema has `type: 'custom'`.

### Type Parameters

| Name | Description |
| --- | --- |
| `T` | The parsed value type. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `config` | [`CombinatorOptions`](/api/combinators/interfaces/CombinatorOptions.md)<`T`> | Configuration with a parse function and optional metavar. |

### Returns

[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> — A combinator schema that resolves to the parse function's return type.

### Examples

```ts
const date = combinator({
  parse: (value) => {
    const d = new Date(value)
    if (isNaN(d.getTime())) {
      throw new Error('Invalid date format')
    }
    return d
  },
  metavar: 'date'
})
```

---

---
url: /api/combinators/functions/describe.md
---
# Function: describe()

Set a description on a combinator schema for help text generation.

The original schema is not modified.
Other modifiers on `schema` (for example [required](/api/combinators/functions/required.md)) are kept.

## Signature

```ts
export declare function describe<T, D extends string, S extends CombinatorSchema<T> = CombinatorSchema<T>>(schema: S, text: D): Modified<S, CombinatorDescribe<D>>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` | The schema's parsed type, when type arguments are given explicitly. It is not inferred, so that `schema` can be a union of schemas of different types. |
| `D` *extends* `string` | The description string literal type. |
| `S` *extends* [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> = [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> | The input combinator schema, inferred from `schema`. Its other modifiers are kept. If type arguments are given explicitly without `S`, `S` is `CombinatorSchema<T>`, and the type of the result lacks the other modifiers, although the returned object has them. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `schema` | `S` | The base combinator schema. |
| `text` | `D` | Human-readable description. |

## Returns

`Modified<S, CombinatorDescribe<D>>` — A new schema with the description set.

## Examples

```ts
const args = {
  port: describe(integer(), 'Port number to listen on')
}
```

---

---
url: /api/combinators/functions/extend.md
---
# Function: extend()

Extend a schema by overriding or adding fields.

Equivalent to `merge(base, overrides)` but communicates the intent of
intentional overrides rather than general composition.

## Signature

```ts
export declare function extend<T extends Args, U extends Args>(base: T, overrides: U): Omit<T, keyof U> & U
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` *extends* [`Args`](/api/default/interfaces/Args.md) | Base schema type. |
| `U` *extends* [`Args`](/api/default/interfaces/Args.md) | Overrides schema type. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `base` | `T` | The base schema to extend. |
| `overrides` | `U` | Fields to override or add. |

## Returns

`Omit<T, keyof U> & U` — A new schema with overrides applied.

## Examples

```ts
const base = args({ port: withDefault(integer(), 8080) })
const strict = extend(base, { port: required(integer({ min: 1, max: 65535 })) })
```

---

---
url: /api/combinators/functions/float.md
---
# Function: float()

## Call Signature

```ts
export declare function float<const R extends boolean>(opts: FloatOptions & {
  required: R;
}): WithRequiredOption<CombinatorSchema<number>, R>
```

Create a floating-point argument schema with optional range validation.

Rejects `NaN` and `Infinity` values.

### Type Parameters

| Name | Description |
| --- | --- |
| `R` *extends* `boolean` | The type of `required` in the options, which the schema keeps. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`FloatOptions`](/api/combinators/interfaces/FloatOptions.md) & { [`required`](/api/combinators/functions/required.md): `R` } | Range options. |

### Returns

`WithRequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`number`>, `R`> — A combinator schema that resolves to number (float).

### Examples

```ts
const args = {
  ratio: float({ min: 0, max: 1 })
}
```

## Call Signature

```ts
export declare function float<const R extends boolean | undefined = boolean | undefined>(opts?: FloatOptions & {
  required?: R;
}): WithUnrequiredOption<CombinatorSchema<number>, R>
```

Create a floating-point argument schema with optional range validation.

Rejects `NaN` and `Infinity` values.

### Type Parameters

| Name | Description |
| --- | --- |
| `R` *extends* `boolean \| undefined` = `boolean \| undefined` | The type of `required` in the options, which the schema keeps when it may be `false` but not `true`, as for `optional ? { required: false } : {}`, so that a positional argument with it is optional. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`FloatOptions`](/api/combinators/interfaces/FloatOptions.md) & { [`required`](/api/combinators/functions/required.md)?: `R` } | Range options. *(optional)* |

### Returns

`WithUnrequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`number`>, `R`> — A combinator schema that resolves to number (float).

### Examples

```ts
const args = {
  ratio: float({ min: 0, max: 1 })
}
```

## Call Signature

```ts
export declare function float(opts?: FloatOptions): CombinatorSchema<number>
```

Create a floating-point argument schema with optional range validation.

Rejects `NaN` and `Infinity` values.

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`FloatOptions`](/api/combinators/interfaces/FloatOptions.md) | Range options. *(optional)* |

### Returns

[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`number`> — A combinator schema that resolves to number (float).

### Examples

```ts
const args = {
  ratio: float({ min: 0, max: 1 })
}
```

---

---
url: /api/combinators/functions/hidden.md
---
# Function: hidden()

Hide a combinator schema from generated help or usage output.

The original schema is not modified. This only marks renderer metadata and
does not change parsing, validation, defaults, conflicts, or resolved values.
For a union of schemas, such as `strict ? integer() : string()`, each schema gets `hidden: true`.

## Signature

```ts
export declare function hidden<T extends ArgSchema>(schema: T): T extends unknown ? WithFlag<T, CombinatorHidden> & Omit<T, 'hidden'> : never
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` *extends* [`ArgSchema`](/api/default/interfaces/ArgSchema.md) | The schema type. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `schema` | `T` | The base combinator schema. |

## Returns

`T extends unknown ? WithFlag<T, CombinatorHidden> & Omit<T, 'hidden'> : never` — A new schema with `hidden: true`.

## Examples

```ts
const args = {
  legacy: hidden(string())
}
```

---

---
url: /api/combinators/functions/integer.md
---
# Function: integer()

## Call Signature

```ts
export declare function integer<const R extends boolean>(opts: IntegerOptions & {
  required: R;
}): WithRequiredOption<CombinatorSchema<number>, R>
```

Create an integer argument schema with optional range validation.

Only accepts integer values (no decimals).

### Type Parameters

| Name | Description |
| --- | --- |
| `R` *extends* `boolean` | The type of `required` in the options, which the schema keeps. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`IntegerOptions`](/api/combinators/interfaces/IntegerOptions.md) & { [`required`](/api/combinators/functions/required.md): `R` } | Range options. |

### Returns

`WithRequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`number`>, `R`> — A combinator schema that resolves to number (integer).

### Examples

```ts
const args = {
  retries: integer({ min: 0, max: 10 })
}
```

## Call Signature

```ts
export declare function integer<const R extends boolean | undefined = boolean | undefined>(opts?: IntegerOptions & {
  required?: R;
}): WithUnrequiredOption<CombinatorSchema<number>, R>
```

Create an integer argument schema with optional range validation.

Only accepts integer values (no decimals).

### Type Parameters

| Name | Description |
| --- | --- |
| `R` *extends* `boolean \| undefined` = `boolean \| undefined` | The type of `required` in the options, which the schema keeps when it may be `false` but not `true`, as for `optional ? { required: false } : {}`, so that a positional argument with it is optional. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`IntegerOptions`](/api/combinators/interfaces/IntegerOptions.md) & { [`required`](/api/combinators/functions/required.md)?: `R` } | Range options. *(optional)* |

### Returns

`WithUnrequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`number`>, `R`> — A combinator schema that resolves to number (integer).

### Examples

```ts
const args = {
  retries: integer({ min: 0, max: 10 })
}
```

## Call Signature

```ts
export declare function integer(opts?: IntegerOptions): CombinatorSchema<number>
```

Create an integer argument schema with optional range validation.

Only accepts integer values (no decimals).

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`IntegerOptions`](/api/combinators/interfaces/IntegerOptions.md) | Range options. *(optional)* |

### Returns

[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`number`> — A combinator schema that resolves to number (integer).

### Examples

```ts
const args = {
  retries: integer({ min: 0, max: 10 })
}
```

---

---
url: /api/combinators/functions/map.md
---
# Function: map()

## Call Signature

```ts
export declare function map<T, U, S extends CombinatorSchema<T> = CombinatorSchema<T>>(schema: S & CombinatorSchema<T>, transform: (value: T) => U): Modified<S, Combinator<U>>
```

Transform the output of a combinator schema.

Creates a new schema that applies `transform` to the result of `schema.parse`.
The original schema is not modified.
Other modifiers on `schema` (for example [multiple](/api/combinators/functions/multiple.md)) are kept, and `transform` is applied
to each value of a `multiple` schema.

A default set on `schema` is kept, but it does not go through `transform`: when it is used, the
value is the default as is, although it is typed as `U`. Set the default after `map()`, with a
transformed value.

A union of schemas of different types, such as `strict ? integer() : string()`, matches the
last overload, whose `transform` takes a value of any of their types. An instantiation expression
with two type arguments, such as `typeof map<number, string>`, is a type error, since that
overload takes two type arguments too, the first of which must be a schema: give `S` as well, as
in `typeof map<number, string, CombinatorSchema<number>>`.

### Type Parameters

| Name | Description |
| --- | --- |
| `T` | The input schema's parsed type. |
| `U` | The transformed type. |
| `S` *extends* [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> = [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> | The input combinator schema, inferred from `schema`. Its other modifiers are kept. If type arguments are given explicitly without `S`, `S` is `CombinatorSchema<T>`, and the type of the result lacks the other modifiers, although the returned object has them. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `schema` | `S` & [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> | The base combinator schema. |
| `transform` | `(value: T) => U` | The transformation function. |

### Returns

`Modified`<`S`, [`Combinator`](/api/combinators/type-aliases/Combinator.md)<`U`>> — A new combinator schema that resolves to the transformed type.

### Examples

```ts
const args = {
  doubled: map(integer(), n => n * 2)
}
```

## Call Signature

```ts
export declare function map<T, U, S extends CombinatorSchema<T> = CombinatorSchema<T>>(schema: S & Combinator<T>, transform: (value: T) => U): Modified<S, Combinator<U>>
```

Transform the output of a combinator schema, as the first overload does, for a schema that fits
the first overload but that TypeScript does not match with it at first, such as
`positional(integer())`, a class instance or a schema typed by an interface. This overload keeps
such a schema from matching the overload for a union of schemas of different types.

Creates a new schema that applies `transform` to the result of `schema.parse`.
The original schema is not modified.
Other modifiers on `schema` (for example [multiple](/api/combinators/functions/multiple.md)) are kept, and `transform` is applied
to each value of a `multiple` schema.

A default set on `schema` is kept, but it does not go through `transform`: when it is used, the
value is the default as is, although it is typed as `U`. Set the default after `map()`, with a
transformed value.

### Type Parameters

| Name | Description |
| --- | --- |
| `T` | The input schema's parsed type. |
| `U` | The transformed type. |
| `S` *extends* [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> = [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> | The input combinator schema, inferred from `schema`. Its other modifiers are kept. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `schema` | `S` & [`Combinator`](/api/combinators/type-aliases/Combinator.md)<`T`> | The base combinator schema. |
| `transform` | `(value: T) => U` | The transformation function. |

### Returns

`Modified`<`S`, [`Combinator`](/api/combinators/type-aliases/Combinator.md)<`U`>> — A new combinator schema that resolves to the transformed type.

### Examples

```ts
const args = {
  doubled: map(positional(integer()), n => n * 2)
}
```

## Call Signature

```ts
export declare function map<S extends CombinatorSchema<unknown>, U>(schema: S, transform: (value: ParsedType<S>) => U): Modified<S, Combinator<U>>
```

Transform the output of a union of combinator schemas of different types, such as
`strict ? integer() : string()`.

Creates a new schema that applies `transform` to the result of `schema.parse`, which is a value
of any of their types: a number or a string for `strict ? integer() : string()`.
The original schema is not modified.
Other modifiers on `schema` (for example [multiple](/api/combinators/functions/multiple.md)) are kept, and `transform` is applied
to each value of a `multiple` schema.

A default set on `schema` is kept, but it does not go through `transform`: when it is used, the
value is the default as is, although it is typed as `U`. Set the default after `map()`, with a
transformed value.

### Type Parameters

| Name | Description |
| --- | --- |
| `S` *extends* [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`unknown`> | The input combinator schema, inferred from `schema`: a union of schemas of different types. Its other modifiers are kept. |
| `U` | The transformed type. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `schema` | `S` | The base combinator schema. |
| `transform` | `(value: ParsedType<S>) => U` | The transformation function, which takes a value of any of the types that the schemas of the union parse to. |

### Returns

`Modified`<`S`, [`Combinator`](/api/combinators/type-aliases/Combinator.md)<`U`>> — A new combinator schema that resolves to the transformed type.

### Examples

```ts
const strict = process.argv.includes('--strict')
const args = {
  // `value` is a number or a string
  timeout: map(strict ? integer({ min: 0 }) : string(), value => String(value))
}
```

---

---
url: /api/combinators/functions/merge.md
---
# Function: merge()

## Call Signature

```ts
export declare function merge<A extends Args, B extends Args>(a: A, b: B): Omit<A, keyof B> & B
```

Compose multiple [Args](/api/default/interfaces/Args.md) schemas into one.

On key conflicts the later schema wins (last-write-wins).

### Type Parameters

| Name | Description |
| --- | --- |
| `A` *extends* [`Args`](/api/default/interfaces/Args.md) | First schema type. |
| `B` *extends* [`Args`](/api/default/interfaces/Args.md) | Second schema type. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `A` | First schema. |
| `b` | `B` | Second schema. |

### Returns

`Omit<A, keyof B> & B` — A merged schema containing all fields.

### Examples

```ts
const common = args({ verbose: boolean() })
const network = args({ host: required(string()), port: withDefault(integer(), 8080) })
const schema = merge(common, network)
```

## Call Signature

```ts
export declare function merge<A extends Args, B extends Args, C extends Args>(a: A, b: B, c: C): Omit<Omit<A, keyof B | keyof C> & Omit<B, keyof C>, never> & C
```

Compose multiple [Args](/api/default/interfaces/Args.md) schemas into one.

### Type Parameters

| Name |
| --- |
| `A` *extends* [`Args`](/api/default/interfaces/Args.md) |
| `B` *extends* [`Args`](/api/default/interfaces/Args.md) |
| `C` *extends* [`Args`](/api/default/interfaces/Args.md) |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `A` | First schema. |
| `b` | `B` | Second schema. |
| `c` | `C` | Third schema. |

### Returns

`Omit<Omit<A, keyof B | keyof C> & Omit<B, keyof C>, never> & C` — A merged schema containing all fields.

## Call Signature

```ts
export declare function merge<A extends Args, B extends Args, C extends Args, D extends Args>(a: A, b: B, c: C, d: D): MergeArgs<[A, B, C, D]>
```

Compose multiple [Args](/api/default/interfaces/Args.md) schemas into one.

### Type Parameters

| Name |
| --- |
| `A` *extends* [`Args`](/api/default/interfaces/Args.md) |
| `B` *extends* [`Args`](/api/default/interfaces/Args.md) |
| `C` *extends* [`Args`](/api/default/interfaces/Args.md) |
| `D` *extends* [`Args`](/api/default/interfaces/Args.md) |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `a` | `A` | First schema. |
| `b` | `B` | Second schema. |
| `c` | `C` | Third schema. |
| `d` | `D` | Fourth schema. |

### Returns

`MergeArgs<[A, B, C, D]>` — A merged schema containing all fields.

## Call Signature

```ts
export declare function merge<T extends Args[]>(...schemas: T): MergeArgs<T>
```

Compose multiple [Args](/api/default/interfaces/Args.md) schemas into one.

### Type Parameters

| Name |
| --- |
| `T` *extends* [`Args`](/api/default/interfaces/Args.md)\[] |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `schemas` | `T` | The schemas to merge. |

### Returns

`MergeArgs<T>` — A merged schema containing all fields.

---

---
url: /api/combinators/functions/multiple.md
---
# Function: multiple()

Mark a combinator schema as accepting multiple values.

The resolved value becomes an array. The original schema is not modified.
Other modifiers on `schema` (for example [required](/api/combinators/functions/required.md)) are kept.

## Signature

```ts
export declare function multiple<S extends CombinatorSchema<unknown>>(schema: S): Modified<S, CombinatorMultiple>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `S` *extends* [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`unknown`> | The input combinator schema. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `schema` | `S` | The base combinator schema. |

## Returns

`Modified<S, CombinatorMultiple>` — A copy of `schema` with `multiple: true`.

## Examples

```ts
const args = {
  tags: multiple(string())
}
// typeof values.tags === string[]
```

---

---
url: /api/combinators/functions/number.md
---
# Function: number()

## Call Signature

```ts
export declare function number<const R extends boolean>(opts: NumberOptions & {
  required: R;
}): WithRequiredOption<CombinatorSchema<number>, R>
```

Create a number argument schema with optional range validation.

Accepts any numeric value (integer or float).

### Type Parameters

| Name | Description |
| --- | --- |
| `R` *extends* `boolean` | The type of `required` in the options, which the schema keeps. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`NumberOptions`](/api/combinators/interfaces/NumberOptions.md) & { [`required`](/api/combinators/functions/required.md): `R` } | Range options. |

### Returns

`WithRequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`number`>, `R`> — A combinator schema that resolves to number.

### Examples

```ts
const args = {
  timeout: number({ min: 0, max: 30000 })
}
```

## Call Signature

```ts
export declare function number<const R extends boolean | undefined = boolean | undefined>(opts?: NumberOptions & {
  required?: R;
}): WithUnrequiredOption<CombinatorSchema<number>, R>
```

Create a number argument schema with optional range validation.

Accepts any numeric value (integer or float).

### Type Parameters

| Name | Description |
| --- | --- |
| `R` *extends* `boolean \| undefined` = `boolean \| undefined` | The type of `required` in the options, which the schema keeps when it may be `false` but not `true`, as for `optional ? { required: false } : {}`, so that a positional argument with it is optional. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`NumberOptions`](/api/combinators/interfaces/NumberOptions.md) & { [`required`](/api/combinators/functions/required.md)?: `R` } | Range options. *(optional)* |

### Returns

`WithUnrequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`number`>, `R`> — A combinator schema that resolves to number.

### Examples

```ts
const args = {
  timeout: number({ min: 0, max: 30000 })
}
```

## Call Signature

```ts
export declare function number(opts?: NumberOptions): CombinatorSchema<number>
```

Create a number argument schema with optional range validation.

Accepts any numeric value (integer or float).

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`NumberOptions`](/api/combinators/interfaces/NumberOptions.md) | Range options. *(optional)* |

### Returns

[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`number`> — A combinator schema that resolves to number.

### Examples

```ts
const args = {
  timeout: number({ min: 0, max: 30000 })
}
```

---

---
url: /api/combinators/functions/positional.md
---
# Function: positional()

## Call Signature

```ts
export declare function positional<T, S extends CombinatorSchema<T> = CombinatorSchema<T>>(parser: S & CombinatorSchema<T>): PositionalOf<S>
```

Create a positional argument schema.

Without a parser, resolves to string.
With a parser (e.g., `positional(integer())`), resolves to the parser's return type.

The positional argument keeps `required`, `default` and `multiple` of the parser, with their
types: `positional(unrequired(integer()))` is optional, and `positional(multiple(integer()))`
resolves to an array, as `multiple(positional(integer()))` does.

An instantiation expression with one type argument, such as `typeof positional<number>`, is a
type error, since the overload for a union of schemas and the overloads for options take one
type argument too, which must be a schema for the former and a boolean (the type of `required`)
for the latter: give `S` as well, as in `typeof positional<number, CombinatorSchema<number>>`.

### Type Parameters

| Name | Description |
| --- | --- |
| `T` | The parser's resolved type. |
| `S` *extends* [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> = [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> | The type of the parser, inferred from `parser`, whose `required`, `default`, `multiple`, `description`, `hidden` and `metavar` the positional argument keeps. If type arguments are given explicitly without `S`, `S` is `CombinatorSchema<T>`, and the type of the result lacks them, although the returned object has them. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `parser` | `S` & [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> | The parser combinator schema. |

### Returns

`PositionalOf<S>` — A positional argument schema resolving to the parser's type.

### Examples

```ts
const args = {
  command: positional(),           // resolves to string
  port: positional(integer()),     // resolves to number
  query: unrequired(positional())  // optional positional
}
```

## Call Signature

```ts
export declare function positional<S extends CombinatorSchema<unknown>>(parser: S): PositionalOf<S>
```

Create a positional argument schema from a union of combinator schemas of different types, such
as `strict ? integer() : string()`.

The positional argument resolves to a value of any of their types: a number or a string for
`strict ? integer() : string()`. Each schema of the union keeps its `required`, `default` and
`multiple`, and the argument is present only when each of them gives it a value:
`positional(strict ? multiple(integer()) : string())` resolves to an array of numbers or a
string, and is optional, since a `multiple` positional argument without `required: true` or a
default may be missing.

### Type Parameters

| Name | Description |
| --- | --- |
| `S` *extends* [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`unknown`> | The type of the parser, inferred from `parser`: a union of schemas of different types. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `parser` | `S` | The parser combinator schema. |

### Returns

`PositionalOf<S>` — A positional argument schema resolving to a value of any of the types that the schemas of the union parse to, in an array for a `multiple` schema.

### Examples

```ts
const strict = process.argv.includes('--strict')
const args = {
  // a number or a string
  port: positional(strict ? integer({ min: 1 }) : string())
}
```

## Call Signature

```ts
export declare function positional<const R extends boolean>(parser: BaseOptions & {
  required: R;
}): WithRequiredOption<Omit<CombinatorSchema<string>, 'type'> & ArgSchemaPositionalType, R>
```

Create a positional argument schema.

Without a parser, resolves to string.
With a parser (e.g., `positional(integer())`), resolves to the parser's return type.

Without a parser, the schema has a `parse` function that returns the value as is, so that the
modifiers, such as [multiple](/api/combinators/functions/multiple.md) and [withDefault](/api/combinators/functions/withDefault.md), take it: `multiple(positional())`
collects the values as strings.

With `required: false` in the options, the positional argument is optional, in its type too. A
`required` of type `boolean`, which may be `false`, types it as optional as well.

### Type Parameters

| Name | Description |
| --- | --- |
| `R` *extends* `boolean` | The type of `required` in the options, which the positional argument keeps. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `parser` | [`BaseOptions`](/api/combinators/interfaces/BaseOptions.md) & { [`required`](/api/combinators/functions/required.md): `R` } | Base options (description, short, hidden, required). `short` has no effect on a positional argument. |

### Returns

`WithRequiredOption`<`Omit`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`string`>, 'type'> & `ArgSchemaPositionalType`, `R`> — A positional argument schema resolving to string.

### Examples

```ts
const args = {
  command: positional(),           // resolves to string
  port: positional(integer()),     // resolves to number
  query: unrequired(positional())  // optional positional
}
```

## Call Signature

```ts
export declare function positional<const R extends boolean | undefined = boolean | undefined>(parser?: BaseOptions & {
  required?: R;
}): WithUnrequiredOption<Omit<CombinatorSchema<string>, 'type'> & ArgSchemaPositionalType, R>
```

Create a positional argument schema.

Without a parser, resolves to string.
With a parser (e.g., `positional(integer())`), resolves to the parser's return type.

Without a parser, the schema has a `parse` function that returns the value as is, so that the
modifiers, such as [multiple](/api/combinators/functions/multiple.md) and [withDefault](/api/combinators/functions/withDefault.md), take it: `multiple(positional())`
collects the values as strings.

With a `required: false` that the options have only in some cases, with no `required` in the
others, such as `optional ? { required: false } : {}`, the positional argument is optional, in
its type too.

### Type Parameters

| Name | Description |
| --- | --- |
| `R` *extends* `boolean \| undefined` = `boolean \| undefined` | The type of `required` in the options, which the positional argument keeps when it may be `false` but not `true`, as for `optional ? { required: false } : {}`. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `parser` | [`BaseOptions`](/api/combinators/interfaces/BaseOptions.md) & { [`required`](/api/combinators/functions/required.md)?: `R` } | Optional base options (description, short, hidden, required). `short` has no effect on a positional argument. *(optional)* |

### Returns

`WithUnrequiredOption`<`Omit`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`string`>, 'type'> & `ArgSchemaPositionalType`, `R`> — A positional argument schema resolving to string.

### Examples

```ts
const args = {
  command: positional(),           // resolves to string
  port: positional(integer()),     // resolves to number
  query: unrequired(positional())  // optional positional
}
```

## Call Signature

```ts
export declare function positional(parser?: BaseOptions): Omit<CombinatorSchema<string>, 'type'> & ArgSchemaPositionalType
```

Create a positional argument schema.

Without a parser, resolves to string.
With a parser (e.g., `positional(integer())`), resolves to the parser's return type.

Without a parser, the schema has a `parse` function that returns the value as is, so that the
modifiers, such as [multiple](/api/combinators/functions/multiple.md) and [withDefault](/api/combinators/functions/withDefault.md), take it: `multiple(positional())`
collects the values as strings.

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `parser` | [`BaseOptions`](/api/combinators/interfaces/BaseOptions.md) | Optional base options (description, short, hidden, required). `short` has no effect on a positional argument. *(optional)* |

### Returns

`Omit`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`string`>, 'type'> & `ArgSchemaPositionalType` — A positional argument schema resolving to string.

### Examples

```ts
const args = {
  command: positional(),           // resolves to string
  port: positional(integer()),     // resolves to number
  query: unrequired(positional())  // optional positional
}
```

---

---
url: /api/combinators/functions/required.md
---
# Function: required()

Mark a combinator schema as required.

The original schema is not modified.
Other modifiers on `schema` (for example [multiple](/api/combinators/functions/multiple.md)) are kept.

## Signature

```ts
export declare function required<S extends CombinatorSchema<unknown>>(schema: S): Modified<S, CombinatorRequired>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `S` *extends* [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`unknown`> | The input combinator schema. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `schema` | `S` | The base combinator schema. |

## Returns

`Modified<S, CombinatorRequired>` — A copy of `schema` with `required: true`.

## Examples

```ts
const args = {
  name: required(string())
}
```

---

---
url: /api/combinators/functions/short.md
---
# Function: short()

Set a short alias on a combinator schema.

The original schema is not modified.
Other modifiers on `schema` (for example [multiple](/api/combinators/functions/multiple.md)) are kept.

## Signature

```ts
export declare function short<T, A extends string, S extends CombinatorSchema<T> = CombinatorSchema<T>>(schema: S, alias: A): Modified<S, CombinatorShort<A>>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` | The schema's parsed type, when type arguments are given explicitly. It is not inferred, so that `schema` can be a union of schemas of different types. |
| `A` *extends* `string` | The short alias string literal type. |
| `S` *extends* [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> = [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> | The input combinator schema, inferred from `schema`. Its other modifiers are kept. If type arguments are given explicitly without `S`, `S` is `CombinatorSchema<T>`, and the type of the result lacks the other modifiers, although the returned object has them. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `schema` | `S` | The base combinator schema. |
| `alias` | `A` | Single character short alias. |

## Returns

`Modified<S, CombinatorShort<A>>` — A new schema with the short alias set.

## Examples

```ts
const args = {
  verbose: short(boolean(), 'v')
}
// Usage: -v or --verbose
```

---

---
url: /api/combinators/functions/string.md
---
# Function: string()

## Call Signature

```ts
export declare function string<const R extends boolean>(opts: StringOptions & {
  required: R;
}): WithRequiredOption<CombinatorSchema<string>, R>
```

Create a string argument schema with optional validation.

### Type Parameters

| Name | Description |
| --- | --- |
| `R` *extends* `boolean` | The type of `required` in the options, which the schema keeps. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`StringOptions`](/api/combinators/interfaces/StringOptions.md) & { [`required`](/api/combinators/functions/required.md): `R` } | Validation options. |

### Returns

`WithRequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`string`>, `R`> — A combinator schema that resolves to string.

### Examples

```ts
const args = {
  name: string({ minLength: 1, maxLength: 50 })
}
```

## Call Signature

```ts
export declare function string<const R extends boolean | undefined = boolean | undefined>(opts?: StringOptions & {
  required?: R;
}): WithUnrequiredOption<CombinatorSchema<string>, R>
```

Create a string argument schema with optional validation.

### Type Parameters

| Name | Description |
| --- | --- |
| `R` *extends* `boolean \| undefined` = `boolean \| undefined` | The type of `required` in the options, which the schema keeps when it may be `false` but not `true`, as for `optional ? { required: false } : {}`, so that a positional argument with it is optional. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`StringOptions`](/api/combinators/interfaces/StringOptions.md) & { [`required`](/api/combinators/functions/required.md)?: `R` } | Validation options. *(optional)* |

### Returns

`WithUnrequiredOption`<[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`string`>, `R`> — A combinator schema that resolves to string.

### Examples

```ts
const args = {
  name: string({ minLength: 1, maxLength: 50 })
}
```

## Call Signature

```ts
export declare function string(opts?: StringOptions): CombinatorSchema<string>
```

Create a string argument schema with optional validation.

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `opts` | [`StringOptions`](/api/combinators/interfaces/StringOptions.md) | Validation options. *(optional)* |

### Returns

[`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`string`> — A combinator schema that resolves to string.

### Examples

```ts
const args = {
  name: string({ minLength: 1, maxLength: 50 })
}
```

---

---
url: /api/combinators/functions/unrequired.md
---
# Function: unrequired()

Mark a combinator schema as not required.

Useful for overriding a base combinator that was created with `required: true`,
or for making a positional argument explicitly optional.
The original schema is not modified.
For a union of schemas, such as `strict ? integer() : string()`, each schema gets
`required: false`.

## Signature

```ts
export declare function unrequired<T extends ArgSchema>(schema: T): T extends unknown ? WithFlag<T, CombinatorUnrequired> & Omit<T, 'required'> : never
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` *extends* [`ArgSchema`](/api/default/interfaces/ArgSchema.md) | The schema type. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `schema` | `T` | The base combinator schema. |

## Returns

`T extends unknown ? WithFlag<T, CombinatorUnrequired> & Omit<T, 'required'> : never` — A new schema with `required: false`.

## Examples

```ts
const args = {
  name: unrequired(string({ required: true })),
  query: unrequired(positional())
}
```

---

---
url: /api/combinators/functions/withDefault.md
---
# Function: withDefault()

## Call Signature

```ts
export declare function withDefault<T extends string | boolean | number, D extends T = T, S extends CombinatorSchema<T> = CombinatorSchema<T>>(schema: S & CombinatorSchema<T>, defaultValue: D): Modified<S, CombinatorWithDefault<T>>
```

Set a default value on a combinator schema.

The original schema is not modified. The default must be a value of the schema's parsed type:
`T` is inferred from `schema` only, so `withDefault(choice(['auto', 'always']), 'awlays')` is a
type error instead of adding `'awlays'` to the type. The schema must parse to a string, number or
boolean, since the default can only be one of them and does not go through `parse`: a schema that
parses to another type, such as a `Date`, or whose `parse` can return `null` or `undefined`,
cannot have a default, and giving it one is a type error.
Other modifiers on `schema` (for example [multiple](/api/combinators/functions/multiple.md)) are kept. The default of a `multiple`
schema is one value of the parsed type, which becomes the only element of the array.

A union of schemas of different types, such as `strict ? integer() : string()`, matches the
last overload, whose default may be a value of any of their types. An instantiation expression
with one type argument, such as `typeof withDefault<number>`, is a type error, since that
overload takes one type argument too, which must be a schema: give `D` as well, as in
`typeof withDefault<number, number>`.

### Type Parameters

| Name | Description |
| --- | --- |
| `T` *extends* `string \| boolean \| number` | The schema's parsed type. |
| `D` *extends* `T` = `T` | The type of the default value, which must be assignable to `T`. |
| `S` *extends* [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> = [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> | The input combinator schema, inferred from `schema`. Its other modifiers are kept. If type arguments are given explicitly without `S`, `S` is `CombinatorSchema<T>`, and the type of the result lacks the other modifiers, although the returned object has them. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `schema` | `S` & [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> | The base combinator schema. |
| `defaultValue` | `D` | The default value, a value of the schema's parsed type. |

### Returns

`Modified<S, CombinatorWithDefault<T>>` — A new schema with the default value set.

### Examples

```ts
const args = {
  port: withDefault(integer({ min: 1, max: 65535 }), 8080)
}
```

## Call Signature

```ts
export declare function withDefault<T extends string | boolean | number, D extends T = T, S extends CombinatorSchema<T> = CombinatorSchema<T>>(schema: S & Combinator<T>, defaultValue: D): Modified<S, CombinatorWithDefault<T>>
```

Set a default value on a combinator schema, as the first overload does, for a schema that fits
the first overload but that TypeScript does not match with it at first, such as
`positional(integer())`, a class instance or a schema typed by an interface. This overload keeps
such a schema from matching the overload for a union of schemas of different types.

The original schema is not modified. The default must be a value of the schema's parsed type. The
schema must parse to a string, number or boolean, since the default can only be one of them and
does not go through `parse`.
Other modifiers on `schema` (for example [multiple](/api/combinators/functions/multiple.md)) are kept. The default of a `multiple`
schema is one value of the parsed type, which becomes the only element of the array.

### Type Parameters

| Name | Description |
| --- | --- |
| `T` *extends* `string \| boolean \| number` | The schema's parsed type. |
| `D` *extends* `T` = `T` | The type of the default value, which must be assignable to `T`. |
| `S` *extends* [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> = [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`T`> | The input combinator schema, inferred from `schema`. Its other modifiers are kept. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `schema` | `S` & [`Combinator`](/api/combinators/type-aliases/Combinator.md)<`T`> | The base combinator schema. |
| `defaultValue` | `D` | The default value, a value of the schema's parsed type. |

### Returns

`Modified<S, CombinatorWithDefault<T>>` — A new schema with the default value set.

### Examples

```ts
const args = {
  port: withDefault(positional(integer()), 8080)
}
```

## Call Signature

```ts
export declare function withDefault<S extends CombinatorSchema<string | boolean | number>>(schema: S, defaultValue: unknown extends ParsedType<S> ? never : ParsedType<S>): Modified<S, CombinatorWithDefault<ParsedType<S>> & Combinator<ParsedType<S>>>
```

Set a default value on a union of combinator schemas of different types, such as
`strict ? integer() : string()`.

The original schema is not modified. The default must be a value of one of the types that the
schemas of the union parse to: a number or a string for `strict ? integer() : string()`. They
must parse to a string, number or boolean, since the default can only be one of them and does
not go through `parse`. A schema typed as `any` matches the first overload instead.
Other modifiers on `schema` (for example [multiple](/api/combinators/functions/multiple.md)) are kept. The default of a `multiple`
schema is one value, which becomes the only element of the array.
Since the default is used for whichever schema of the union is in use, the `parse` of each schema
is typed as returning a value of any of the types that the schemas parse to:
`withDefault(strict ? multiple(integer()) : string(), 'none')` resolves to
`(number | string)[] | number | string`.

### Type Parameters

| Name | Description |
| --- | --- |
| `S` *extends* [`CombinatorSchema`](/api/combinators/type-aliases/CombinatorSchema.md)<`string` | `boolean` | `number`> | The input combinator schema, inferred from `schema`: a union of schemas of different types. Its other modifiers are kept. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `schema` | `S` | The base combinator schema. |
| `defaultValue` | `unknown extends ParsedType<S> ? never : ParsedType<S>` | The default value, a value of one of the types that the schemas of the union parse to. |

### Returns

`Modified`<`S`, `CombinatorWithDefault`<`ParsedType`<`S`>> & [`Combinator`](/api/combinators/type-aliases/Combinator.md)<`ParsedType`<`S`>>> — A new schema with the default value set.

### Examples

```ts
const strict = process.argv.includes('--strict')
const args = {
  timeout: withDefault(strict ? integer({ min: 0 }) : string(), 'none')
}
// typeof values.timeout === number | string
```

---

---
url: /api/combinators/interfaces/BaseOptions.md
---
# Interface: BaseOptions

Common options shared by all base combinators.

## Signature

```ts
export interface BaseOptions
```

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `description` *(optional)* | `string` | Human-readable description for help text generation. |
| `hidden` *(optional)* | `boolean` | Hide from generated help or usage output. |
| `required` *(optional)* | `boolean` | Mark as required. A literal `true` or `false` is kept in the type of the schema: `true` types the value as present, as [required](/api/combinators/functions/required.md) does, and `false` makes a positional argument optional. So does a `required` that may be `false`: one of type `boolean` that the options always have, or a `false` that they have only in some cases, with no `required` in the others, such as `optional ? { required: false } : {}`. A `true` that the options have only in some cases, such as `strict ? { required: true } : {}`, is not kept. TypeScript widens a `required: true` to `boolean` in options written apart from the call, such as `const options = { required: true }`, which makes a positional argument optional, as a `required` typed as `any` does: write such options `as const`. Options whose type only says that `required` is a `boolean` that may be missing, as the type of this property does, keep a positional argument typed as present, as options without `required` do. So do `optional ? { required: flag } : {}`, and the options that a generic helper takes as a type parameter, such as `T extends IntegerOptions`, whose `required` TypeScript reads from the constraint. Use [unrequired](/api/combinators/functions/unrequired.md) for such a positional argument when it may be missing. |
| `short` *(optional)* | `string` | Single character short alias. |

---

---
url: /api/combinators/interfaces/BooleanOptions.md
---
# Interface: BooleanOptions

Options for the [boolean](/api/combinators/functions/boolean.md) combinator.

## Extends

* [`BaseOptions`](/api/combinators/interfaces/BaseOptions.md)

## Signature

```ts
export interface BooleanOptions extends BaseOptions
```

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `negatable` *(optional)* | `boolean` | Enable negation with `--no-` prefix. |

---

---
url: /api/combinators/interfaces/CombinatorOptions.md
---
# Interface: CombinatorOptions\<T>

Options for the [combinator](/api/combinators/functions/combinator.md) factory function.

## Extends

* [`BaseOptions`](/api/combinators/interfaces/BaseOptions.md)

## Signature

```ts
export interface CombinatorOptions<T> extends BaseOptions
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` | The parsed value type. |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `metavar` *(optional)* | `string` | Display name hint for help text generation. **Default:** `'custom'` |
| `parse` | `(value: string) => T` | The parse function that converts a string to the desired type. It is called synchronously, as [ArgSchema](/api/default/interfaces/ArgSchema.md).parse is: a promise that it returns becomes the value as is, and its rejection is not reported as an error. |

### parse Parameters

| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | The input string value. |

### parse Returns

`T` — The parsed value of type T.

---

---
url: /api/combinators/interfaces/FloatOptions.md
---
# Interface: FloatOptions

Options for the [float](/api/combinators/functions/float.md) combinator.

## Extends

* [`BaseOptions`](/api/combinators/interfaces/BaseOptions.md)

## Signature

```ts
export interface FloatOptions extends BaseOptions
```

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `max` *(optional)* | `number` | Maximum value (inclusive). |
| `min` *(optional)* | `number` | Minimum value (inclusive). |

---

---
url: /api/combinators/interfaces/IntegerOptions.md
---
# Interface: IntegerOptions

Options for the [integer](/api/combinators/functions/integer.md) combinator.

## Extends

* [`BaseOptions`](/api/combinators/interfaces/BaseOptions.md)

## Signature

```ts
export interface IntegerOptions extends BaseOptions
```

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `max` *(optional)* | `number` | Maximum value (inclusive). |
| `min` *(optional)* | `number` | Minimum value (inclusive). |

---

---
url: /api/combinators/interfaces/NumberOptions.md
---
# Interface: NumberOptions

Options for the [number](/api/combinators/functions/number.md) combinator.

## Extends

* [`BaseOptions`](/api/combinators/interfaces/BaseOptions.md)

## Signature

```ts
export interface NumberOptions extends BaseOptions
```

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `max` *(optional)* | `number` | Maximum value (inclusive). |
| `min` *(optional)* | `number` | Minimum value (inclusive). |

---

---
url: /api/combinators/interfaces/StringOptions.md
---
# Interface: StringOptions

Options for the [string](/api/combinators/functions/string.md) combinator.

## Extends

* [`BaseOptions`](/api/combinators/interfaces/BaseOptions.md)

## Signature

```ts
export interface StringOptions extends BaseOptions
```

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `maxLength` *(optional)* | `number` | Maximum string length. |
| `minLength` *(optional)* | `number` | Minimum string length. |
| `pattern` *(optional)* | `RegExp` | Regular expression pattern the value must match. |

---

---
url: /api/combinators/type-aliases/Combinator.md
---
# Type Alias: Combinator\<T>

A combinator produced by combinator factory functions.

## Signature

```ts
export type Combinator<T> = { parse: (value: string) => T }
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` | The parsed value type. |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `parse` | `(value: string) => T` | The parse function that converts a string to the desired type. |

### parse Parameters

| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | The input string value. |

### parse Returns

`T` — The parsed value of type T.

---

---
url: /api/combinators/type-aliases/CombinatorSchema.md
---
# Type Alias: CombinatorSchema\<T>

A schema produced by combinator factory functions.
Any [ArgSchema](/api/default/interfaces/ArgSchema.md) whose parse function returns `T` qualifies. The `parse` of
[ArgSchema](/api/default/interfaces/ArgSchema.md), which returns `any`, is left out, so that a schema fits only where the values
that it parses do: `integer()` is not a `CombinatorSchema<string>`.

## Signature

```ts
export type CombinatorSchema<T> = Omit<ArgSchema, 'parse'> & Combinator<T>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` | The parsed value type. |

---

---
url: /api/context.md
---
# context

The entry for gunshi context.
This module is exported for the purpose of testing the command.

## Example

```js
import { createCommandContext } from 'gunshi/context'
```

## Functions

| Function | Description |
| ------ | ------ |
| [createCommandContext](/api/context/functions/createCommandContext.md) | Create a command context. |

## Interfaces

| Interface | Description |
| ------ | ------ |
| [CommandContextParams](/api/context/interfaces/CommandContextParams.md) | Parameters of [createCommandContext](/api/context/functions/createCommandContext.md) |

---

---
url: /api/context/functions/createCommandContext.md
---
# Function: createCommandContext()

Create a command context.

## Signature

```ts
export async function createCommandContext<
  G extends GunshiParamsConstraint = DefaultGunshiParams,
  V extends ArgValues<ExtractArgs<G>> = ArgValues<ExtractArgs<G>>,
  C extends Command<G> | LazyCommand<G> = Command<G>,
  E extends Record<string, CommandContextExtension> = {}
>({
  args = {} as ExtractArgs<G>,
  explicit = {} as ExtractArgExplicitlyProvided<G>,
  values = {} as V,
  positionals = [],
  rest = [],
  argv = [],
  tokens = [],
  command = {} as C,
  extensions = {} as E,
  cliOptions = {} as CliOptions<G>,
  callMode = 'entry',
  commandPath = [],
  omitted = false,
  validationError
}: CommandContextParams<G, V, C, E>): Promise<CommandContextResult<G, E>>
```

## Type Parameters

| Name |
| --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) |
| `V` *extends* [`ArgValues`](/api/default/type-aliases/ArgValues.md)<`ExtractArgs`<`G`>> = [`ArgValues`](/api/default/type-aliases/ArgValues.md)<`ExtractArgs`<`G`>> |
| `C` *extends* [`Command`](/api/default/interfaces/Command.md)<`G`> | [`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<`G`> = [`Command`](/api/default/interfaces/Command.md)<`G`> |
| `E` *extends* `Record`<`string`, [`CommandContextExtension`](/api/default/interfaces/CommandContextExtension.md)> = `{}` |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `param` | [`CommandContextParams`](/api/context/interfaces/CommandContextParams.md)<`G`, `V`, `C`, `E`> | A [parameters](/api/context/interfaces/CommandContextParams.md) to create a command context. |

## Returns

`Promise<CommandContextResult<G, E>>` — A [command context](/api/default/interfaces/CommandContext.md), which is readonly.

---

---
url: /api/context/interfaces/CommandContextParams.md
---
# Interface: CommandContextParams\<G, V, C, E>

Parameters of [createCommandContext](/api/context/functions/createCommandContext.md)

## Signature

```ts
export interface CommandContextParams<
  G extends GunshiParams | { args: Args } | { extensions: ExtendContext },
  V extends ArgValues<ExtractArgs<G>>,
  C extends Command<G> | LazyCommand<G> = Command<G>,
  E extends Record<string, CommandContextExtension> = Record<string, CommandContextExtension>
>
```

## Type Parameters

| Name |
| --- |
| `G` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) | { [`args`](/api/combinators/functions/args.md): [`Args`](/api/default/interfaces/Args.md) } | { `extensions`: [`ExtendContext`](/api/default/type-aliases/ExtendContext.md) } |
| `V` *extends* [`ArgValues`](/api/default/type-aliases/ArgValues.md)<`ExtractArgs`<`G`>> |
| `C` *extends* [`Command`](/api/default/interfaces/Command.md)<`G`> | [`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<`G`> = [`Command`](/api/default/interfaces/Command.md)<`G`> |
| `E` *extends* `Record`<`string`, [`CommandContextExtension`](/api/default/interfaces/CommandContextExtension.md)> = `Record`<`string`, [`CommandContextExtension`](/api/default/interfaces/CommandContextExtension.md)> |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `args` *(optional)* | `ExtractArgs<G>` | An arguments of target command |
| `argv` *(optional)* | `string[]` | Original command line arguments |
| `callMode` *(optional)* | [`CommandCallMode`](/api/default/type-aliases/CommandCallMode.md) | Command call mode. |
| `cliOptions` *(optional)* | [`CliOptions`](/api/default/interfaces/CliOptions.md)<`G`> | A command options, which is spicialized from `cli` function |
| `command` *(optional)* | `C` | A target command |
| `commandPath` *(optional)* | `string[]` | The path of nested sub-commands resolved to reach the current command. |
| `explicit` *(optional)* | `ExtractArgExplicitlyProvided<G>` | Explicitly provided arguments |
| `extensions` *(optional)* | `E` | Plugin extensions to apply as the command context extension. |
| `omitted` *(optional)* | `boolean` | Whether the command is omitted |
| `positionals` *(optional)* | `string[]` | A positionals arguments, which passed to the target command |
| `rest` *(optional)* | `string[]` | A rest arguments, which passed to the target command |
| `tokens` *(optional)* | [`ArgToken`](/api/default/interfaces/ArgToken.md)\[] | Argument tokens that are parsed by the `parseArgs` function |
| `validationError` *(optional)* | `AggregateError` | Validation error from argument parsing. |
| `values` *(optional)* | `V` | A values of target command |

---

---
url: /api/default.md
---
# 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`.
* Some basic type definitions, such as `CommandContext`, `Plugin`, `PluginContext`, etc.

## Example

```js
import { cli } from 'gunshi'
```

## Variables

| Variable | Description |
| ------ | ------ |
| [ANONYMOUS\_COMMAND\_NAME](/api/default/variables/ANONYMOUS_COMMAND_NAME.md) |  |
| [CommandNotFoundErrorKeys](/api/default/variables/CommandNotFoundErrorKeys.md) | Command not found error resource keys. |
| [CommandResolutionErrorKeys](/api/default/variables/CommandResolutionErrorKeys.md) | Command resolution error resource keys. |

## Functions

| Function | Description |
| ------ | ------ |
| [cli](/api/default/functions/cli.md) | Run the command. |
| [hasPriorityValidationError](/api/default/functions/hasPriorityValidationError.md) | Check whether validation errors should be handled before version, help, or command execution. |
| [isArgsValidationError](/api/default/functions/isArgsValidationError.md) | Check whether an error is an [ArgsValidationError](/api/default/classes/ArgsValidationError.md). |
| [isCommandNotFoundError](/api/default/functions/isCommandNotFoundError.md) | Check whether an error is a [CommandNotFoundError](/api/default/classes/CommandNotFoundError.md). |
| [isCommandResolutionError](/api/default/functions/isCommandResolutionError.md) | Check whether an error is a [CommandResolutionError](/api/default/classes/CommandResolutionError.md). |
| [parseArgs](/api/default/functions/parseArgs.md) | Parse command line arguments. |
| [plugin](/api/default/functions/plugin.md) | Define a plugin with extension compatibility and typed dependency extensions |
| [resolveArgs](/api/default/functions/resolveArgs.md) | Resolve command line arguments. |

## Classes

| Class | Description |
| ------ | ------ |
| [ArgsValidationError](/api/default/classes/ArgsValidationError.md) | An error that contains structured metadata for argument validation failures. |
| [CommandNotFoundError](/api/default/classes/CommandNotFoundError.md) | Error raised when a command cannot be resolved. |
| [CommandResolutionError](/api/default/classes/CommandResolutionError.md) | Error raised when command routing cannot produce one consistent command. |
| [DefaultTranslation](/api/default/classes/DefaultTranslation.md) | Default implementation of `TranslationAdapter`. |

## Interfaces

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

## References

### CommandContextParams

Re-exports [CommandContextParams](/api/context/interfaces/CommandContextParams.md)

***

### createCommandContext

Re-exports [createCommandContext](/api/context/functions/createCommandContext.md)

***

### define

Re-exports [define](/api/definition/functions/define.md)

***

### defineWithTypes

Re-exports [defineWithTypes](/api/definition/functions/defineWithTypes.md)

***

### lazy

Re-exports [lazy](/api/definition/functions/lazy.md)

***

### lazyWithTypes

Re-exports [lazyWithTypes](/api/definition/functions/lazyWithTypes.md)

## Type Aliases

| Type Alias | Description |
| ------ | ------ |
| [ArgsValidationErrorCode](/api/default/type-aliases/ArgsValidationErrorCode.md) | A machine-readable argument validation error code. |
| [ArgValues](/api/default/type-aliases/ArgValues.md) | An object that contains the values of the arguments. |
| [Awaitable](/api/default/type-aliases/Awaitable.md) | Awaitable type. |
| [Commandable](/api/default/type-aliases/Commandable.md) | Define a command type. |
| [CommandCallMode](/api/default/type-aliases/CommandCallMode.md) | Command call mode. |
| [CommandContextCore](/api/default/type-aliases/CommandContextCore.md) | Readonly command context available to a command context extension factory. |
| [CommandDecorator](/api/default/type-aliases/CommandDecorator.md) | Command decorator. |
| [CommandExamplesFetcher](/api/default/type-aliases/CommandExamplesFetcher.md) | Command examples fetcher. |
| [CommandLoader](/api/default/type-aliases/CommandLoader.md) | Command loader. |
| [CommandNotFoundErrorCode](/api/default/type-aliases/CommandNotFoundErrorCode.md) | Command not found error code. |
| [CommandNotFoundErrorOptions](/api/default/type-aliases/CommandNotFoundErrorOptions.md) | Options for [CommandNotFoundError](/api/default/classes/CommandNotFoundError.md). |
| [CommandResolutionErrorCode](/api/default/type-aliases/CommandResolutionErrorCode.md) | Command resolution error code. |
| [CommandResolutionErrorOptions](/api/default/type-aliases/CommandResolutionErrorOptions.md) | Options for [CommandResolutionError](/api/default/classes/CommandResolutionError.md). |
| [CommandRunner](/api/default/type-aliases/CommandRunner.md) | Command runner. |
| [DefaultGunshiParams](/api/default/type-aliases/DefaultGunshiParams.md) | Default Gunshi parameters. |
| [ExtendContext](/api/default/type-aliases/ExtendContext.md) | Extend command context type. This type is used to extend the command context with additional properties at [`CommandContext.extensions`](/api/default/interfaces/CommandContext.md#property-extensions). |
| [GunshiParamsConstraint](/api/default/type-aliases/GunshiParamsConstraint.md) | Generic constraint for command-related types. |
| [LazyCommand](/api/default/type-aliases/LazyCommand.md) | Lazy command interface. |
| [OnPluginExtension](/api/default/type-aliases/OnPluginExtension.md) | Plugin extension callback, which is called when the plugin is extended with `extension` option. |
| [Plugin](/api/default/type-aliases/Plugin.md) | Gunshi plugin, which is a function that receives a PluginContext. |
| [PluginExtension](/api/default/type-aliases/PluginExtension.md) | Plugin extension |
| [PluginFunction](/api/default/type-aliases/PluginFunction.md) | Plugin function type |
| [Prettify](/api/default/type-aliases/Prettify.md) | Prettify a type by flattening its structure. |
| [RendererDecorator](/api/default/type-aliases/RendererDecorator.md) | Renderer decorator type. |
| [ValidationErrorsDecorator](/api/default/type-aliases/ValidationErrorsDecorator.md) | Validation errors renderer decorator type. A function that wraps a validation errors renderer to add or modify its behavior. |

---

---
url: /api/default/variables/ANONYMOUS_COMMAND_NAME.md
---
# Variable: ANONYMOUS\_COMMAND\_NAME

## Signature

```ts
export const ANONYMOUS_COMMAND_NAME = '(anonymous)'
```

---

---
url: /api/default/variables/CommandNotFoundErrorKeys.md
---
# Variable: CommandNotFoundErrorKeys

Command not found error resource keys.

## Signature

```ts
export const CommandNotFoundErrorKeys = {
  notFound: 'err:cmd:not-found'
} as const
```

---

---
url: /api/default/variables/CommandResolutionErrorKeys.md
---
# Variable: CommandResolutionErrorKeys

Command resolution error resource keys.

These errors describe an ambiguity or inconsistency while choosing a command from arguments.
They are kept separate from [CommandNotFoundError](/api/default/classes/CommandNotFoundError.md) so consumers can distinguish a typo
from an input whose command interpretation is not unique.

## Signature

```ts
export const CommandResolutionErrorKeys = {
  ambiguous: 'err:cmd:ambiguous',
  inconsistentOptions: 'err:cmd:inconsistent-options',
  lazySchemaMismatch: 'err:cmd:lazy-schema-mismatch'
} as const
```

---

---
url: /api/default/functions/cli.md
---
# Function: cli()

Run the command.

## Call Signature

```ts
export async function cli<G extends GunshiParamsConstraint>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>
```

Run the command.

### Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command and cli options. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `args` | `string[]` | Command line arguments |
| `entry` | [`Command`](/api/default/interfaces/Command.md)<`G`> | [`CommandRunner`](/api/default/type-aliases/CommandRunner.md)<`G`> | [`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<`G`> | A [entry command](/api/default/interfaces/Command.md), an [inline command runner](/api/default/type-aliases/CommandRunner.md), or a [lazily-loaded command](/api/default/type-aliases/LazyCommand.md) |
| `options` | [`CliOptions`](/api/default/interfaces/CliOptions.md)<`G`> | A [CLI options](/api/default/interfaces/CliOptions.md) *(optional)* |

### Returns

`Promise<string | undefined>` — A rendered usage or undefined. if you will use [`CliOptions.usageSilent`](/api/default/interfaces/CliOptions.md#property-usagesilent) option, it will return rendered usage string.

## Call Signature

```ts
export async function cli<
  A extends Args = Args,
  G extends GunshiParams = { args: A; extensions: {} }
>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>
```

Run the command.

### Type Parameters

| Name | Description |
| --- | --- |
| `A` *extends* [`Args`](/api/default/interfaces/Args.md) = [`Args`](/api/default/interfaces/Args.md) | The type of [`arguments`](/api/default/interfaces/Args.md) defined in the command and cli options. |
| `G` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = { [`args`](/api/combinators/functions/args.md): `A`; `extensions`: {} } | - |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `args` | `string[]` | Command line arguments |
| `entry` | [`Command`](/api/default/interfaces/Command.md)<`G`> | [`CommandRunner`](/api/default/type-aliases/CommandRunner.md)<`G`> | [`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<`G`> | A [entry command](/api/default/interfaces/Command.md), an [inline command runner](/api/default/type-aliases/CommandRunner.md), or a [lazily-loaded command](/api/default/type-aliases/LazyCommand.md) |
| `options` | [`CliOptions`](/api/default/interfaces/CliOptions.md)<`G`> | A [CLI options](/api/default/interfaces/CliOptions.md) *(optional)* |

### Returns

`Promise<string | undefined>` — A rendered usage or undefined. if you will use [`CliOptions.usageSilent`](/api/default/interfaces/CliOptions.md#property-usagesilent) option, it will return rendered usage string.

## Call Signature

```ts
export async function cli<
  E extends ExtendContext = ExtendContext,
  G extends GunshiParams = { args: Args; extensions: E }
>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>
```

Run the command.

### Type Parameters

| Name | Description |
| --- | --- |
| `E` *extends* [`ExtendContext`](/api/default/type-aliases/ExtendContext.md) = [`ExtendContext`](/api/default/type-aliases/ExtendContext.md) | An [`ExtendContext`](/api/default/type-aliases/ExtendContext.md) type to specify the shape of command and cli options. |
| `G` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = { [`args`](/api/combinators/functions/args.md): [`Args`](/api/default/interfaces/Args.md); `extensions`: `E` } | - |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `args` | `string[]` | Command line arguments |
| `entry` | [`Command`](/api/default/interfaces/Command.md)<`G`> | [`CommandRunner`](/api/default/type-aliases/CommandRunner.md)<`G`> | [`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<`G`> | A [entry command](/api/default/interfaces/Command.md), an [inline command runner](/api/default/type-aliases/CommandRunner.md), or a [lazily-loaded command](/api/default/type-aliases/LazyCommand.md) |
| `options` | [`CliOptions`](/api/default/interfaces/CliOptions.md)<`G`> | A [CLI options](/api/default/interfaces/CliOptions.md) *(optional)* |

### Returns

`Promise<string | undefined>` — A rendered usage or undefined. if you will use [`CliOptions.usageSilent`](/api/default/interfaces/CliOptions.md#property-usagesilent) option, it will return rendered usage string.

## Call Signature

```ts
export async function cli<G extends GunshiParams = DefaultGunshiParams>(args: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>
```

Run the command.

### Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command and cli options. |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `args` | `string[]` | Command line arguments |
| `entry` | [`Command`](/api/default/interfaces/Command.md)<`G`> | [`CommandRunner`](/api/default/type-aliases/CommandRunner.md)<`G`> | [`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<`G`> | A [entry command](/api/default/interfaces/Command.md), an [inline command runner](/api/default/type-aliases/CommandRunner.md), or a [lazily-loaded command](/api/default/type-aliases/LazyCommand.md) |
| `options` | [`CliOptions`](/api/default/interfaces/CliOptions.md)<`G`> | A [CLI options](/api/default/interfaces/CliOptions.md) *(optional)* |

### Returns

`Promise<string | undefined>` — A rendered usage or undefined. if you will use [`CliOptions.usageSilent`](/api/default/interfaces/CliOptions.md#property-usagesilent) option, it will return rendered usage string.

## Call Signature

```ts
export async function cli(args: string[], entry: SubCommandable, options?: CliOptions): Promise<string | undefined>
```

Run the command.

This overload accepts any command-like object using a loose structural type.
It bypasses TypeScript contravariance issues with callback properties.

Note: This overload MUST be last in the overload list. TypeScript checks overloads
in declaration order and selects the first matching one. The SubCommandable type
is intentionally loose and would match any command, so placing it first would
prevent proper type inference for more specific command types.

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `args` | `string[]` | Command line arguments |
| `entry` | [`SubCommandable`](/api/default/interfaces/SubCommandable.md) | A command-like object (command, command runner, or lazy command) |
| `options` | [`CliOptions`](/api/default/interfaces/CliOptions.md) | A [CLI options](/api/default/interfaces/CliOptions.md) *(optional)* |

### Returns

`Promise<string | undefined>` — A rendered usage or undefined. if you will use [`CliOptions.usageSilent`](/api/default/interfaces/CliOptions.md#property-usagesilent) option, it will return rendered usage string.

---

---
url: /api/default/functions/hasPriorityValidationError.md
---
# Function: hasPriorityValidationError()

Check whether validation errors should be handled before version, help, or command execution.

## Signature

```ts
export function hasPriorityValidationError(error: AggregateError | undefined): boolean
```

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `error` | `AggregateError \| undefined` | An aggregate validation error |

## Returns

`boolean` — `true` if the validation error must be handled with priority

---

---
url: /api/default/functions/isArgsValidationError.md
---
# Function: isArgsValidationError()

Check whether an error is an [ArgsValidationError](/api/default/classes/ArgsValidationError.md).

Prefer this over the `args-tokens` guard of the same name. Both recognize errors from another
bundled copy through the `Symbol.for('args-tokens.ArgsValidationError')` brand that
`args-tokens` 0.29.0 or later sets, including subclasses such as `ArgResolveError` that
override `name` with the argument name. This guard additionally:

* recognizes direct `ArgsValidationError` instances from copies bundling `args-tokens`
  older than 0.29.0, which do not set the brand
* checks that `code` and `values` of an error from another copy have the expected types

The guard narrows only to [ArgsValidationError](/api/default/classes/ArgsValidationError.md): across copies,
`instanceof ArgResolveError` still fails, so do not rely on `type` or `schema` for such errors.

## Signature

```ts
export function isArgsValidationError(error: unknown): error is ArgsValidationError
```

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `error` | `unknown` | An unknown error |

## Returns

`error` `is` [`ArgsValidationError`](/api/default/classes/ArgsValidationError.md) — `true` if the error is an [ArgsValidationError](/api/default/classes/ArgsValidationError.md)

---

---
url: /api/default/functions/isCommandNotFoundError.md
---
# Function: isCommandNotFoundError()

Check whether an error is a [CommandNotFoundError](/api/default/classes/CommandNotFoundError.md).

`instanceof` alone is not enough: `@gunshi/plugin` is bundled with its own copy of this
class (`noExternal: ['gunshi/plugin']`), so an error thrown by `gunshi` is never an instance
of the class a plugin imports. Errors from another copy are recognized through the
`Symbol.for('gunshi.CommandNotFoundError')` brand, which does not depend on `error.name`.

## Signature

```ts
export function isCommandNotFoundError(error: unknown): error is CommandNotFoundError
```

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `error` | `unknown` | An unknown error |

## Returns

`error` `is` [`CommandNotFoundError`](/api/default/classes/CommandNotFoundError.md) — `true` if the error is a [CommandNotFoundError](/api/default/classes/CommandNotFoundError.md)

---

---
url: /api/default/functions/isCommandResolutionError.md
---
# Function: isCommandResolutionError()

Check whether an error is a [CommandResolutionError](/api/default/classes/CommandResolutionError.md).

## Signature

```ts
export function isCommandResolutionError(error: unknown): error is CommandResolutionError
```

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `error` | `unknown` | An unknown error |

## Returns

`error` `is` [`CommandResolutionError`](/api/default/classes/CommandResolutionError.md) — `true` when the error has the command-resolution brand and shape

---

---
url: /api/default/functions/parseArgs.md
---
# Function: parseArgs()

Parse command line arguments.

## Signature

```ts
declare function parseArgs(args: string[], options?: ParserOptions): ArgToken[]
```

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `args` | `string[]` | command line arguments |
| `options` | `ParserOptions` | parse options, about details see ParserOptions *(optional)* |

## Returns

[`ArgToken`](/api/default/interfaces/ArgToken.md)\[] — Argument tokens.

## Examples

```js
import { parseArgs } from 'args-tokens' // for Node.js and Bun
// import { parseArgs } from 'jsr:@kazupon/args-tokens' // for Deno

const tokens = parseArgs(['--foo', 'bar', '-x', '--bar=baz'])
// do something with using tokens
// ...
console.log('tokens:', tokens)
```

---

---
url: /api/default/functions/plugin.md
---
# Function: plugin()

Define a plugin

## Since

v0.27.0

## Call Signature

```ts
export function plugin<
  Context extends ExtendContext = DefaultGunshiParams['extensions'], // for plugin dependency extensions
  Id extends string = string, // for plugin id
  Deps extends ReadonlyArray<PluginDependency | string> = [], // for plugin dependencies
  Extension extends {} = {}, // for plugin extension type
  ResolvedDepExtensions extends GunshiParams = DependencyParams<Deps, Context>,
  PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<
    Extension,
    ResolvedDepExtensions
  >,
  MergedExtensions extends GunshiParams = MergedPluginParams<
    Id,
    Deps,
    Context,
    Awaited<ReturnType<PluginExt>>
  >
>(options: {
  id: Id
  name?: string
  dependencies?: Deps
  setup?: (
    ctx: Readonly<
      PluginContext<MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>
    >
  ) => Awaitable<void>
  extension: PluginExt
  onExtension?: OnPluginExtension<MergedExtensions>
}): PluginWithExtension<Awaited<ReturnType<PluginExt>>>
```

Define a plugin with extension compatibility and typed dependency extensions

### Since

v0.27.0

### Type Parameters

| Name | Description |
| --- | --- |
| `Context` *extends* [`ExtendContext`](/api/default/type-aliases/ExtendContext.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)\['extensions'] | A type extending [`ExtendContext`](/api/default/type-aliases/ExtendContext.md) to specify the shape of plugin dependency extensions. |
| `Id` *extends* `string` = `string` | A string type to specify the plugin ID. |
| `Deps` *extends* `ReadonlyArray`<[`PluginDependency`](/api/default/interfaces/PluginDependency.md) | `string`> = `[]` | A readonly array of [`PluginDependency`](/api/default/interfaces/PluginDependency.md) or string to specify the plugin dependencies. |
| `Extension` *extends* `{}` = `{}` | A type to specify the shape of the plugin extension object. |
| `ResolvedDepExtensions` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = `DependencyParams<Deps, Context>` | - |
| `PluginExt` *extends* [`PluginExtension`](/api/default/type-aliases/PluginExtension.md)<`Extension`, [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)> = [`PluginExtension`](/api/default/type-aliases/PluginExtension.md)<`Extension`, `ResolvedDepExtensions`> | - |
| `MergedExtensions` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = `MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>` | - |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `options` | { `id`: `Id`; `name`?: `string`; `dependencies`?: `Deps`; `setup`?: (`ctx`: `Readonly`<[`PluginContext`](/api/default/interfaces/PluginContext.md)<`MergedPluginParams`<`Id`, `Deps`, `Context`, `Awaited`<`ReturnType`<`PluginExt`>>>>>) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`>; `extension`: `PluginExt`; `onExtension`?: [`OnPluginExtension`](/api/default/type-aliases/OnPluginExtension.md)<`MergedExtensions`> } | [`plugin options`](/api/default/interfaces/PluginOptions.md) |
| `options.id` | `Id` |  |
| `options.name?` | `string` | *optional* |
| `options.dependencies?` | `Deps` | *optional* |
| `options.setup?` | (`ctx`: `Readonly`<[`PluginContext`](/api/default/interfaces/PluginContext.md)<`MergedPluginParams`<`Id`, `Deps`, `Context`, `Awaited`<`ReturnType`<`PluginExt`>>>>>) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`> | *optional* |
| `options.extension` | `PluginExt` |  |
| `options.onExtension?` | [`OnPluginExtension`](/api/default/type-aliases/OnPluginExtension.md)<`MergedExtensions`> | *optional* |

### Returns

[`PluginWithExtension`](/api/default/interfaces/PluginWithExtension.md)<`Awaited`<`ReturnType`<`PluginExt`>>> — A defined plugin with extension

## Call Signature

```ts
export function plugin<
  Context extends ExtendContext = DefaultGunshiParams['extensions'], // for plugin dependency extensions
  Id extends string = string, // for plugin id
  Deps extends ReadonlyArray<PluginDependency | string> = [], // for plugin dependencies
  Extension extends Record<string, unknown> = {}, // for plugin extension type
  ResolvedDepExtensions extends GunshiParams = DependencyParams<Deps, Context>,
  PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<
    Extension,
    ResolvedDepExtensions
  >,
  MergedExtensions extends GunshiParams = MergedPluginParams<
    Id,
    Deps,
    Context,
    Awaited<ReturnType<PluginExt>>
  >
>(options: {
  id: Id
  name?: string
  dependencies?: Deps
  setup?: (
    ctx: Readonly<
      PluginContext<MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>
    >
  ) => Awaitable<void>
  onExtension?: OnPluginExtension<MergedExtensions>
}): PluginWithoutExtension<DefaultGunshiParams['extensions']>
```

Define a plugin without extension and typed dependency extensions

### Since

v0.27.0

### Type Parameters

| Name | Description |
| --- | --- |
| `Context` *extends* [`ExtendContext`](/api/default/type-aliases/ExtendContext.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)\['extensions'] | A type extending [`ExtendContext`](/api/default/type-aliases/ExtendContext.md) to specify the shape of plugin dependency extensions. |
| `Id` *extends* `string` = `string` | A string type to specify the plugin ID. |
| `Deps` *extends* `ReadonlyArray`<[`PluginDependency`](/api/default/interfaces/PluginDependency.md) | `string`> = `[]` | A readonly array of [`PluginDependency`](/api/default/interfaces/PluginDependency.md) or string to specify the plugin dependencies. |
| `Extension` *extends* `Record<string, unknown>` = `{}` | A type to specify the shape of the plugin extension object. |
| `ResolvedDepExtensions` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = `DependencyParams<Deps, Context>` | - |
| `PluginExt` *extends* [`PluginExtension`](/api/default/type-aliases/PluginExtension.md)<`Extension`, [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)> = [`PluginExtension`](/api/default/type-aliases/PluginExtension.md)<`Extension`, `ResolvedDepExtensions`> | - |
| `MergedExtensions` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = `MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>` | - |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `options` | { `id`: `Id`; `name`?: `string`; `dependencies`?: `Deps`; `setup`?: (`ctx`: `Readonly`<[`PluginContext`](/api/default/interfaces/PluginContext.md)<`MergedPluginParams`<`Id`, `Deps`, `Context`, `Awaited`<`ReturnType`<`PluginExt`>>>>>) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`>; `onExtension`?: [`OnPluginExtension`](/api/default/type-aliases/OnPluginExtension.md)<`MergedExtensions`> } | [`plugin options`](/api/default/interfaces/PluginOptions.md) without extension |
| `options.id` | `Id` |  |
| `options.name?` | `string` | *optional* |
| `options.dependencies?` | `Deps` | *optional* |
| `options.setup?` | (`ctx`: `Readonly`<[`PluginContext`](/api/default/interfaces/PluginContext.md)<`MergedPluginParams`<`Id`, `Deps`, `Context`, `Awaited`<`ReturnType`<`PluginExt`>>>>>) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`> | *optional* |
| `options.onExtension?` | [`OnPluginExtension`](/api/default/type-aliases/OnPluginExtension.md)<`MergedExtensions`> | *optional* |

### Returns

[`PluginWithoutExtension`](/api/default/interfaces/PluginWithoutExtension.md)<[`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)\['extensions']> — A defined plugin without extension

---

---
url: /api/default/functions/resolveArgs.md
---
# Function: resolveArgs()

Resolve command line arguments.

## Signature

```ts
export declare function resolveArgs<A extends Args>(args: A, tokens: ArgToken[], { shortGrouping, skipPositional, toKebab }?: ResolveArgs): {
  values: ArgValues<A>;
  positionals: string[];
  rest: string[];
  error: AggregateError | undefined;
  explicit: ArgExplicitlyProvided<A>;
}
```

## Type Parameters

| Name | Description |
| --- | --- |
| `A` *extends* [`Args`](/api/default/interfaces/Args.md) | [Arguments](/api/default/interfaces/Args.md), which is an object that defines the command line arguments. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `args` | `A` | An arguments that contains [arguments schema](/api/default/interfaces/ArgSchema.md). |
| `tokens` | [`ArgToken`](/api/default/interfaces/ArgToken.md)\[] | An array of [tokens](/api/default/interfaces/ArgToken.md). |
| `resolveArgs` | `ResolveArgs` | An arguments that contains resolve arguments. *(optional)* |

## Returns

`object` — An object that contains the values of the arguments, positional arguments, rest arguments, validation errors, and explicit provision status.

### error

```ts
error: AggregateError | undefined;
```

### explicit

```ts
explicit: ArgExplicitlyProvided<A>;
```

### positionals

```ts
positionals: string[];
```

### rest

```ts
rest: string[];
```

### values

```ts
values: ArgValues<A>;
```

## Examples

```typescript
// passed tokens: --port 3000

const { values, explicit } = resolveArgs({
  port: {
    type: 'number',
    default: 8080
  },
  host: {
    type: 'string',
    default: 'localhost'
  }
}, parsedTokens)

values.port // 3000
values.host // 'localhost'

explicit.port // true (explicitly provided)
explicit.host // false (not provided, fallback to default)
```

---

---
url: /api/default/classes/ArgsValidationError.md
---
# Class: ArgsValidationError

An error that contains structured metadata for argument validation failures.

The `message` remains the English fallback message. Renderers can use `code`
and `values` to localize the error, falling back to `message` when localization
is unavailable.

Each instance carries a non-enumerable brand keyed by
`Symbol.for('args-tokens.ArgsValidationError')`, which [isArgsValidationError](/api/default/functions/isArgsValidationError.md)
uses to recognize instances created by another bundled copy of `args-tokens`.

## Extends

* `Error`

## Signature

```ts
export declare class ArgsValidationError extends Error
```

## Constructors

### Constructor

```ts
new ArgsValidationError(message: string, options?: {
    code?: ArgsValidationErrorCode;
    values?: Record<string, unknown>;
    cause?: unknown;
  }): ArgsValidationError;
```

Create an `ArgsValidationError` instance.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `message` | `string` | fallback error message |
| `options` | { `code`?: [`ArgsValidationErrorCode`](/api/default/type-aliases/ArgsValidationErrorCode.md); `values`?: `Record`<`string`, `unknown`>; `cause`?: `unknown` } | structured validation metadata *(optional)* |
| `options.code?` | [`ArgsValidationErrorCode`](/api/default/type-aliases/ArgsValidationErrorCode.md) | *optional* |
| `options.values?` | `Record<string, unknown>` | *optional* |
| `options.cause?` | `unknown` | *optional* |

#### Returns

[`ArgsValidationError`](/api/default/classes/ArgsValidationError.md)

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `code` *(optional, readonly)* | [`ArgsValidationErrorCode`](/api/default/type-aliases/ArgsValidationErrorCode.md) | `undefined` | Machine-readable error code for this validation failure. This code can also be used as an i18n resource key. |
| `values` *(readonly)* | `Record<string, unknown>` | Interpolation values for `code`. |

---

---
url: /api/default/classes/CommandNotFoundError.md
---
# Class: CommandNotFoundError

Error raised when a command cannot be resolved.

Each instance carries a non-enumerable brand keyed by
`Symbol.for('gunshi.CommandNotFoundError')`, so that [isCommandNotFoundError](/api/default/functions/isCommandNotFoundError.md)
recognizes it even when it was created by another bundled copy of gunshi.

## Extends

* `Error`

## Signature

```ts
export class CommandNotFoundError extends Error
```

## Constructors

### Constructor

```ts
new CommandNotFoundError(message: string, options: CommandNotFoundErrorOptions): CommandNotFoundError;
```

Create a command-not-found error.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `message` | `string` | Fallback error message |
| `options` | [`CommandNotFoundErrorOptions`](/api/default/type-aliases/CommandNotFoundErrorOptions.md) | Command-not-found metadata |

#### Returns

[`CommandNotFoundError`](/api/default/classes/CommandNotFoundError.md)

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `candidates` *(readonly)* | `readonly string[]` |  |
| `code` *(optional, readonly)* | [`CommandNotFoundErrorCode`](/api/default/type-aliases/CommandNotFoundErrorCode.md) |  |
| `commandName` *(readonly)* | `string` |  |
| `commandPath` *(readonly)* | `readonly string[]` |  |
| `values` *(readonly)* | `Record<string, unknown>` |  |

---

---
url: /api/default/classes/CommandResolutionError.md
---
# Class: CommandResolutionError

Error raised when command routing cannot produce one consistent command.

The own registry brand is the cross-bundle contract. Unlike the legacy command-not-found
guard, the new guard deliberately has no name-based fallback because this error type is new and
must not classify arbitrary errors from older versions.

## Extends

* `Error`

## Signature

```ts
export class CommandResolutionError extends Error
```

## Constructors

### Constructor

```ts
new CommandResolutionError(message: string, options: CommandResolutionErrorOptions = {}): CommandResolutionError;
```

Create a command resolution error with structured routing metadata.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `message` | `string` | Human-readable fallback message |
| `options` | [`CommandResolutionErrorOptions`](/api/default/type-aliases/CommandResolutionErrorOptions.md) | Error code and command-routing metadata *(optional, default: {})* |

#### Returns

[`CommandResolutionError`](/api/default/classes/CommandResolutionError.md)

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `candidatePaths` *(readonly)* | `readonly (readonly string[])[]` |  |
| `code` *(optional, readonly)* | [`CommandResolutionErrorCode`](/api/default/type-aliases/CommandResolutionErrorCode.md) |  |
| `commandPath` *(readonly)* | `readonly string[]` |  |
| `values` *(readonly)* | `Record<string, unknown>` |  |

---

---
url: /api/default/classes/DefaultTranslation.md
---
# Class: DefaultTranslation

Default implementation of `TranslationAdapter`.

## Implements

* `TranslationAdapter`

## Signature

```ts
declare class DefaultTranslation implements TranslationAdapter
```

## Constructors

### Constructor

```ts
new DefaultTranslation(options: TranslationAdapterFactoryOptions): DefaultTranslation;
```

Creates a new instance of DefaultTranslation.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `options` | `TranslationAdapterFactoryOptions` | Options for the translation adapter, see `TranslationAdapterFactoryOptions` |

#### Returns

[`DefaultTranslation`](/api/default/classes/DefaultTranslation.md)

## Methods

### getMessage()

```ts
getMessage(locale: string, key: string): string | undefined;
```

Get a message of locale.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `locale` | `string` | A locale of message (BCP 47 language tag) |
| `key` | `string` | A key of message resource |

#### Returns

`string | undefined` — A message of locale. If message not found, return `undefined`.

***

### getResource()

```ts
getResource(locale: string): Record<string, string> | undefined;
```

Get a resource of locale.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `locale` | `string` | A locale of resource (BCP 47 language tag) |

#### Returns

`Record<string, string> | undefined` — A resource of locale. If resource not found, return `undefined`.

***

### setResource()

```ts
setResource(locale: string, resource: Record<string, string>): void;
```

Set a resource of locale.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `locale` | `string` | A locale of resource (BCP 47 language tag) |
| `resource` | `Record<string, string>` | A resource of locale |

#### Returns

`void`

***

### translate()

```ts
translate(locale: string, key: string, values?: Record<string, unknown>): string | undefined;
```

Translate a message.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `locale` | `string` | A locale of message (BCP 47 language tag) |
| `key` | `string` | A key of message resource |
| `values` | `Record<string, unknown>` | A values to interpolate in the message *(optional)* |

#### Returns

`string | undefined` — A translated message, if message is not translated, return `undefined`.

---

---
url: /api/default/interfaces/Args.md
---
# Interface: Args

An object that contains [argument schema](/api/default/interfaces/ArgSchema.md).

This type is used to define the structure and validation rules for command line arguments.

## Signature

```ts
export interface Args
```

## Indexable

```ts
[option: string]: ArgSchema
```

---

---
url: /api/default/interfaces/ArgSchema.md
---
# Interface: ArgSchema

An argument schema definition for command-line argument parsing.

This schema is similar to the schema of Node.js `util.parseArgs` but with extended features:

* Additional `required`, `description`, and `hidden` properties
* Extended `type` support: 'string', 'boolean', 'number', 'enum', 'positional', 'custom'
* Simplified `default` property (single type, not union types)

## Signature

```ts
export interface ArgSchema
```

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `choices` *(optional)* | `string[] \| readonly string[]` | Array of allowed string values for enum-type arguments. Required when `type: 'enum'`, unless the argument has a `parse` function: if `choices` is missing or not an array, [resolveArgs](/api/default/functions/resolveArgs.md) and `parse()` throw a `TypeError`, whether or not the argument is given. With a `parse` function and no `choices`, the value is passed to the function as for a `string` argument with a `parse` function. The argument value must be one of these choices, otherwise the error is an `ArgResolveError` with type 'type' and the code `err:arg:invalid-choice` (ArgsValidationErrorKeys.invalidChoice). The value is checked before `parse` is called, so a `parse` function receives only one of these choices and can change it, for example to upper case. Supports both mutable arrays and readonly arrays for type safety. |
| `conflicts` *(optional)* | `string \| string[]` | Names of other options that conflict with this option. When this option is used together with any of the conflicting options, the error is an `ArgResolveError` with type 'conflict' and the code `err:arg:conflict` (ArgsValidationErrorKeys.conflict). Its `values` has the `displayName` and `name` of the argument whose `conflicts` names the other one, and the `conflictDisplayName` and `conflictName` of the other one. `displayName` and `conflictDisplayName` show an option as it was written, such as `'-p'`, and `name` and `conflictName` are the schema keys. When both name each other, `name` is the one that comes first in the schema. A positional argument can be on either side, such as `[file]` and `--stdin`. It conflicts when it is given, and it is shown by its name, such as `'file'` (in kebab-case with `toKebab`), as in its other errors. The message starts with the kind of the argument given as `name`: `Positional argument 'file' conflicts with '--stdin'` or `Optional argument '--stdin' conflicts with 'file'`. Conflicts only need to be defined on one side - if option A defines a conflict with option B, the conflict is automatically detected when both are used, regardless of whether B also defines a conflict with A. Supports both single option name or array of option names. Option names must match the property keys in the schema object exactly (no automatic conversion between camelCase and kebab-case). |
| `default` *(optional)* | `string \| boolean \| number` | Default value used when the argument is not provided. An option that is given without a value, or with a value that is rejected, also gets its default, along with the error. The type must match the argument's `type` property: - `string` type: string default - `boolean` type: boolean default - `number` type: number default - `enum` type: one of the `choices` values, or a value that a `parse` of your own returns - `positional`/`custom` type: string, boolean, or number default The default is used as is and never goes through `parse`, including when an option is given without a value. An explicit empty value, such as `--name=` or `-n ''`, is a value, not a missing one: a `string` option without `parse` gets `''` instead of the default, unless it is `required`. What `parse` returns is a value too, even `undefined` or `null`, and the default does not replace it. The value of a `multiple` argument is an array, so its default becomes the only element of the array: `default: 'latest'` gives `['latest']`. The default of an `enum` option with `choices` is checked when it would be used, that is, when no value from the command line is used: one that is not one of the choices is reported as an `ArgResolveError` with type 'type' and the code `err:arg:invalid-default` (ArgsValidationErrorKeys.invalidDefault), and is not used. With a `parse` function of your own, or a `map()` transform, the default is a value that the function returns, which need not be one of the choices, and it is not checked. `choice()` returns the value as is, so its default is checked. For positional arguments, `multiple` ones included, the default is used when no value is left for the argument: when the positional values run out, or when the remaining ones are preserved for later required positional arguments. With `required: true`, the default is not used, and the argument is reported as required instead. |
| `description` *(optional)* | `string` | Human-readable description of the argument's purpose. Used for help text generation and documentation. Should be concise but descriptive enough to understand the argument's role. |
| `hidden` *(optional)* | `boolean` | Hide the argument from generated help or usage output. This is metadata for renderers. It does not affect parsing, validation, required checks, defaults, conflicts, or resolved values. |
| `metavar` *(optional)* | `string` | Display name hint for help text generation. Provides a meaningful type hint for the argument value in help output. Particularly useful for `type: 'custom'` arguments where the type name would otherwise be unhelpful. For a `custom` option that is given without a value, it is also the `expected` in the `values` of the `err:arg:missing-value` error (ArgsValidationErrorKeys.missingValue), which is `'custom'` without it. |
| `multiple` *(optional)* | `true` | Allows the argument to accept multiple values. When `true`, the resolved value becomes an array. When the argument is not given and has no `default`, its value is `undefined`, not an empty array. For options: can be specified multiple times (--tags foo --tags bar) For positional: collects remaining positional arguments after preserving values for later required positional arguments. Note: Only `true` is allowed (not `false`) to make intent explicit. |
| `negatable` *(optional)* | `boolean` | Enables negation for boolean arguments using `--no-` prefix. When `true`, allows users to explicitly set the boolean to `false` using `--no-option-name`. When `false` or omitted, only positive form is available. Only applicable to `type: 'boolean'` arguments. The negated name is always `no-` followed by the full option name. An option named `no-cache` is negated by `--no-no-cache`, and `--no-cache` sets it to `true`. The negated form does not take a value. `--no-flag=<value>` is reported as `err:arg:unexpected-value` (ArgsValidationErrorKeys.unexpectedValue). |
| `parse` *(optional)* | `(value: string) => any` | Custom parsing function, used in place of the parsing of the argument's `type`. Required when `type: 'custom'`: if it is missing or not a function, [resolveArgs](/api/default/functions/resolveArgs.md) and `parse()` throw a `TypeError`, whether or not the argument is given. The function receives the raw string value and must return the parsed result. It should throw an Error (or subclass) if parsing fails. The function's return type becomes the resolved argument type. `parse` is called synchronously, and what it returns becomes the value, even `undefined` or `null`, so throw to reject a value. An `async` function returns a promise, and the promise becomes the value as is: it is not awaited, and its rejection is not reported as an error. Await the value, or each of its elements with `multiple` (for example with `Promise.all()`), and handle the rejection yourself: a rejection that nothing handles is an unhandled rejection, which ends a Node.js process by default. A `boolean` option calls `parse` with `'true'`, or `'false'` for the negated form. Other options call it only with a value from the command line: when the option is given without a value, `parse` is not called and the missing value is reported as `err:arg:missing-value` (ArgsValidationErrorKeys.missingValue). When that error may suggest the argument after the option as its value, such as `--port=-5` for `--port -5`, a `parse` function of your own is not called to check it either: only the `parse` functions of `string()`, `number()`, `integer()`, `float()` and `choice()`, which have no side effects, are called for that. An explicit empty value, such as `--name=` or `-n=`, is passed as `''` unless `required: true` is set. An `enum` option with `choices` calls it only with one of them. Any other value, an explicit empty one included, is reported as `err:arg:invalid-choice` (ArgsValidationErrorKeys.invalidChoice), except that a required option reports an explicit empty value as required. |
| `required` *(optional)* | `boolean` | Marks the argument as required. When `true`, the argument must be provided by the user. If it is missing, the error is an `ArgResolveError` with type 'required' and the code `err:arg:required-option` (ArgsValidationErrorKeys.requiredOption), or `err:arg:required-positional` (ArgsValidationErrorKeys.requiredPositional) for a positional argument. Its `values` has the `displayName` as in the message, such as `'--name'` for an option (`'--name' or '-n'` with the short name `n`) and `'file'` for a positional argument, and the `name`, which is the schema key. An option that is given without a value is reported as `err:arg:missing-value` (ArgsValidationErrorKeys.missingValue) instead, because the option itself was given. An explicit empty value, such as `--name=` or `-n ''`, is still reported as required, but the option counts as given: it is `true` in `explicit` and takes part in conflicts, as any other given option does. For single-value positional arguments, omitting `required` keeps the argument required for compatibility, unless it has a `default`, which makes it optional. A `multiple` positional argument is optional unless `required: true` is set. Set `required: false` to make a positional argument explicitly optional. Optional positional arguments leave enough input values for later required positional arguments before consuming a value. In the type of the values, such as [ArgValues](/api/default/type-aliases/ArgValues.md), a single-value positional argument whose `required` may be `false`, such as one of type `boolean`, is optional, as it may be missing, unless it has a `default`. An optional `required` of type `boolean`, as declared here, says nothing, and keeps it required. TypeScript widens a `required: true` to `boolean` in a schema written apart from the call, such as `{ type: 'positional' as const, required: true }`, which types the argument as optional: write such a schema `as const`. |
| `short` *(optional)* | `string` | Single character alias for the long option name. As example, allows users to use `-x` instead of `--extended-option`. Only valid for non-positional argument types. |
| `toKebab` *(optional)* | `true` | Converts the argument name from camelCase to kebab-case for CLI usage. When `true`, a property like `maxCount` becomes available as `--max-count`. This allows [CAC](https://github.com/cacjs/cac) user-friendly property names while maintaining CLI conventions. The `toKebab` option of [resolveArgs](/api/default/functions/resolveArgs.md) and `parse()` applies it to all arguments, as in `resolveArgs(args, tokens, { toKebab: true })`. Note: Only `true` is allowed (not `false`) to make intent explicit. |
| `type` | `"string" \| "boolean" \| "number" \| "enum" \| "positional" \| "custom"` | Type of the argument value. - `'string'`: Text value - `'boolean'`: `true`/`false` flag (can be negatable with `--no-` prefix). `--flag=true` and `--flag=false` set the value explicitly; any other value after `=` is a type error - `'number'`: Numeric value (parsed as integer or float) - `'enum'`: One of predefined string values (requires `choices` property, unless the argument has a `parse` function) - `'positional'`: Non-option argument by position - `'custom'`: Custom parsing with user-defined `parse` function Any other `type`, or no `type`, is a mistake that only untyped code can make: if the argument has no `parse` function, [resolveArgs](/api/default/functions/resolveArgs.md) and `parse()` throw an `Error`, whether or not the argument is given. |

### parse Parameters

| Name | Type | Description |
| --- | --- | --- |
| `value` | `string` | Raw string value from command line |

### parse Returns

`any` — Parsed value of any type

### parse Throws

* `Error` — Error or subclass when value is invalid

## Examples

Basic string argument:

```ts
const schema: ArgSchema = {
  type: 'string',
  description: 'Server hostname',
  default: 'localhost'
}
```

Required number argument with alias:

```ts
const schema: ArgSchema = {
  type: 'number',
  short: 'p',
  description: 'Port number to listen on',
  required: true
}
```

Enum argument with choices:

```ts
const schema: ArgSchema = {
  type: 'enum',
  choices: ['info', 'warn', 'error'],
  description: 'Logging level',
  default: 'info'
}
```

---

---
url: /api/default/interfaces/ArgToken.md
---
# Interface: ArgToken

Argument token.

## Signature

```ts
interface ArgToken
```

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `index` | `number` | Argument token index, e.g `--foo bar` => `--foo` index is 0, `bar` index is 1. |
| `inlineValue` *(optional)* | `boolean \| undefined` | Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`, `-x-1` => `false`, since no `=` is written. Unlike Node.js `parseArgs`, `false` does not mean that the value is the next argument: the value token of `-x-1` has the `index` of that argument. |
| `kind` | `ArgTokenKind` | Argument token kind. |
| `name` *(optional)* | `string` | Option name, e.g. `--foo` => `foo`, `-x` => `x`. |
| `rawName` *(optional)* | `string` | Raw option name, e.g. `--foo` => `--foo`, `-x` => `-x`. |
| `value` *(optional)* | `string \| undefined` | Option value, e.g. `--foo=bar` => `bar`. The value of a short option, such as `bar` of `-x=bar`, `-1` of `-x=-1` or `-x-1`, and `''` of `-x=`, is in a token of its own after the option, which has no `name` and `rawName`. If the `allowCompatible` option is `true`, short option value will be same as Node.js `parseArgs` behavior. |

---

---
url: /api/default/interfaces/CliOptions.md
---
# Interface: CliOptions\<G>

CLI options of [`cli`](/api/default/functions/cli.md) function.

## Signature

```ts
export interface CliOptions<G extends GunshiParamsConstraint = DefaultGunshiParams>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) 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`](/api/default/interfaces/CommandContext.md)<`G`>>, `result`: `string` | `undefined`) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`> | Hook that runs after successful command execution **Since** v0.27.0 |
| `onBeforeCommand` *(optional)* | (`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`> | Hook that runs before any command execution **Since** v0.27.0 |
| `onErrorCommand` *(optional)* | (`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>, `error`: `Error`) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`> | Hook that runs when a command throws an error **Since** v0.27.0 |
| `plugins` *(optional)* | [`Plugin`](/api/default/type-aliases/Plugin.md)\[] | User plugins. **Since** v0.27.0 |
| `renderHeader` *(optional)* | ((`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>) => `Promise`<`string`>) | `null` | Render function the header section in the command usage. |
| `renderUsage` *(optional)* | ((`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>) => `Promise`<`string`>) | `null` | Render function the command usage. |
| `renderValidationErrors` *(optional)* | ((`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>, `error`: `AggregateError`) => `Promise`<`string`>) | `null` | Render function the validation errors. |
| `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. **Default:** `false` |
| `subCommands` *(optional)* | `Record`<`string`, [`SubCommandable`](/api/default/interfaces/SubCommandable.md)> | `Map`<`string`, [`SubCommandable`](/api/default/interfaces/SubCommandable.md)> | 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`](/api/default/interfaces/CommandContext.md#property-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`. **Default:** `false` |
| `version` *(optional)* | `string` | Command program version. |

### onAfterCommand Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>> | The command context |
| `result` | `string \| undefined` | The command execution result |

### onAfterCommand Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`>

### onBeforeCommand Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>> | The command context |

### onBeforeCommand Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`>

### onErrorCommand Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>> | The command context |
| `error` | `Error` | The error thrown during execution |

### onErrorCommand Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`>

---

---
url: /api/default/interfaces/Command.md
---
# Interface: Command\<G>

Command interface.

## Signature

```ts
export interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | The Gunshi parameters constraint |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `args` *(optional)* | `ExtractArgs<G>` | Command arguments. Each argument can include a description property to describe the argument in usage. |
| `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`](/api/default/type-aliases/CommandExamplesFetcher.md)<`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. |
| `rendering` *(optional)* | [`RenderingOptions`](/api/default/interfaces/RenderingOptions.md)<`G`> | Rendering control options **Since** v0.27.0 |
| `run` *(optional)* | [`CommandRunner`](/api/default/type-aliases/CommandRunner.md)<`G`> | Command runner. it's the command to be executed |
| `subCommands` *(optional)* | `Record`<`string`, [`SubCommandable`](/api/default/interfaces/SubCommandable.md)> | `Map`<`string`, [`SubCommandable`](/api/default/interfaces/SubCommandable.md)> | 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 or lazy command. **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`](#property-args) names will be converted to kebab-case. |

---

---
url: /api/default/interfaces/CommandContext.md
---
# Interface: CommandContext\<G>

Command context.

Command context is the context of the command execution.

## Signature

```ts
export interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command context. |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `_` | `string[]` | Original command line arguments. This argument is passed from `cli` function. |
| `args` | `ExtractArgs<G>` | Command arguments, that is the arguments of the command that is executed. The command arguments is same [`Command.args`](/api/default/interfaces/Command.md#property-args). |
| `callMode` | [`CommandCallMode`](/api/default/type-aliases/CommandCallMode.md) | Command call mode. The command call mode is `entry` when the command is executed as an entry command, and `subCommand` when the command is executed as a sub-command. |
| `commandPath` | `string[]` | The path of nested sub-commands that were resolved to reach the current command. For example, if the user runs `git remote add`, `commandPath` would be `['remote', 'add']`. For the entry command, this is an empty array. **Since** v0.28.0 |
| `description` | `string \| undefined` | Command description, that is the description of the command that is executed. The command description is same [`CommandEnvironment.description`](/api/default/interfaces/CommandEnvironment.md#property-description). |
| `env` | `Readonly`<[`CommandEnvironment`](/api/default/interfaces/CommandEnvironment.md)<`G`>> | Command environment, that is the environment of the command that is executed. The command environment is same [`CommandEnvironment`](/api/default/interfaces/CommandEnvironment.md). |
| `explicit` | `ExtractArgExplicitlyProvided<G>` | Whether arguments were explicitly provided by the user. - `true`: The argument was explicitly provided via command line - `false`: The argument was not explicitly provided. This means either: - The value comes from a default value defined in the argument schema - The value is `undefined` (no explicit input and no default value) |
| `extensions` | `keyof ExtractExtensions<G> extends never ? any : ExtractExtensions<G>` | Command context extensions. **Since** v0.27.0 |
| `log` | `(message?: any, ...optionalParams: any[]) => void` | Output a message. If [`CommandEnvironment.usageSilent`](/api/default/interfaces/CommandEnvironment.md#property-usagesilent) is true, the message is not output. |
| `name` | `string \| undefined` | Command name, that is the command that is executed. The command name is same [`CommandEnvironment.name`](/api/default/interfaces/CommandEnvironment.md#property-name). |
| `omitted` | `boolean` | Whether the currently executing command has been executed with the sub-command name omitted. |
| `positionals` | `string[]` | Command positionals arguments, that is the positionals of the command that is executed. Resolve positionals with `resolveArgs` from command arguments. |
| `rest` | `string[]` | Command rest arguments, that is the remaining argument not resolved by the optional command option delimiter `--`. |
| `toKebab` *(optional)* | `boolean` | Whether to convert the camel-case style argument name to kebab-case. This context value is set from [`Command.toKebab`](/api/default/interfaces/Command.md#property-tokebab) option. |
| `tokens` | [`ArgToken`](/api/default/interfaces/ArgToken.md)\[] | Argument tokens, that is parsed by `parseArgs` function. |
| `validationError` *(optional)* | `AggregateError` | Validation error from argument parsing. This will be set if argument validation fails during CLI execution. |
| `values` | [`ArgValues`](/api/default/type-aliases/ArgValues.md)<`ExtractArgs`<`G`>> | Command values, that is the values of the command that is executed. Resolve values with `resolveArgs` from command arguments and [`Command.args`](/api/default/interfaces/Command.md#property-args). |

### log Parameters

| Name | Type | Description |
| --- | --- | --- |
| `message` | `any` | an output message, see `console.log` *(optional)* |
| `optionalParams` | `any[]` | an optional parameters, see `console.log` |

### log Returns

`void`

---

---
url: /api/default/interfaces/CommandContextExtension.md
---
# Interface: CommandContextExtension\<E>

Command context extension

## Since

v0.27.0

## Signature

```ts
export interface CommandContextExtension<
  E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']
>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `E` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md)\['extensions'] = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)\['extensions'] | A type extending [`GunshiParams.extensions`](/api/default/interfaces/GunshiParams.md#property-extensions) to specify the shape of the extension. |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `factory` *(readonly)* | (`ctx`: [`CommandContextCore`](/api/default/type-aliases/CommandContextCore.md), `cmd`: [`Command`](/api/default/interfaces/Command.md)) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`E`> | Plugin extension factory |
| `key` *(readonly)* | `symbol` | Plugin identifier |
| `onFactory` *(optional, readonly)* | (`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)>, `cmd`: `Readonly`<[`Command`](/api/default/interfaces/Command.md)>) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`> | Plugin extension factory after hook |

### factory Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | [`CommandContextCore`](/api/default/type-aliases/CommandContextCore.md) |  |
| `cmd` | [`Command`](/api/default/interfaces/Command.md) |  |

### factory Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<`E`>

### onFactory Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)> |  |
| `cmd` | `Readonly`<[`Command`](/api/default/interfaces/Command.md)> |  |

### onFactory Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`>

---

---
url: /api/default/interfaces/CommandEnvironment.md
---
# Interface: CommandEnvironment\<G>

Command environment.

## Signature

```ts
export interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiParams>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command environments. |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `cwd` | `string \| undefined` | Current working directory. |
| `description` | `string \| undefined` | Command description. |
| `entryCommand` *(optional)* | [`Command`](/api/default/interfaces/Command.md)<`any`> | [`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<`any`> | The entry command of the CLI, marked with `entry: true`. It is available whether or not the CLI has sub-commands, while [`CommandEnvironment.subCommands`](#property-subcommands) includes the entry command only when the sub-commands are given with [`CliOptions.subCommands`](/api/default/interfaces/CliOptions.md#property-subcommands). It is not frozen, like the commands in [`CommandEnvironment.subCommands`](#property-subcommands). |
| `globalOptions` *(optional)* | `ReadonlyMap`<`string`, [`ArgSchema`](/api/default/interfaces/ArgSchema.md)> | The global options that are in effect for the command being executed. A plugin registers a global option with `addGlobalOption`, and gunshi merges it into the arguments of the command that runs. An argument that the command declares under the same name replaces it, and the option is then not in effect: the value under that name is the command's, and the plugin that registered it must not read it as its own. The schema is the one in effect, which may have given up its short name to an argument of the command that claims the same letter. |
| `leftMargin` | `number` | Left margin of the command output. **Default:** `2` |
| `middleMargin` | `number` | Middle margin of the command output. **Default:** `10` |
| `name` | `string \| undefined` | Command name. |
| `onAfterCommand` | ((`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>, `result`: `string` | `undefined`) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`>) | `undefined` | Hook that runs after successful command execution **Since** v0.27.0 |
| `onBeforeCommand` | ((`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`>) | `undefined` | Hook that runs before any command execution **Since** v0.27.0 |
| `onErrorCommand` | ((`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>, `error`: `Error`) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`>) | `undefined` | Hook that runs when a command throws an error **Since** v0.27.0 |
| `renderHeader` | ((`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>) => `Promise`<`string`>) | `null` | `undefined` | Render function the header section in the command usage. |
| `renderUsage` | ((`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>) => `Promise`<`string`>) | `null` | `undefined` | Render function the command usage. |
| `renderValidationErrors` | ((`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>, `error`: `AggregateError`) => `Promise`<`string`>) | `null` | `undefined` | Render function the validation errors. |
| `strict` | `boolean` | Whether to treat undefined options as argument validation errors. **Default:** `false` |
| `subCommands` | `Map`<`string`, [`Command`](/api/default/interfaces/Command.md)<`any`> | [`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<`any`>> | `undefined` | Sub commands. |
| `usageOptionType` | `boolean` | Whether to display the usage option type. **Default:** `false` |
| `usageOptionValue` | `boolean` | Whether to display the option value. **Default:** `true` |
| `usageSilent` | `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`](/api/default/interfaces/CommandContext.md#property-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`. **Default:** `false` |
| `version` | `string \| undefined` | Command version. |

---

---
url: /api/default/interfaces/GunshiParams.md
---
# Interface: GunshiParams\<P>

Gunshi unified parameter type.

This type combines both argument definitions and command context extensions.

## Since

v0.27.0

## Signature

```ts
export interface GunshiParams<
  P extends {
    args?: Args
    extensions?: ExtendContext
  } = {
    args: Args
    extensions: {}
  }
>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `P` *extends* { [`args`](/api/combinators/functions/args.md)?: [`Args`](/api/default/interfaces/Args.md) `extensions`?: [`ExtendContext`](/api/default/type-aliases/ExtendContext.md) } = { [`args`](/api/combinators/functions/args.md): [`Args`](/api/default/interfaces/Args.md) `extensions`: {} } | The type of parameters, which can include `args` and `extensions`. |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `args` | `P` `extends` { [`args`](/api/combinators/functions/args.md): `infer` `A` `extends` [`Args`](/api/default/interfaces/Args.md) } ? `A` : [`Args`](/api/default/interfaces/Args.md) | Command argument definitions. |
| `extensions` | `P` `extends` { `extensions`: `infer` `E` `extends` [`ExtendContext`](/api/default/type-aliases/ExtendContext.md) } ? `E` : {} | Command context extensions. |

---

---
url: /api/default/interfaces/PluginContext.md
---
# Interface: PluginContext\<G>

Gunshi plugin context interface.

## Since

v0.27.0

## Signature

```ts
export interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command parameters. |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `globalOptions` *(readonly)* | `Map`<`string`, [`ArgSchema`](/api/default/interfaces/ArgSchema.md)> | Get the global options |
| `subCommands` *(readonly)* | `ReadonlyMap`<`string`, [`Command`](/api/default/interfaces/Command.md)<`G`> | [`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<`G`>> | Get the registered sub commands |

## Methods

### addCommand()

```ts
addCommand(name: string, command: Command<G> | LazyCommand<G>): void;
```

Add a sub command.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | Command name |
| `command` | [`Command`](/api/default/interfaces/Command.md)<`G`> | [`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<`G`> | Command definition |

#### Returns

`void`

***

### addGlobalOption()

```ts
addGlobalOption(name: string, schema: ArgSchema): void;
```

Add a global option.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | An option name |
| `schema` | [`ArgSchema`](/api/default/interfaces/ArgSchema.md) | An [`ArgSchema`](/api/default/interfaces/ArgSchema.md) for the option |

#### Returns

`void`

***

### decorateCommand()

```ts
decorateCommand<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (
      baseRunner: (
        ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>
      ) => Awaitable<void | string>
    ) => (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Awaitable<void | string>): void;
```

Decorate the command execution.

Decorators are applied in reverse order (last registered is executed first).

#### Type Parameters

| Name | Description |
| --- | --- |
| `L` *extends* `Record<string, unknown>` = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)\['extensions'] | An extensions type to specify the shape of [`CommandContext`](/api/default/interfaces/CommandContext.md)'s extensions. |

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `decorator` | (`baseRunner`: (`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`MergeGunshiExtensions`<`G`, `L`>>>) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void` | `string`>) => (`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`MergeGunshiExtensions`<`G`, `L`>>>) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void` | `string`> | A decorator function that wraps the command runner |

#### Returns

`void`

***

### decorateHeaderRenderer()

```ts
decorateHeaderRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (
      baseRenderer: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>,
      ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>
    ) => Promise<string>): void;
```

Decorate the header renderer.

#### Type Parameters

| Name | Description |
| --- | --- |
| `L` *extends* `Record<string, unknown>` = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)\['extensions'] | An extensions type to specify the shape of [`CommandContext`](/api/default/interfaces/CommandContext.md)'s extensions. |

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `decorator` | (`baseRenderer`: (`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`MergeGunshiExtensions`<`G`, `L`>>>) => `Promise`<`string`>, `ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`MergeGunshiExtensions`<`G`, `L`>>>) => `Promise`<`string`> | A decorator function that wraps the base header renderer. |

#### Returns

`void`

***

### decorateUsageRenderer()

```ts
decorateUsageRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (
      baseRenderer: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>,
      ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>
    ) => Promise<string>): void;
```

Decorate the usage renderer.

#### Type Parameters

| Name | Description |
| --- | --- |
| `L` *extends* `Record<string, unknown>` = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)\['extensions'] | An extensions type to specify the shape of [`CommandContext`](/api/default/interfaces/CommandContext.md)'s extensions. |

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `decorator` | (`baseRenderer`: (`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`MergeGunshiExtensions`<`G`, `L`>>>) => `Promise`<`string`>, `ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`MergeGunshiExtensions`<`G`, `L`>>>) => `Promise`<`string`> | A decorator function that wraps the base usage renderer. |

#### Returns

`void`

***

### decorateValidationErrorsRenderer()

```ts
decorateValidationErrorsRenderer<
    L extends Record<string, unknown> = DefaultGunshiParams['extensions']
  >(decorator: (
      baseRenderer: (
        ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>,
        error: AggregateError
      ) => Promise<string>,
      ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>,
      error: AggregateError
    ) => Promise<string>): void;
```

Decorate the validation errors renderer.

#### Type Parameters

| Name | Description |
| --- | --- |
| `L` *extends* `Record<string, unknown>` = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)\['extensions'] | An extensions type to specify the shape of [`CommandContext`](/api/default/interfaces/CommandContext.md)'s extensions. |

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `decorator` | (`baseRenderer`: (`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`MergeGunshiExtensions`<`G`, `L`>>>, `error`: `AggregateError`) => `Promise`<`string`>, `ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`MergeGunshiExtensions`<`G`, `L`>>>, `error`: `AggregateError`) => `Promise`<`string`> | A decorator function that wraps the base validation errors renderer. |

#### Returns

`void`

***

### hasCommand()

```ts
hasCommand(name: string): boolean;
```

Check if a command exists.

#### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `name` | `string` | Command name |

#### Returns

`boolean` — True if the command exists, false otherwise

---

---
url: /api/default/interfaces/PluginDependency.md
---
# Interface: PluginDependency

Plugin dependency definition

## Since

v0.27.0

## Signature

```ts
export interface PluginDependency
```

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `id` | `string` | Dependency plugin id |
| `optional` *(optional)* | `boolean` | Optional dependency flag. If `true`, the plugin will not throw an error if the dependency is not found |

---

---
url: /api/default/interfaces/PluginOptions.md
---
# Interface: PluginOptions\<DepExt, Id, Deps, Ext, ResolvedDepExt, PluginExt, MergedExt>

Plugin definition options

## Since

v0.27.0

## Signature

```ts
export interface PluginOptions<
  DepExt extends ExtendContext = DefaultGunshiParams['extensions'], // for plugin dependency extensions
  Id extends string = string, // for plugin id
  Deps extends ReadonlyArray<PluginDependency | string> = (PluginDependency | string)[], // for plugin dependencies
  Ext extends Record<string, unknown> = {}, // for plugin extension type
  ResolvedDepExt extends GunshiParams = DependencyParams<Deps, DepExt>,
  PluginExt extends PluginExtension<Ext, ResolvedDepExt> = PluginExtension<Ext, ResolvedDepExt>,
  MergedExt extends GunshiParams = MergedPluginParams<
    Id,
    Deps,
    DepExt,
    Awaited<ReturnType<PluginExt>>
  >
>
```

## Type Parameters

| Name |
| --- |
| `DepExt` *extends* [`ExtendContext`](/api/default/type-aliases/ExtendContext.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)\['extensions'] |
| `Id` *extends* `string` = `string` |
| `Deps` *extends* `ReadonlyArray`<[`PluginDependency`](/api/default/interfaces/PluginDependency.md) | `string`> = ([`PluginDependency`](/api/default/interfaces/PluginDependency.md) | `string`)\[] |
| `Ext` *extends* `Record<string, unknown>` = `{}` |
| `ResolvedDepExt` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = `DependencyParams<Deps, DepExt>` |
| `PluginExt` *extends* [`PluginExtension`](/api/default/type-aliases/PluginExtension.md)<`Ext`, `ResolvedDepExt`> = [`PluginExtension`](/api/default/type-aliases/PluginExtension.md)<`Ext`, `ResolvedDepExt`> |
| `MergedExt` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = `MergedPluginParams<Id, Deps, DepExt, Awaited<ReturnType<PluginExt>>>` |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `dependencies` *(optional)* | `Deps` | Plugin dependencies |
| `extension` *(optional)* | `PluginExt` | Plugin extension |
| `id` | `Id` | Plugin unique identifier. Must be a non-empty string. [`plugin`](/api/default/functions/plugin.md) and the installer both reject an empty id. |
| `name` *(optional)* | `string` | Plugin name |
| `onExtension` *(optional)* | [`OnPluginExtension`](/api/default/type-aliases/OnPluginExtension.md)<`MergedExt`> | Callback for when the plugin is extended with `extension` option. |
| `setup` *(optional)* | [`PluginFunction`](/api/default/type-aliases/PluginFunction.md)<`MergedExt`> | Plugin setup function |

### onExtension Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>> |  |
| `cmd` | `Readonly`<[`Command`](/api/default/interfaces/Command.md)<`G`>> |  |

### onExtension Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`>

### setup Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `Readonly`<[`PluginContext`](/api/default/interfaces/PluginContext.md)<`G`>> |  |

### setup Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`>

---

---
url: /api/default/interfaces/PluginWithExtension.md
---
# Interface: PluginWithExtension\<E>

Plugin return type with extension, which includes the plugin ID, name, dependencies, and extension.

This type is used to define a plugin at `plugin` function.

## Extends

* [`Plugin`](/api/default/type-aliases/Plugin.md)<`E`>

## Signature

```ts
export interface PluginWithExtension<
  E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']
> extends Plugin<E>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `E` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md)\['extensions'] = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)\['extensions'] | A type extending [GunshiParams](/api/default/interfaces/GunshiParams.md) to specify the shape of [`CommandContext`](/api/default/interfaces/CommandContext.md)'s extensions. |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `dependencies` *(optional)* | ([`PluginDependency`](/api/default/interfaces/PluginDependency.md) | `string`)\[] | Plugin dependencies |
| `extension` | [`CommandContextExtension`](/api/default/interfaces/CommandContextExtension.md)<`E`> | Plugin extension |
| `id` | `string` | Plugin identifier |
| `name` | `string` | Plugin name |

---

---
url: /api/default/interfaces/PluginWithoutExtension.md
---
# Interface: PluginWithoutExtension\<E>

Plugin return type without extension, which includes the plugin ID, name, and dependencies, but no extension.

This type is used to define a plugin at `plugin` function without extension.

## Extends

* [`Plugin`](/api/default/type-aliases/Plugin.md)<`E`>

## Signature

```ts
export interface PluginWithoutExtension<
  E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']
> extends Plugin<E>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `E` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md)\['extensions'] = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)\['extensions'] | A type extending [GunshiParams](/api/default/interfaces/GunshiParams.md) to specify the shape of [`CommandContext`](/api/default/interfaces/CommandContext.md)'s extensions. |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `dependencies` *(optional)* | ([`PluginDependency`](/api/default/interfaces/PluginDependency.md) | `string`)\[] | Plugin dependencies |
| `id` | `string` | Plugin identifier |
| `name` | `string` | Plugin name |

---

---
url: /api/default/interfaces/RenderingOptions.md
---
# Interface: RenderingOptions\<G>

Rendering control options

## Since

v0.27.0

## Signature

```ts
export interface RenderingOptions<G extends GunshiParamsConstraint = DefaultGunshiParams>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of render options. |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `header` *(optional)* | ((`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>) => `Promise`<`string`>) | `null` | Header rendering configuration - `null`: Disable rendering - `function`: Use custom renderer - `undefined` (when omitted): Use default renderer |
| `usage` *(optional)* | ((`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>) => `Promise`<`string`>) | `null` | Usage rendering configuration - `null`: Disable rendering - `function`: Use custom renderer - `undefined` (when omitted): Use default renderer |
| `validationErrors` *(optional)* | ((`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>, `error`: `AggregateError`) => `Promise`<`string`>) | `null` | Validation errors rendering configuration - `null`: Disable rendering - `function`: Use custom renderer - `undefined` (when omitted): Use default renderer |

---

---
url: /api/default/interfaces/SubCommandable.md
---
# Interface: SubCommandable

Sub-command entry type for use in subCommands.

This type uses a loose structural match to bypass TypeScript's contravariance issues
with function parameters, allowing any Command or LazyCommand to be used as a sub-command.

## Since

v0.27.1

## Signature

```ts
export interface SubCommandable
```

## Indexable

```ts
[key: string]: any
```

Index signature to allow additional properties

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `args` *(optional)* | [`Args`](/api/default/interfaces/Args.md) | `Record`<`string`, `any`> | see [Command.args](/api/default/interfaces/Command.md#property-args) |
| `commandName` *(optional)* | `string` | see LazyCommand.commandName |
| `description` *(optional)* | `string` | see [Command.description](/api/default/interfaces/Command.md#property-description) |
| `entry` *(optional)* | `boolean` | see [Command.entry](/api/default/interfaces/Command.md#property-entry) |
| `examples` *(optional)* | `string` | ((...[`args`](/api/combinators/functions/args.md): `any`\[]) => `any`) | see [Command.examples](/api/default/interfaces/Command.md#property-examples) |
| `internal` *(optional)* | `boolean` | see [Command.internal](/api/default/interfaces/Command.md#property-internal) |
| `name` *(optional)* | `string` | see [Command.name](/api/default/interfaces/Command.md#property-name) |
| `rendering` *(optional)* | `any` | see [Command.rendering](/api/default/interfaces/Command.md#property-rendering) |
| `run` *(optional)* | (...[`args`](/api/combinators/functions/args.md): `any`\[]) => `any` | see [Command.run](/api/default/interfaces/Command.md#property-run) |
| `subCommands` *(optional)* | `Record<string, any> \| Map<string, any>` | Nested sub-commands for this command. **Since** v0.28.0 |
| `toKebab` *(optional)* | `boolean` | see [Command.toKebab](/api/default/interfaces/Command.md#property-tokebab) |

### run Parameters

| Name | Type | Description |
| --- | --- | --- |
| `args` | `any[]` |  |

### run Returns

`any`

---

---
url: /api/default/type-aliases/ArgsValidationErrorCode.md
---
# Type Alias: ArgsValidationErrorCode

A machine-readable argument validation error code.

Each code is one of ArgsValidationErrorKeys and can also be used as
an i18n resource key.

## Signature

```ts
export type ArgsValidationErrorCode = (typeof ArgsValidationErrorKeys)[keyof typeof ArgsValidationErrorKeys]
```

---

---
url: /api/default/type-aliases/ArgValues.md
---
# Type Alias: ArgValues\<T>

An object that contains the values of the arguments.

The value of an argument whose schema is a union, such as
`strict ? multiple(integer()) : string()` with the combinators, is typed as a value of any of its
schemas: `number[] | string`. The argument is typed as present only when each schema of the
union gives it a value, with a default, with `required: true` or as a required positional
argument.

When the type of one schema covers that of the other, as the type of `integer()` covers that of
`multiple(integer())`, TypeScript types a `?:` expression of them as the covering schema alone:
the value of `strict ? multiple(integer()) : integer()` is typed without the array, and
`strict ? multiple(positional()) : positional()` as present, although it may be missing. Give
each schema its own argument instead, or give the expression the type of both schemas with `as`,
as in `(strict ? many : one) as typeof many | typeof one` for `const many = multiple(integer())`
and `const one = integer()`.

## Signature

```ts
export type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]>; }> : { [option: string]: string | boolean | number | (string | boolean | number)[] | undefined; }
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` | [Arguments](/api/default/interfaces/Args.md) which is an object that defines the command line arguments. |

---

---
url: /api/default/type-aliases/Awaitable.md
---
# Type Alias: Awaitable\<T>

Awaitable type.

## Signature

```ts
export type Awaitable<T> = T | Promise<T>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` | The type of the value that can be awaited. |

---

---
url: /api/default/type-aliases/Commandable.md
---
# Type Alias: Commandable\<G>

Define a command type.

## Signature

```ts
export type Commandable<G extends GunshiParamsConstraint = DefaultGunshiParams> = Command<G> | LazyCommand<G, {}>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command. |

---

---
url: /api/default/type-aliases/CommandCallMode.md
---
# Type Alias: CommandCallMode

Command call mode.

* `entry`: The command is executed as an entry command.
* `subCommand`: The command is executed as a sub-command.

## Signature

```ts
export type CommandCallMode = "entry" | "subCommand" | "unexpected"
```

---

---
url: /api/default/type-aliases/CommandContextCore.md
---
# Type Alias: CommandContextCore\<G>

Readonly command context available to a command context extension factory.

## Since

v0.27.0

## Signature

```ts
export type CommandContextCore<G extends GunshiParamsConstraint = DefaultGunshiParams> = Readonly<CommandContext<G>>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command context. |

---

---
url: /api/default/type-aliases/CommandDecorator.md
---
# Type Alias: CommandDecorator\<G>

Command decorator.

A function that wraps a command runner to add or modify its behavior.

## Since

v0.27.0

## Signature

```ts
export type CommandDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRunner: (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>) => (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command context. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `baseRunner` | (`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`string` | `void`> | The base command runner to decorate |

## Returns

(`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>) => [`Awaitable`](/api/default/type-aliases/Awaitable.md)<`string` | `void`> — The decorated command runner

---

---
url: /api/default/type-aliases/CommandExamplesFetcher.md
---
# Type Alias: CommandExamplesFetcher\<G>

Command examples fetcher.

## Signature

```ts
export type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command context. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>> | A [command context](/api/default/interfaces/CommandContext.md) |

## Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<`string`> — A fetched command examples.

---

---
url: /api/default/type-aliases/CommandLoader.md
---
# Type Alias: CommandLoader\<G>

Command loader.

A function that returns a command or command runner.
This is used to lazily load commands.

## Signature

```ts
export type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = () => Awaitable<Command<G> | CommandRunner<G>>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command context and command runner. |

## Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<[`Command`](/api/default/interfaces/Command.md)<`G`> | [`CommandRunner`](/api/default/type-aliases/CommandRunner.md)<`G`>> — A command or command runner

---

---
url: /api/default/type-aliases/CommandNotFoundErrorCode.md
---
# Type Alias: CommandNotFoundErrorCode

Command not found error code.

## Signature

```ts
export type CommandNotFoundErrorCode = (typeof CommandNotFoundErrorKeys)[keyof typeof CommandNotFoundErrorKeys]
```

---

---
url: /api/default/type-aliases/CommandNotFoundErrorOptions.md
---
# Type Alias: CommandNotFoundErrorOptions

Options for [CommandNotFoundError](/api/default/classes/CommandNotFoundError.md).

## Signature

```ts
export type CommandNotFoundErrorOptions = { code?: CommandNotFoundErrorCode; values?: Record<string, unknown>; commandName: string; candidates?: readonly string[]; commandPath?: readonly string[]; cause?: unknown }
```

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `candidates` *(optional)* | `readonly string[]` | Command names available at the same level. |
| `cause` *(optional)* | `unknown` | Underlying cause. |
| `code` *(optional)* | [`CommandNotFoundErrorCode`](/api/default/type-aliases/CommandNotFoundErrorCode.md) | Localization resource key for command-not-found rendering. |
| `commandName` | `string` | The command name that could not be resolved. |
| `commandPath` *(optional)* | `readonly string[]` | Parent command path where resolution failed. |
| `values` *(optional)* | `Record<string, unknown>` | Values used when localizing the message. |

---

---
url: /api/default/type-aliases/CommandResolutionErrorCode.md
---
# Type Alias: CommandResolutionErrorCode

Command resolution error code.

## Signature

```ts
export type CommandResolutionErrorCode = (typeof CommandResolutionErrorKeys)[keyof typeof CommandResolutionErrorKeys]
```

---

---
url: /api/default/type-aliases/CommandResolutionErrorOptions.md
---
# Type Alias: CommandResolutionErrorOptions

Options for [CommandResolutionError](/api/default/classes/CommandResolutionError.md).

## Signature

```ts
export type CommandResolutionErrorOptions = { code?: CommandResolutionErrorCode; values?: Record<string, unknown>; commandPath?: readonly string[]; candidatePaths?: readonly (readonly string[])[]; cause?: unknown }
```

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `candidatePaths` *(optional)* | `readonly (readonly string[])[]` | Candidate command paths considered by the resolver. |
| `cause` *(optional)* | `unknown` | Underlying cause. |
| `code` *(optional)* | [`CommandResolutionErrorCode`](/api/default/type-aliases/CommandResolutionErrorCode.md) | Localization resource key for the resolution failure. |
| `commandPath` *(optional)* | `readonly string[]` | Command path at which the resolution failed. |
| `values` *(optional)* | `Record<string, unknown>` | Values used when localizing the message. |

---

---
url: /api/default/type-aliases/CommandRunner.md
---
# Type Alias: CommandRunner\<G>

Command runner.

## Signature

```ts
export type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string | void>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command context. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>> | A [command context](/api/default/interfaces/CommandContext.md) |

## Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<`string` | `void`> — void or string (for CLI output)

---

---
url: /api/default/type-aliases/DefaultGunshiParams.md
---
# Type Alias: DefaultGunshiParams

Default Gunshi parameters.

## Since

v0.27.0

## Signature

```ts
export type DefaultGunshiParams = GunshiParams
```

---

---
url: /api/default/type-aliases/ExtendContext.md
---
# Type Alias: ExtendContext

Extend command context type. This type is used to extend the command context with additional properties at [`CommandContext.extensions`](/api/default/interfaces/CommandContext.md#property-extensions).

## Since

v0.27.0

## Signature

```ts
export type ExtendContext = Record<string, unknown>
```

---

---
url: /api/default/type-aliases/GunshiParamsConstraint.md
---
# Type Alias: GunshiParamsConstraint

Generic constraint for command-related types.

This type constraint allows both [`GunshiParams`](/api/default/interfaces/GunshiParams.md) and objects with extensions.

## Since

v0.27.0

## Signature

```ts
export type GunshiParamsConstraint = GunshiParams<any> | { args: Args } | { extensions: ExtendContext }
```

---

---
url: /api/default/type-aliases/LazyCommand.md
---
# Type Alias: LazyCommand\<G, D>

Lazy command interface.

Lazy command that's not loaded until it is executed.

## Signature

```ts
export type LazyCommand<
  G extends GunshiParamsConstraint = DefaultGunshiParams,
  D extends Partial<Command<G>> = {}
> = { (): Awaitable<Command<G> | CommandRunner<G>> } & (D extends { name: infer N } ? { commandName: N } : { commandName?: string }) & Omit<D, 'name' | 'run'> & Partial<Omit<Command<G>, keyof D | 'run' | 'name'>>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | The Gunshi parameters constraint |
| `D` *extends* `Partial`<[`Command`](/api/default/interfaces/Command.md)<`G`>> = `{}` | The partial command definition provided to lazy function |

---

---
url: /api/default/type-aliases/OnPluginExtension.md
---
# Type Alias: OnPluginExtension\<G>

Plugin extension callback, which is called when the plugin is extended with `extension` option.

## Since

v0.27.0

## Signature

```ts
export type OnPluginExtension<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>, cmd: Readonly<Command<G>>) => Awaitable<void>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of [`CommandContext`](/api/default/interfaces/CommandContext.md) and [`Command`](/api/default/interfaces/Command.md). |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>> | The [`command context`](/api/default/interfaces/CommandContext.md) |
| `cmd` | `Readonly`<[`Command`](/api/default/interfaces/Command.md)<`G`>> | The [`command`](/api/default/interfaces/Command.md) |

## Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`>

---

---
url: /api/default/type-aliases/Plugin.md
---
# Type Alias: Plugin\<E>

Gunshi plugin, which is a function that receives a PluginContext.

## Since

v0.27.0

## Signature

```ts
export type Plugin<E extends GunshiParams['extensions'] = DefaultGunshiParams['extensions']> = PluginFunction & { id: string; name?: string; dependencies?: (PluginDependency | string)[]; extension?: CommandContextExtension<E> }
```

## Type Parameters

| Name | Description |
| --- | --- |
| `E` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md)\['extensions'] = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md)\['extensions'] | A type extending [GunshiParams](/api/default/interfaces/GunshiParams.md) to specify the shape of [`CommandContext`](/api/default/interfaces/CommandContext.md)'s extensions. |

## Properties

| Name | Type | Description |
| --- | --- | --- |
| `dependencies` *(optional)* | ([`PluginDependency`](/api/default/interfaces/PluginDependency.md) | `string`)\[] |  |
| `extension` *(optional)* | [`CommandContextExtension`](/api/default/interfaces/CommandContextExtension.md)<`E`> |  |
| `id` | `string` |  |
| `name` *(optional)* | `string` |  |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `Readonly`<[`PluginContext`](/api/default/interfaces/PluginContext.md)<`G`>> | A [`PluginContext`](/api/default/interfaces/PluginContext.md). |

## Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`> — An [`Awaitable`](/api/default/type-aliases/Awaitable.md) that resolves when the plugin is loaded.

---

---
url: /api/default/type-aliases/PluginExtension.md
---
# Type Alias: PluginExtension\<T, G>

Plugin extension

## Since

v0.27.0

## Signature

```ts
export type PluginExtension<
  T = Record<string, unknown>,
  G extends GunshiParams = DefaultGunshiParams
> = (ctx: CommandContextCore<G>, cmd: Command<G>) => Awaitable<T>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` = `Record<string, unknown>` | The type of the extension object returned by the plugin extension function. |
| `G` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of [`CommandContextCore`](/api/default/type-aliases/CommandContextCore.md). |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | [`CommandContextCore`](/api/default/type-aliases/CommandContextCore.md)<`G`> | The [`command context`](/api/default/type-aliases/CommandContextCore.md) core |
| `cmd` | [`Command`](/api/default/interfaces/Command.md)<`G`> | The [`command`](/api/default/interfaces/Command.md) to which the plugin is being applied |

## Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<`T`> — An object of type T that represents the extension provided by the plugin

---

---
url: /api/default/type-aliases/PluginFunction.md
---
# Type Alias: PluginFunction\<G>

Plugin function type

## Since

v0.27.0

## Signature

```ts
export type PluginFunction<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readonly<PluginContext<G>>) => Awaitable<void>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the [`PluginContext`](/api/default/interfaces/PluginContext.md). |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `Readonly`<[`PluginContext`](/api/default/interfaces/PluginContext.md)<`G`>> |  |

## Returns

[`Awaitable`](/api/default/type-aliases/Awaitable.md)<`void`>

---

---
url: /api/default/type-aliases/Prettify.md
---
# Type Alias: Prettify\<T>

Prettify a type by flattening its structure.

## Signature

```ts
export type Prettify<T> = { [K in keyof T]: T[K] } & {}
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` | The type to be prettified. |

---

---
url: /api/default/type-aliases/RendererDecorator.md
---
# Type Alias: RendererDecorator\<T, G>

Renderer decorator type.

A function that wraps a base renderer to add or modify its behavior.

## Since

v0.27.0

## Signature

```ts
export type RendererDecorator<T, G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRenderer: (ctx: Readonly<CommandContext<G>>) => Promise<T>, ctx: Readonly<CommandContext<G>>) => Promise<T>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `T` | The type of the rendered result. |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command context. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `baseRenderer` | (`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>) => `Promise`<`T`> | The base renderer function to decorate |
| `ctx` | `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>> | The command context |

## Returns

`Promise<T>` — The decorated result

---

---
url: /api/default/type-aliases/ValidationErrorsDecorator.md
---
# Type Alias: ValidationErrorsDecorator\<G>

Validation errors renderer decorator type.
A function that wraps a validation errors renderer to add or modify its behavior.

## Since

v0.27.0

## Signature

```ts
export type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRenderer: (ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command context. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `baseRenderer` | (`ctx`: `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>>, `error`: `AggregateError`) => `Promise`<`string`> | The base validation errors renderer function to decorate |
| `ctx` | `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>> | The command context |
| `error` | `AggregateError` | The aggregate error containing validation errors |

## Returns

`Promise<string>` — The decorated result

---

---
url: /api/definition.md
---
# definition

The entry for gunshi command definition.

This entry point exports the following APIs and types:

* `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.
* Some basic type definitions, such as `Command`, `LazyCommand`, etc.

## Example

```js
import { define } from 'gunshi/definition'

export default define({
  name: 'say',
  args: {
    say: {
      type: 'string',
      description: 'say something',
      default: 'hello!'
    }
  },
  run: ctx => {
    return `You said: ${ctx.values.say}`
  }
})
```

## Functions

| Function | Description |
| ------ | ------ |
| [define](/api/definition/functions/define.md) | Define a [command](/api/default/interfaces/Command.md). |
| [defineWithTypes](/api/definition/functions/defineWithTypes.md) | Define a [command](/api/default/interfaces/Command.md) with types |
| [lazy](/api/definition/functions/lazy.md) | Define a [lazy command](/api/default/type-aliases/LazyCommand.md). |
| [lazyWithTypes](/api/definition/functions/lazyWithTypes.md) | Define a [lazy command](/api/default/type-aliases/LazyCommand.md) with specific type parameters. |

## References

### Args

Re-exports [Args](/api/default/interfaces/Args.md)

***

### ArgSchema

Re-exports [ArgSchema](/api/default/interfaces/ArgSchema.md)

***

### ArgValues

Re-exports [ArgValues](/api/default/type-aliases/ArgValues.md)

***

### Command

Re-exports [Command](/api/default/interfaces/Command.md)

***

### CommandContextParams

Re-exports [CommandContextParams](/api/context/interfaces/CommandContextParams.md)

***

### CommandLoader

Re-exports [CommandLoader](/api/default/type-aliases/CommandLoader.md)

***

### CommandRunner

Re-exports [CommandRunner](/api/default/type-aliases/CommandRunner.md)

***

### createCommandContext

Re-exports [createCommandContext](/api/context/functions/createCommandContext.md)

***

### DefaultGunshiParams

Re-exports [DefaultGunshiParams](/api/default/type-aliases/DefaultGunshiParams.md)

***

### ExtendContext

Re-exports [ExtendContext](/api/default/type-aliases/ExtendContext.md)

***

### GunshiParams

Re-exports [GunshiParams](/api/default/interfaces/GunshiParams.md)

***

### LazyCommand

Re-exports [LazyCommand](/api/default/type-aliases/LazyCommand.md)

---

---
url: /api/definition/functions/define.md
---
# Function: define()

Define a [command](/api/default/interfaces/Command.md).

## Signature

```ts
export function define<
  G extends GunshiParamsConstraint = DefaultGunshiParams,
  A extends Args = ExtractArgs<G>,
  C extends Partial<Command<{ args: A; extensions: ExtractExtensions<G> }>> = {}
>(definition: CommandDefinition<A, ExtractExtensions<G>, C>): CommandDefinitionResult<G, C>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A [GunshiParamsConstraint](/api/default/type-aliases/GunshiParamsConstraint.md) type |
| `A` *extends* [`Args`](/api/default/interfaces/Args.md) = `ExtractArgs<G>` | An [Args](/api/default/interfaces/Args.md) type extracted from [GunshiParamsConstraint](/api/default/type-aliases/GunshiParamsConstraint.md) |
| `C` *extends* `Partial`<[`Command`](/api/default/interfaces/Command.md)<{ [`args`](/api/combinators/functions/args.md): `A`; `extensions`: `ExtractExtensions`<`G`> }>> = `{}` | A [Command](/api/default/interfaces/Command.md) type inferred from [GunshiParamsConstraint](/api/default/type-aliases/GunshiParamsConstraint.md) |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `definition` | `CommandDefinition<A, ExtractExtensions<G>, C>` | A [command](/api/default/interfaces/Command.md) definition |

## Returns

`CommandDefinitionResult<G, C>` — A defined [command](/api/default/interfaces/Command.md)

## Examples

```ts
const command = define({
  name: 'test',
  description: 'A test command',
  args: {
    debug: {
      type: 'boolean',
      description: 'Enable debug mode',
      default: false
    }
  },
  run: ctx => {
    if (ctx.values.debug) {
      console.debug('Debug mode is enabled');
    }
  }
})
```

---

---
url: /api/definition/functions/defineWithTypes.md
---
# Function: defineWithTypes()

Define a [command](/api/default/interfaces/Command.md) with types

This helper function allows specifying the type parameter of [GunshiParamsConstraint](/api/default/type-aliases/GunshiParamsConstraint.md)
while inferring the [Args](/api/default/interfaces/Args.md) type, [ExtendContext](/api/default/type-aliases/ExtendContext.md) type from the definition.

## Since

v0.27.0

## Signature

```ts
export function defineWithTypes<G extends GunshiParamsConstraint>(): DefineWithTypesReturn<
  ExtractExtensions<G>,
  ExtractArgs<G>
>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) | A [GunshiParamsConstraint](/api/default/type-aliases/GunshiParamsConstraint.md) type |

## Returns

`DefineWithTypesReturn<ExtractExtensions<G>, ExtractArgs<G>>` — A function that takes a command definition via [define](/api/definition/functions/define.md)

## Examples

```ts
// Define a command with specific extensions type
type MyExtensions = { logger: { log: (message: string) => void } }

const command = defineWithTypes<{ extensions: MyExtensions }>()({
  name: 'greet',
  args: {
    name: { type: 'string' }
  },
  run: ctx => {
    // ctx.values is inferred as { name?: string }
    // ctx.extensions is MyExtensions
  }
})
```

---

---
url: /api/definition/functions/lazy.md
---
# Function: lazy()

Define a [lazy command](/api/default/type-aliases/LazyCommand.md) with or without definition.

## Call Signature

```ts
export function lazy<A extends Args>(loader: CommandLoader<{ args: A; extensions: {} }>): LazyCommand<{ args: A; extensions: {} }, {}>
```

Define a [lazy command](/api/default/type-aliases/LazyCommand.md).

### Type Parameters

| Name | Description |
| --- | --- |
| `A` *extends* [`Args`](/api/default/interfaces/Args.md) | An [Args](/api/default/interfaces/Args.md) type |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `loader` | [`CommandLoader`](/api/default/type-aliases/CommandLoader.md)<{ [`args`](/api/combinators/functions/args.md): `A`; `extensions`: {} }> | A [command loader](/api/default/type-aliases/CommandLoader.md) |

### Returns

[`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<{ [`args`](/api/combinators/functions/args.md): `A`; `extensions`: {} }, {}> — A [lazy command](/api/default/type-aliases/LazyCommand.md) with loader

### Examples

```ts
// load command with dynamic importing
const test = lazy(() => import('./commands/test'))
```

## Call Signature

```ts
export function lazy<
  D extends { args: Args } & Partial<Command<{ args: D['args']; extensions: {} }>>
>(loader: CommandLoader<{ args: D['args']; extensions: {} }>, definition: D): LazyCommand<{ args: D['args']; extensions: {} }, D>
```

Define a [lazy command](/api/default/type-aliases/LazyCommand.md) with definition.

### Type Parameters

| Name | Description |
| --- | --- |
| `D` *extends* { [`args`](/api/combinators/functions/args.md): [`Args`](/api/default/interfaces/Args.md) } & `Partial`<[`Command`](/api/default/interfaces/Command.md)<{ [`args`](/api/combinators/functions/args.md): `D`\['args']; `extensions`: {} }>> | A partial [Command](/api/default/interfaces/Command.md) definition type with required `args` |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `loader` | [`CommandLoader`](/api/default/type-aliases/CommandLoader.md)<{ [`args`](/api/combinators/functions/args.md): `D`\['args']; `extensions`: {} }> | A [command loader](/api/default/type-aliases/CommandLoader.md) function that returns a command definition |
| `definition` | `D` | A [command](/api/default/interfaces/Command.md) definition. Its `name` may be omitted, including when the lazy command is used as the CLI entry command. |

### Returns

[`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<{ [`args`](/api/combinators/functions/args.md): `D`\['args']; `extensions`: {} }, `D`> — A [lazy command](/api/default/type-aliases/LazyCommand.md) that can be executed later

### Examples

```ts
// define command without command runner
const testDefinition = define({
  name: 'test',
  description: 'Test command',
  args: {
    debug: {
      type: 'boolean',
      description: 'Enable debug mode',
      default: false
    }
  },
})

// define load command with command runner and defined command
const test = lazy((): CommandRunner<{ args: typeof testDefinition.args; extensions: {} }> => {
  return ctx => {
    if (ctx.values.debug) {
      console.debug('Debug mode is enabled');
    }
  }
}, testDefinition)
```

## Call Signature

```ts
export function lazy<
  G extends GunshiParamsConstraint = DefaultGunshiParams,
  D extends Partial<Command<G>> = Partial<Command<G>>
>(loader: CommandLoader<G>, definition?: D): LazyCommand<G, D>
```

Define a [lazy command](/api/default/type-aliases/LazyCommand.md) with explicit Gunshi parameters and optional definition.

### Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A [GunshiParamsConstraint](/api/default/type-aliases/GunshiParamsConstraint.md) |
| `D` *extends* `Partial`<[`Command`](/api/default/interfaces/Command.md)<`G`>> = `Partial`<[`Command`](/api/default/interfaces/Command.md)<`G`>> | A partial [Command](/api/default/interfaces/Command.md) definition type |

### Parameters

| Name | Type | Description |
| --- | --- | --- |
| `loader` | [`CommandLoader`](/api/default/type-aliases/CommandLoader.md)<`G`> | A [command loader](/api/default/type-aliases/CommandLoader.md) function that returns a command definition |
| `definition` | `D` | An optional [command](/api/default/interfaces/Command.md) definition. Its `name` may be omitted, including when the lazy command is used as the CLI entry command. *(optional)* |

### Returns

[`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<`G`, `D`> — A [lazy command](/api/default/type-aliases/LazyCommand.md) that can be executed later

---

---
url: /api/definition/functions/lazyWithTypes.md
---
# Function: lazyWithTypes()

Define a [lazy command](/api/default/type-aliases/LazyCommand.md) with specific type parameters.

This helper function allows specifying the type parameter of [GunshiParamsConstraint](/api/default/type-aliases/GunshiParamsConstraint.md)
while inferring the [Args](/api/default/interfaces/Args.md) type, [ExtendContext](/api/default/type-aliases/ExtendContext.md) type from the definition.

## Since

v0.27.0

## Signature

```ts
export function lazyWithTypes<G extends GunshiParamsConstraint>(): LazyWithTypesReturn<
  NormalizeToGunshiParams<G>
>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) | A [GunshiParamsConstraint](/api/default/type-aliases/GunshiParamsConstraint.md) type |

## Returns

`LazyWithTypesReturn<NormalizeToGunshiParams<G>>` — A function that takes a lazy command definition via [lazy](/api/definition/functions/lazy.md)

## Examples

```ts
type MyExtensions = { logger: { log: (message: string) => void } }

const command = lazyWithTypes<{ extensions: MyExtensions }>()(
  () => {
    return ctx => {
      // Command runner implementation
      ctx.extensions.logger?.log('Command executed')
  },
 {
  name: 'lazy-command',
  args: {
    opt: {
      type: 'string',
      description: 'An optional string argument',
      required: false,
    },
  },
)
```

---

---
url: /api/generator.md
---
# generator

The entry for usage generator.

## Example

```js
import { generate } from 'gunshi/generator'
```

## Functions

| Function | Description |
| ------ | ------ |
| [generate](/api/generator/functions/generate.md) | Generate the command usage. |

## Type Aliases

| Type Alias | Description |
| ------ | ------ |
| [GenerateOptions](/api/generator/type-aliases/GenerateOptions.md) | generate options of `generate` function. |

---

---
url: /api/generator/functions/generate.md
---
# Function: generate()

Generate the command usage.

## Signature

```ts
export async function generate<G extends GunshiParamsConstraint = DefaultGunshiParams>(command: string | string[] | null, entry: Command<G> | LazyCommand<G>, options: GenerateOptions<G> = {}): Promise<string>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of command parameters. |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `command` | `string \| string[] \| null` | usage generate command, if you want to generate the usage of the default command where there are target commands and sub-commands, specify `null`. |
| `entry` | [`Command`](/api/default/interfaces/Command.md)<`G`> | [`LazyCommand`](/api/default/type-aliases/LazyCommand.md)<`G`> | A [`entry command`](/api/default/interfaces/Command.md) |
| `options` | [`GenerateOptions`](/api/generator/type-aliases/GenerateOptions.md)<`G`> | A [`cli options`](/api/generator/type-aliases/GenerateOptions.md) *(optional, default: {})* |

## Returns

`Promise<string>` — A rendered usage.

---

---
url: /api/generator/type-aliases/GenerateOptions.md
---
# Type Alias: GenerateOptions\<G>

generate options of `generate` function.

## Signature

```ts
export type GenerateOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> = CliOptions<G>
```

## Type Parameters

| Name | Description |
| --- | --- |
| `G` *extends* [`GunshiParamsConstraint`](/api/default/type-aliases/GunshiParamsConstraint.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) | A type extending [`GunshiParams`](/api/default/interfaces/GunshiParams.md) to specify the shape of [`CliOptions`](/api/default/interfaces/CliOptions.md). |

---

---
url: /api/plugin.md
---
# plugin

The entry point for Gunshi plugin module.

## Example

```js
import { plugin } from 'gunshi/plugin'

export default yourPlugin() {
  return plugin({
    id: 'your-plugin-id',
    setup: (ctx) => {
      // your plugin setup logic here
    },
  })
}
```

## Variables

| Variable | Description |
| ------ | ------ |
| [CLI\_OPTIONS\_DEFAULT](/api/plugin/variables/CLI_OPTIONS_DEFAULT.md) |  |

## References

### ANONYMOUS\_COMMAND\_NAME

Re-exports [ANONYMOUS\_COMMAND\_NAME](/api/default/variables/ANONYMOUS_COMMAND_NAME.md)

***

### Args

Re-exports [Args](/api/default/interfaces/Args.md)

***

### ArgSchema

Re-exports [ArgSchema](/api/default/interfaces/ArgSchema.md)

***

### ArgsValidationError

Re-exports [ArgsValidationError](/api/default/classes/ArgsValidationError.md)

***

### ArgsValidationErrorCode

Re-exports [ArgsValidationErrorCode](/api/default/type-aliases/ArgsValidationErrorCode.md)

***

### ArgToken

Re-exports [ArgToken](/api/default/interfaces/ArgToken.md)

***

### ArgValues

Re-exports [ArgValues](/api/default/type-aliases/ArgValues.md)

***

### Awaitable

Re-exports [Awaitable](/api/default/type-aliases/Awaitable.md)

***

### Command

Re-exports [Command](/api/default/interfaces/Command.md)

***

### CommandContext

Re-exports [CommandContext](/api/default/interfaces/CommandContext.md)

***

### CommandContextCore

Re-exports [CommandContextCore](/api/default/type-aliases/CommandContextCore.md)

***

### CommandContextExtension

Re-exports [CommandContextExtension](/api/default/interfaces/CommandContextExtension.md)

***

### CommandContextParams

Re-exports [CommandContextParams](/api/context/interfaces/CommandContextParams.md)

***

### CommandDecorator

Re-exports [CommandDecorator](/api/default/type-aliases/CommandDecorator.md)

***

### CommandExamplesFetcher

Re-exports [CommandExamplesFetcher](/api/default/type-aliases/CommandExamplesFetcher.md)

***

### CommandNotFoundError

Re-exports [CommandNotFoundError](/api/default/classes/CommandNotFoundError.md)

***

### CommandNotFoundErrorCode

Re-exports [CommandNotFoundErrorCode](/api/default/type-aliases/CommandNotFoundErrorCode.md)

***

### CommandNotFoundErrorKeys

Re-exports [CommandNotFoundErrorKeys](/api/default/variables/CommandNotFoundErrorKeys.md)

***

### CommandNotFoundErrorOptions

Re-exports [CommandNotFoundErrorOptions](/api/default/type-aliases/CommandNotFoundErrorOptions.md)

***

### CommandResolutionError

Re-exports [CommandResolutionError](/api/default/classes/CommandResolutionError.md)

***

### CommandResolutionErrorCode

Re-exports [CommandResolutionErrorCode](/api/default/type-aliases/CommandResolutionErrorCode.md)

***

### CommandResolutionErrorKeys

Re-exports [CommandResolutionErrorKeys](/api/default/variables/CommandResolutionErrorKeys.md)

***

### CommandResolutionErrorOptions

Re-exports [CommandResolutionErrorOptions](/api/default/type-aliases/CommandResolutionErrorOptions.md)

***

### CommandRunner

Re-exports [CommandRunner](/api/default/type-aliases/CommandRunner.md)

***

### createCommandContext

Re-exports [createCommandContext](/api/context/functions/createCommandContext.md)

***

### DefaultGunshiParams

Re-exports [DefaultGunshiParams](/api/default/type-aliases/DefaultGunshiParams.md)

***

### ExtendContext

Re-exports [ExtendContext](/api/default/type-aliases/ExtendContext.md)

***

### GunshiParams

Re-exports [GunshiParams](/api/default/interfaces/GunshiParams.md)

***

### GunshiParamsConstraint

Re-exports [GunshiParamsConstraint](/api/default/type-aliases/GunshiParamsConstraint.md)

***

### hasPriorityValidationError

Re-exports [hasPriorityValidationError](/api/default/functions/hasPriorityValidationError.md)

***

### isArgsValidationError

Re-exports [isArgsValidationError](/api/default/functions/isArgsValidationError.md)

***

### isCommandNotFoundError

Re-exports [isCommandNotFoundError](/api/default/functions/isCommandNotFoundError.md)

***

### isCommandResolutionError

Re-exports [isCommandResolutionError](/api/default/functions/isCommandResolutionError.md)

***

### LazyCommand

Re-exports [LazyCommand](/api/default/type-aliases/LazyCommand.md)

***

### OnPluginExtension

Re-exports [OnPluginExtension](/api/default/type-aliases/OnPluginExtension.md)

***

### Plugin

Re-exports [Plugin](/api/default/type-aliases/Plugin.md)

***

### plugin

Re-exports [plugin](/api/default/functions/plugin.md)

***

### PluginContext

Re-exports [PluginContext](/api/default/interfaces/PluginContext.md)

***

### PluginDependency

Re-exports [PluginDependency](/api/default/interfaces/PluginDependency.md)

***

### PluginExtension

Re-exports [PluginExtension](/api/default/type-aliases/PluginExtension.md)

***

### PluginFunction

Re-exports [PluginFunction](/api/default/type-aliases/PluginFunction.md)

***

### PluginOptions

Re-exports [PluginOptions](/api/default/interfaces/PluginOptions.md)

***

### PluginWithExtension

Re-exports [PluginWithExtension](/api/default/interfaces/PluginWithExtension.md)

***

### PluginWithoutExtension

Re-exports [PluginWithoutExtension](/api/default/interfaces/PluginWithoutExtension.md)

***

### Prettify

Re-exports [Prettify](/api/default/type-aliases/Prettify.md)

***

### RendererDecorator

Re-exports [RendererDecorator](/api/default/type-aliases/RendererDecorator.md)

***

### ValidationErrorsDecorator

Re-exports [ValidationErrorsDecorator](/api/default/type-aliases/ValidationErrorsDecorator.md)

---

---
url: /api/plugin/variables/CLI_OPTIONS_DEFAULT.md
---
# Variable: CLI\_OPTIONS\_DEFAULT

## Signature

```ts
export const CLI_OPTIONS_DEFAULT: CliOptions<DefaultGunshiParams>
```

---

---
url: /api/renderer.md
---
# renderer

The entry point for Gunshi renderer.

## Example

```js
import { renderHeader, renderUsage, renderValidationErrors } from 'gunshi/renderer'
```

## Functions

| Function | Description |
| ------ | ------ |
| [renderHeader](/api/renderer/functions/renderHeader.md) | Render the header. |
| [renderUsage](/api/renderer/functions/renderUsage.md) | Render the usage. |
| [renderValidationErrors](/api/renderer/functions/renderValidationErrors.md) | Render the validation errors. |

---

---
url: /api/renderer/functions/renderHeader.md
---
# Function: renderHeader()

Render the header.

## Signature

```ts
declare function renderHeader<G extends GunshiParams = DefaultGunshiParams>(ctx: Readonly<CommandContext<G>>): Promise<string>
```

## Type Parameters

| Name |
| --- |
| `G` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>> | A [command context](/api/default/interfaces/CommandContext.md) |

## Returns

`Promise<string>` — A rendered header.

---

---
url: /api/renderer/functions/renderUsage.md
---
# Function: renderUsage()

Render the usage.

## Signature

```ts
declare function renderUsage<G extends GunshiParams = DefaultGunshiParams>(ctx: Readonly<CommandContext<G>>): Promise<string>
```

## Type Parameters

| Name |
| --- |
| `G` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | `Readonly`<[`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`>> | A [command context](/api/default/interfaces/CommandContext.md) |

## Returns

`Promise<string>` — A rendered usage.

---

---
url: /api/renderer/functions/renderValidationErrors.md
---
# Function: renderValidationErrors()

Render the validation errors.

## Signature

```ts
declare function renderValidationErrors<G extends GunshiParams = DefaultGunshiParams>(ctx: CommandContext<G>, error: AggregateError): Promise<string>
```

## Type Parameters

| Name |
| --- |
| `G` *extends* [`GunshiParams`](/api/default/interfaces/GunshiParams.md) = [`DefaultGunshiParams`](/api/default/type-aliases/DefaultGunshiParams.md) |

## Parameters

| Name | Type | Description |
| --- | --- | --- |
| `ctx` | [`CommandContext`](/api/default/interfaces/CommandContext.md)<`G`> | A [command context](/api/default/interfaces/CommandContext.md) |
| `error` | `AggregateError` | An AggregateError of option in `args-token` validation |

## Returns

`Promise<string>` — A rendered validation error.

---

---
url: /showcase.md
---
# Showcase

Gunshi is used in the following projects:
(no particular order)

* [pnpmc](https://github.com/kazupon/pnpmc): PNPM Catalogs Tooling
* [sourcemap-publisher](https://github.com/es-tooling/sourcemap-publisher): A tool to publish sourcemaps externally and rewrite sourcemap URLs at pre-publish time
* [curxy](https://github.com/ryoppippi/curxy): An proxy worker for using ollama in cursor
* [SiteMCP](https://github.com/ryoppippi/sitemcp): Fetch an entire site and use it as a MCP Server
* [ccusage](https://github.com/ryoppippi/ccusage): A CLI tool for analyzing Claude Code usage from local JSONL files
* [varlock](https://github.com/dmno-dev/varlock): Enhanced .env file loader, using @decorator style comments to add validation, type-safety, and more

---

---
url: /release/v0.27.md
---
# Gunshi v0.27 Release Notes

## 🌟 Features

### Plugin System

Gunshi v0.27 introduces a powerful plugin system that enables modular CLI architecture. Plugins can extend command functionality, add global options, and provide cross-cutting concerns like internationalization and completion.

```ts
import { cli } from 'gunshi'
import i18n, { defineI18nWithTypes, pluginId as i18nId } from '@gunshi/plugin-i18n'
import completion from '@gunshi/plugin-completion'
import type { I18nExtension, PluginId as I18nPluginId } from '@gunshi/plugin-i18n'

// Type-safe command definition with plugin extensions
const command = defineI18nWithTypes<{ extensions: Record<I18nPluginId, I18nExtension> }>()({
  name: 'app',
  // Provide translation resources for i18n plugin
  resource: locale => {
    if (locale.toString() === 'ja-JP') {
      return { greeting: 'こんにちは' }
    }
    return { greeting: 'Hello' }
  },
  run: ctx => {
    // Plugins automatically extend the context
    console.log(ctx.extensions[i18nId].translate('greeting'))
  }
})

await cli(process.argv.slice(2), command, {
  name: 'my-app',
  version: '1.0.0',
  plugins: [i18n(), completion()]
})
```

Plugins can extend the `CommandContext` by adding their own properties to `ctx.extensions`. Each plugin's extension is namespaced using its plugin ID, preventing conflicts and ensuring type safety:

* Extensions are accessed via `ctx.extensions[pluginId]`
* Plugin IDs should be imported to avoid hardcoding strings
* TypeScript provides full type inference for extensions when using `define<Record<PluginId, Extension>>()`
* Multiple plugins can coexist, each providing their own extensions

In the example above, the i18n plugin extends `ctx.extensions` with internationalization functionality accessible via `ctx.extensions[i18nId]`. This provides methods like `translate()` and properties like `locale` to all commands, enabling consistent internationalization across your CLI application.

### Official Plugin Ecosystem

Gunshi v0.27 comes with a comprehensive set of official plugins that work seamlessly with the new plugin system:

#### Built-in Plugins (included in `gunshi` package)

These plugins are automatically included when using the standard `cli()` function from gunshi:

* `@gunshi/plugin-global`: Adds `--help` and `--version` options to all commands automatically
  * Provides `showVersion()`, `showHeader()`, `showUsage()`, and `showValidationErrors()` methods
  * Intercepts command execution to handle help/version display

* `@gunshi/plugin-renderer`: Automatic rendering of usage, help text, and validation errors
  * Integrates with i18n plugin for localized messages
  * Customizable rendering for headers, usage, and error messages
  * Smart formatting for arguments, options, and subcommands

#### Optional Plugins

Install these plugins separately based on your needs:

* `gunshi/plugin-i18n`: Comprehensive internationalization support

  ```sh
  npm install @gunshi/plugin-i18n
  ```

  * Type-safe translation functions with key completion
  * Dynamic resource loading per command
  * Custom translation adapters
  * Built-in namespace management

* `@gunshi/plugin-completion`: Shell completion support

  ```sh
  npm install @gunshi/plugin-completion
  ```

  * Support for bash, zsh, fish, and PowerShell
  * Custom completion handlers for dynamic suggestions
  * Automatic `complete` subcommand generation
  * Integration with i18n for localized descriptions

### `@gunshi/definition` - Command Definition Utilities

New standalone package for creating reusable, distributable commands:

```sh
npm install @gunshi/definition
```

This package enables you to create standalone commands that can be published as libraries and shared across multiple CLI applications:

```js
// my-shared-commands/build.js
import { define } from '@gunshi/definition'

// Create a standalone command that can be imported by any Gunshi CLI
export const buildCommand = define({
  name: 'build',
  args: {
    watch: { type: 'boolean', default: false },
    output: { type: 'string', required: true }
  },
  run: ctx => {
    if (ctx.values.watch) {
      console.log(`Watching and building to ${ctx.values.output}`)
    }
  }
})

// my-shared-commands/analyze.js
import { lazy } from '@gunshi/definition'

// Export a lazy-loaded command for better performance
export const analyzeCommand = lazy(async () => {
  // Heavy imports only when command is actually used
  const { analyze } = await import('./heavy-analyzer.js')

  return {
    name: 'analyze',
    run: ctx => analyze(ctx.values)
  }
})
```

Now these commands can be imported and used in any Gunshi CLI:

```js
// app-cli/index.js
import { cli } from 'gunshi'
import { buildCommand, analyzeCommand } from 'my-shared-commands'

await cli(process.argv.slice(2), buildCommand, {
  name: 'app',
  subCommands: {
    build: buildCommand,
    analyze: analyzeCommand
  }
})
```

Benefits:

* **Standalone commands**: Create reusable commands that can be published as npm packages
* **Framework-agnostic distribution**: Commands defined with `@gunshi/definition` can be imported by any Gunshi CLI
* **Smaller bundles**: Separate from main gunshi package for optimal tree-shaking
* **Full type safety**: Complete TypeScript inference for arguments and extensions (see [Type Safety Enhancements](#type-safety-enhancements) for details)
* **Mix and match**: Combine commands from multiple packages to build your CLI

### `@gunshi/bone` - Minimal CLI Package

A lightweight alternative to the main gunshi package, without any built-in plugins:

```sh
npm install @gunshi/bone
```

```js
import { cli } from '@gunshi/bone'
import customPlugin from './my-custom-plugin.js'

// No default plugins - you have full control
await cli(process.argv.slice(2), command, {
  name: 'my-minimal-cli',
  plugins: [customPlugin()] // Only the plugins you need
})
```

Use cases:

* When you need complete control over plugin composition
* For minimal bundle size in size-critical applications
* When built-in plugins conflict with your custom implementation
* For embedded CLIs where every byte counts

### `@gunshi/docs` - LLM-Assisted Development (Experimental)

New package for integrating with AI coding assistants such as [Claude Code](https://claude.ai/code):

```sh
npx @gunshi/docs
```

This command automatically configures:

* [Claude Code skills](https://docs.anthropic.com/en/docs/claude-code/skills) at `.claude/skills/use-gunshi-cli/SKILL.md`
* Updates `CLAUDE.md` with instructions to use the Gunshi skill

Optionally, it can also install `gunshi` and `@gunshi/docs` packages for you.

For manual setup, install the documentation package as a dev dependency:

```sh
npm install --save-dev @gunshi/docs
```

The package includes guide content and API references as markdown files in [llms.txt](https://llmstxt.org/) format, enabling AI assistants to provide accurate guidance when developing Gunshi CLI applications.

### Fallback to Entry Command

New `fallbackToEntry` option enables graceful handling of unknown subcommands:

```js
const mainCommand = {
  name: 'tool',
  args: {
    file: { type: 'string', positional: true }
  },
  run: ctx => {
    // Process file when no subcommand is provided
    console.log(`Processing ${ctx.values.file}`)
  }
}

await cli(process.argv.slice(2), mainCommand, {
  name: 'tool',
  fallbackToEntry: true, // Enable fallback
  subCommands: {
    convert: convertCommand,
    validate: validateCommand
  }
})

// Usage:
// tool convert file.txt  -> Runs convert subcommand
// tool file.txt          -> Falls back to main command
// tool unknown file.txt  -> Falls back to main command (with v0.27)
```

This feature is particularly useful for:

* Git-style CLIs where the main command has its own functionality
* Backward compatibility when adding subcommands to existing CLIs
* Creating more forgiving user experiences

### Subcommand Object Style

Subcommands can now be defined as plain objects (Record) in addition to Map, providing better organization for complex CLIs:

```js
// Define subcommands
const addCommand = {
  name: 'add',
  description: 'Add file contents to the index',
  run: ctx => console.log('Adding files...')
}

const commitCommand = {
  name: 'commit',
  description: 'Record changes to the repository',
  run: ctx => console.log('Committing...')
}

// Pass subcommands as object to CLI options
await cli(process.argv.slice(2), mainCommand, {
  name: 'git',
  version: '1.0.0',
  subCommands: {
    add: addCommand,
    commit: commitCommand
  }
})
```

### Explicit Argument Detection

New feature to detect whether arguments were explicitly provided by the user or using default values:

```js
const command = {
  name: 'deploy',
  args: {
    verbose: {
      type: 'boolean',
      default: false,
      description: 'Enable verbose output'
    },
    output: {
      type: 'string',
      default: 'output.txt',
      description: 'Output file path'
    }
  },
  run: ctx => {
    // Check if arguments were explicitly provided
    if (ctx.explicit.output) {
      console.log('Output file explicitly specified:', ctx.values.output)
    } else {
      console.log('Using default output file:', ctx.values.output)
    }

    // Useful for configuration overrides
    if (!ctx.explicit.verbose && ctx.values.verbose) {
      console.log('Verbose mode enabled by config file')
    }
  }
}
```

The `ctx.explicit` object indicates for each argument:

* `true`: The argument was explicitly provided via command line
* `false`: The argument uses a default value or is undefined

### Command Lifecycle Hooks

New hooks for fine-grained control over command execution, available in CLI options:

```js
const command = {
  name: 'backup',
  run: ctx => {
    // Main backup logic
    console.log('Running backup...')
  }
}

await cli(process.argv.slice(2), command, {
  name: 'backup-tool',
  version: '1.0.0',
  onBeforeCommand: async ctx => {
    console.log('Preparing backup...')
  },
  onAfterCommand: async (ctx, result) => {
    console.log('Backup completed!')
    if (result) console.log('Result:', result)
  },
  onErrorCommand: async (ctx, error) => {
    console.error('Backup failed:', error)
    // Custom error handling logic
  }
})
```

### Custom Rendering Control

New rendering options allow fine-grained control over how commands display their output. Each command can customize or disable specific parts of the UI:

```js
const command = {
  name: 'wizard',
  rendering: {
    // Custom header with emoji and version
    header: async ctx => `🚀 ${ctx.name} v${ctx.version}`,

    // Disable default usage (set to null)
    usage: null,

    // Custom error formatting
    validationErrors: async (ctx, error) => `❌ Error: ${error.message}`
  },
  run: ctx => {
    // Command logic
  }
}
```

This feature enables:

* **Per-command customization**: Each command can have its own UI style
* **Selective rendering**: Disable specific parts (header, usage, errors) by setting them to `null`
* **Async rendering**: Support for async functions to fetch dynamic content
* **Full context access**: Renderers receive the complete command context for flexible output generation

## ⚡ Improvement Features

### Multiple Positional Argument Usage Display

The plugin-renderer now displays multiple positional arguments more clearly in usage output:

* Required positional: `<name>`
* Multiple positional: `[<name> ...]`
* Required + multiple: `<name> [<name> ...]`

This improvement helps users understand when a command accepts multiple positional arguments.

### i18n Plugin: `registerGlobalOptionResources` Extension

New extension method for dynamically registering global option resources:

```ts
const command = defineI18n({
  name: 'app',
  run: ctx => {
    // Register custom global option descriptions
    ctx.extensions['g:i18n'].registerGlobalOptionResources('custom-option', {
      'en-US': 'Custom option description',
      'ja-JP': 'カスタムオプションの説明'
    })
  }
})
```

This enables plugins to register localized descriptions for global options dynamically.

### Type Safety Enhancements

v0.27 brings comprehensive type safety improvements to all core APIs through generic type parameters, enabling full TypeScript inference for arguments and plugin extensions.

#### Enhanced `define()` API

The `define` function now accepts type parameters for type-safe command definitions with plugin extensions:

```ts
import { define } from 'gunshi'
import logger, { pluginId as loggerId } from '@your-company/plugin-logger'
import auth, { pluginId as authId } from '@your-company/plugin-auth'

import type { LoggerExtension, PluginId as LoggerId } from '@your-company/plugin-logger'
import type { AuthExtension, PluginId as AuthId } from '@your-company/plugin-auth'

// Type-safe command with plugin extensions
const deployCommand = define<{
  extensions: Record<LoggerId, LoggerExtension> & Record<AuthId, AuthExtension>
}>({
  name: 'deploy',
  run: ctx => {
    // Plugin extensions are fully typed
    ctx.extensions[loggerId]?.log('Starting deployment...')

    if (!ctx.extensions[authId]?.isAuthenticated()) {
      throw new Error('Authentication required')
    }

    const user = ctx.extensions[authId]?.getUser()
    ctx.extensions[loggerId]?.info(`Deploying as ${user?.name}`)
  }
})
```

#### New `defineWithTypes()` API

For better type inference with plugin extensions, v0.27 introduces `defineWithTypes()` - a curried function that separates type specification from command definition:

```ts
import { defineWithTypes } from 'gunshi'

// Define your extensions type first
type MyExtensions = {
  logger: { log: (msg: string) => void }
  auth: { isAuthenticated: () => boolean; getUser: () => User }
}

// Use defineWithTypes - specify only extensions, args are inferred!
const command = defineWithTypes<{ extensions: MyExtensions }>()({
  name: 'deploy',
  args: {
    env: { type: 'string', required: true },
    force: { type: 'boolean', default: false }
  },
  run: ctx => {
    // ctx.values is automatically inferred as { env: string; force?: boolean }
    // ctx.extensions is typed as MyExtensions
    if (!ctx.extensions.auth?.isAuthenticated()) {
      throw new Error('Authentication required')
    }

    ctx.extensions.logger?.log(`Deploying to ${ctx.values.env}`)
  }
})
```

Benefits over standard `define()`:

* Cleaner syntax when specifying extensions - no need for complex generic type parameters
* Better IDE support with curried function pattern
* Arguments are automatically inferred from the definition

#### Enhanced `lazy()` API

The `lazy` function supports type parameters for lazy-loaded commands with extensions:

```ts
import { lazy } from 'gunshi'
import { pluginId as dbId } from '@your-company/plugin-database'
import { pluginId as cacheId } from '@your-company/plugin-cache'

import type { DatabaseExtension, PluginId as DbId } from '@your-company/plugin-database'
import type { CacheExtension, PluginId as CacheId } from '@your-company/plugin-cache'

// Type-safe lazy loading with plugin extensions
const heavyCommand = lazy<{
  extensions: Record<DbId, DatabaseExtension> & Record<CacheId, CacheExtension>
}>(async () => {
  // Command is loaded only when needed
  return {
    name: 'process',
    run: async ctx => {
      // Extensions are typed even in lazy-loaded commands
      const cached = await ctx.extensions[cacheId]?.get('data')
      if (cached) return cached

      const result = await ctx.extensions[dbId]?.query('SELECT * FROM data')
      await ctx.extensions[cacheId]?.set('data', result)
      return result
    }
  }
})
```

#### New `lazyWithTypes()` API

Similar to `defineWithTypes()`, the new `lazyWithTypes()` function provides better type inference for lazy-loaded commands with extensions:

```ts
import { lazyWithTypes } from 'gunshi'

type BuildExtensions = {
  logger: { log: (msg: string) => void }
  metrics: { track: (event: string) => void }
}

// Define args separately for reusability
const buildArgs = {
  target: { type: 'enum', required: true, choices: ['dev', 'prod'] },
  minify: { type: 'boolean', default: false }
} as const

// Use lazyWithTypes with both args and extensions
const buildCommand = lazyWithTypes<{
  args: typeof buildArgs
  extensions: BuildExtensions
}>()(
  async () => {
    // Heavy dependencies loaded only when needed
    const { buildProject } = await import('./heavy-build-utils')

    return async ctx => {
      // ctx.values inferred from args
      const { target, minify } = ctx.values

      // Extensions fully typed
      ctx.extensions.logger?.log(`Building for ${target}...`)
      ctx.extensions.metrics?.track('build.started')

      await buildProject({ target, minify })
    }
  },
  {
    name: 'build',
    description: 'Build the project',
    args: buildArgs
  }
)
```

Benefits:

* Type-safe lazy loading with plugin extensions
* Separates type declaration from implementation
* Supports both args and extensions type parameters
* Maintains all benefits of lazy loading (performance, code splitting)

#### Enhanced `cli()` API

The `cli` function accepts type parameters for the entire CLI application's extensions:

```ts
import { cli } from 'gunshi'
import i18n, { pluginId as i18nId } from '@gunshi/plugin-i18n'
import metrics, { pluginId as metricsId } from '@your-company/plugin-metrics'

import type { I18nExtension, PluginId as I18nId } from '@gunshi/plugin-i18n'
import type { MetricsExtension, PluginId as MetricsId } from '@your-company/plugin-metrics'

// Type-safe CLI with multiple plugin extensions
await cli<{ extensions: Record<I18nId, I18nExtension> & Record<MetricsId, MetricsExtension> }>(
  process.argv.slice(2),
  async ctx => {
    // All plugin extensions are available and typed
    const greeting = ctx.extensions[i18nId]?.translate('welcome')
    console.log(greeting)

    // Track CLI usage
    ctx.extensions[metricsId]?.track('cli.started', {
      command: ctx.name,
      locale: ctx.extensions[i18nId]?.locale.toString()
    })
  },
  {
    name: 'my-cli',
    plugins: [i18n(), metrics()]
  }
)
```

These type safety improvements ensure that:

* Command arguments are validated at compile time
* Plugin extensions are properly typed and accessible
* Typos and incorrect property access are caught before runtime
* IDE autocompletion works seamlessly across your CLI application

## 💥 Breaking Changes

### Internationalization migration

The built-in i18n support in CLI options has been moved to the official i18n plugin:

**Before (v0.26):**

```js
import { cli } from 'gunshi'

const command = {
  name: 'app',
  resource: async ctx => {
    // Return translations based on locale
    if (ctx.locale.toString() === 'ja-JP') {
      return { greeting: 'こんにちは' }
    }
    return { greeting: 'Hello' }
  },
  run: ctx => {
    console.log(ctx.translate('greeting'))
  }
}

// locale and translationAdapterFactory were in CLI options
await cli(process.argv.slice(2), command, {
  name: 'my-app',
  version: '1.0.0',
  locale: new Intl.Locale('en-US'),
  translationAdapterFactory: customAdapter
})
```

**After (v0.27):**

```ts
import { cli } from 'gunshi'
import i18n, { defineI18nWithTypes, pluginId as i18nId } from '@gunshi/plugin-i18n'
import type { I18nExtension, PluginId as I18nPluginId } from '@gunshi/plugin-i18n'

// Type-safe command with i18n plugin extension
const command = defineI18nWithTypes<{ extensions: Record<I18nPluginId, I18nExtension> }>()({
  name: 'app',
  // resource function is still used with i18n plugin
  resource: locale => {
    if (locale.toString() === 'ja-JP') {
      return { greeting: 'こんにちは' }
    }
    return { greeting: 'Hello' }
  },
  run: ctx => {
    // Use the translate() function from i18n plugin extension
    console.log(ctx.extensions[i18nId].translate('greeting'))
  }
})

// locale and translationAdapterFactory removed from CLI options
await cli(process.argv.slice(2), command, {
  name: 'my-app',
  version: '1.0.0',
  plugins: [
    i18n({
      locale: 'en-US', // Moved from CLI options
      translationAdapterFactory: customAdapter // Moved from CLI options
    })
  ]
})
```

**Migration steps:**

1. Install the i18n plugin: `npm install --save @gunshi/plugin-i18n`
2. Import the plugin and its ID: `import i18n, { pluginId as i18nId } from '@gunshi/plugin-i18n'`
3. Move `locale` from CLI options to i18n plugin options
4. Move `translationAdapterFactory` from CLI options to i18n plugin options
5. Change `ctx.translate()` to `ctx.extensions[i18nId].translate()`
6. Keep using `resource` function in commands

**Additional i18n Resources and Helpers:**

The i18n plugin comes with additional packages and helper functions to simplify internationalization:

* `@gunshi/resources`: Pre-built localization resources for common CLI terms

  ```js
  import resources from '@gunshi/resources'

  // Use with i18n plugin
  i18n({
    locale: 'en-US',
    builtinResources: resources
  })
  ```

* **Helper Functions**: Type-safe command definition with i18n

  ```js
  import { defineI18n, withI18nResource } from '@gunshi/plugin-i18n'

  // Define new command with i18n support
  const command = defineI18n({
    name: 'deploy',
    resource: locale => ({/* translations */}),
    run: ctx => {
      /* command logic */
    }
  })

  // Add i18n to existing command
  const enhancedCommand = withI18nResource(existingCommand, {
    resource: locale => ({/* translations */})
  })
  ```

* **Key Resolution Helpers**: Proper namespace management

  ```js
  import { resolveKey } from '@gunshi/plugin-i18n'

  // In subcommands, use `resolveKey` for proper namespacing
  run: ctx => {
    const key = resolveKey('customMessage', ctx.name)
    const message = ctx.extensions[i18nId].translate(key)
  }
  ```

## 📚 Documentation

### New Plugin Guides

* **Plugin Ecosystem Guide**: Comprehensive introduction to the plugin system
* **Context Extensions Guide**: Learn how to leverage plugin extensions
* **Plugin Development Guide**: Step-by-step guide for creating custom plugins

### Updated API Reference

* New plugin-related interfaces: `PluginOptions`, `PluginWithExtension`, `PluginWithoutExtension`
* Enhanced type definitions: `GunshiParams`, `CommandContextExtension`
* Rendering options: `RenderingOptions`, `RendererDecorator`

### Example Projects

New playground examples demonstrating:

* Plugin usage patterns
* Context extension scenarios
* Advanced type safety with plugins

## 🧑‍🤝‍🧑 Contributors

We'd like to thank all the contributors who made this release possible:

* [@kazupon](https://github.com/kazupon) - Core maintainer, plugin system architect, i18n extraction, lifecycle hooks
* [@yukukotani](https://github.com/yukukotani) - Fallback to entry command feature ([#291](https://github.com/kazupon/gunshi/pull/291))
* [@sushichan044](https://github.com/sushichan044) - Explicit argument detection feature ([#232](https://github.com/kazupon/gunshi/pull/232))
* [@43081j](https://github.com/43081j) - Exposed `Plugin` type ([#159](https://github.com/kazupon/gunshi/pull/159))
* [@theoephraim](https://github.com/theoephraim) - Documentation improvements ([#249](https://github.com/kazupon/gunshi/pull/249))
* [@lukekarrys](https://github.com/lukekarrys) - Documentation updates ([#228](https://github.com/kazupon/gunshi/pull/228))
* [@BobbieGoede](https://github.com/BobbieGoede) - Fixed FUNDING.yml ([#303](https://github.com/kazupon/gunshi/pull/303))
* [@ryoppippi](https://github.com/ryoppippi) - Docs init CLI feature ([#422](https://github.com/kazupon/gunshi/pull/422))
* [@ota-meshi](https://github.com/ota-meshi) - Multiple positional argument usage display improvement ([#432](https://github.com/kazupon/gunshi/pull/432))

Special thanks to the community for feedback and bug reports that helped shape v0.27!

## 💖 Credits

The completion plugin is powered by:

* [`@bomb.sh/tab`](https://github.com/bombshell-dev/tab) by [Bombshell](https://github.com/bombshell-dev) - Shell completion library that powers our tab completion functionality

---

---
url: /api.md
---
# API Documentation

## Modules

| Module | Description |
| ------ | ------ |
| [agent](/api/agent/index.md) | The entry point for AI agent detection utilities. |
| [combinators](/api/combinators/index.md) | Parser combinator entry point. |
| [context](/api/context/index.md) | The entry for gunshi context. This module is exported for the purpose of testing the command. |
| [default](/api/default/index.md) | gunshi cli entry point. |
| [definition](/api/definition/index.md) | The entry for gunshi command definition. |
| [generator](/api/generator/index.md) | The entry for usage generator. |
| [plugin](/api/plugin/index.md) | The entry point for Gunshi plugin module. |
| [renderer](/api/renderer/index.md) | The entry point for Gunshi renderer. |