> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wevm/incur/llms.txt
> Use this file to discover all available pages before exploring further.

# Cli

> Core CLI creation and management API

## Cli.create()

Creates a new CLI application. Can be used to create a single-command CLI with a root handler, or a router CLI that registers subcommands.

### Signature

```typescript theme={null}
function create<
  const args extends z.ZodObject<any> | undefined = undefined,
  const env extends z.ZodObject<any> | undefined = undefined,
  const opts extends z.ZodObject<any> | undefined = undefined,
  const output extends z.ZodType | undefined = undefined,
  const vars extends z.ZodObject<any> | undefined = undefined,
>(
  name: string,
  definition?: create.Options<args, env, opts, output, vars>
): Cli<{}, vars, env>
```

### Parameters

<ParamField path="name" type="string" required>
  The name of the CLI application. Used as the primary command name.
</ParamField>

<ParamField path="definition" type="create.Options">
  Configuration options for the CLI. Omit `run` for a router CLI that only registers subcommands, or include `run` to create a leaf CLI with a root command handler.

  <Expandable title="create.Options">
    <ParamField path="args" type="z.ZodObject<any>">
      Zod schema for positional arguments. Keys define argument names, schemas define types and validation.
    </ParamField>

    <ParamField path="description" type="string">
      A short description of what the CLI does. Shown in help text and agent discovery.
    </ParamField>

    <ParamField path="env" type="z.ZodObject<any>">
      Zod schema for environment variables. Keys are the variable names (e.g. `NPM_TOKEN`). Parsed before middleware runs.
    </ParamField>

    <ParamField path="options" type="z.ZodObject<any>">
      Zod schema for named options/flags. Keys define flag names, schemas define types and defaults.
    </ParamField>

    <ParamField path="output" type="z.ZodType">
      Zod schema for the return value. Used for output validation and type inference.
    </ParamField>

    <ParamField path="vars" type="z.ZodObject<any>">
      Zod schema for middleware variables. Keys define variable names, schemas define types and defaults.
    </ParamField>

    <ParamField path="alias" type="Record<string, string>">
      Map of option names to single-char aliases (e.g. `{ verbose: 'v' }`).
    </ParamField>

    <ParamField path="aliases" type="string[]">
      Alternative binary names for this CLI (e.g. shorter aliases in package.json `bin`). Shell completions are registered for all names.
    </ParamField>

    <ParamField path="examples" type="Example[]">
      Usage examples for this command. Shown in help output.
    </ParamField>

    <ParamField path="format" type="'toon' | 'json' | 'yaml' | 'md'">
      Default output format. Can be overridden by `--format` or `--json` flags.
    </ParamField>

    <ParamField path="outputPolicy" type="'all' | 'agent-only'" default="'all'">
      Controls when output data is displayed:

      * `'all'` — displays to both humans and agents
      * `'agent-only'` — suppresses data output in human/TTY mode while still returning it to agents

      Inherited by child commands when set on a group or root CLI.
    </ParamField>

    <ParamField path="run" type="(context) => InferReturn<output> | Promise<InferReturn<output>> | AsyncGenerator">
      The root command handler. When provided, creates a leaf CLI with a root command. When omitted, creates a router CLI that only registers subcommands.

      <Expandable title="Context">
        <ResponseField name="agent" type="boolean">
          Whether the consumer is an agent (stdout is not a TTY).
        </ResponseField>

        <ResponseField name="args" type="InferOutput<args>">
          Positional arguments parsed according to the args schema.
        </ResponseField>

        <ResponseField name="name" type="string">
          The CLI name.
        </ResponseField>

        <ResponseField name="env" type="InferOutput<env>">
          Parsed environment variables according to the env schema.
        </ResponseField>

        <ResponseField name="options" type="InferOutput<options>">
          Named options/flags parsed according to the options schema.
        </ResponseField>

        <ResponseField name="var" type="InferVars<vars>">
          Variables set by middleware. Typed according to the vars schema.
        </ResponseField>

        <ResponseField name="ok" type="(data, meta?) => never">
          Return a success result with optional metadata (e.g. CTAs). Calling this short-circuits execution.
        </ResponseField>

        <ResponseField name="error" type="(options) => never">
          Return an error result with optional CTAs. Calling this short-circuits execution.
        </ResponseField>
      </Expandable>
    </ParamField>

    <ParamField path="usage" type="Usage[]">
      Alternative usage patterns shown in help output.
    </ParamField>

    <ParamField path="version" type="string">
      The CLI version string. Displayed with `--version` flag.
    </ParamField>

    <ParamField path="mcp" type="object">
      Options for the built-in `mcp add` command.

      <Expandable title="MCP Options">
        <ParamField path="agents" type="string[]">
          Target specific agents by default (e.g. `['claude-code', 'cursor']`).
        </ParamField>

        <ParamField path="command" type="string">
          Override the command agents will run to start the MCP server. Auto-detected if omitted.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="sync" type="object">
      Options for the built-in `skills add` command.

      <Expandable title="Sync Options">
        <ParamField path="cwd" type="string">
          Working directory for resolving `include` globs. Pass `import.meta.dirname` when running from a bin entry. Defaults to `process.cwd()`.
        </ParamField>

        <ParamField path="depth" type="number" default="1">
          Default grouping depth for skill files. Overridden by `--depth`.
        </ParamField>

        <ParamField path="include" type="string[]">
          Glob patterns for directories containing SKILL.md files to include (e.g. `"skills/*"`, `"my-skill"`).
        </ParamField>

        <ParamField path="suggestions" type="string[]">
          Example prompts shown after sync to help users get started.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Return Type

<ResponseField name="Cli" type="Cli<commands, vars, env>">
  A CLI application instance. Also used as a command group when mounted on a parent CLI.
</ResponseField>

### Examples

#### Create a simple router CLI

```typescript theme={null}
import { Cli } from 'incur'

const cli = Cli.create('my-cli', {
  version: '1.0.0',
  description: 'My awesome CLI'
})

cli.command('greet', {
  args: z.object({ name: z.string() }),
  run(c) {
    return { message: `Hello ${c.args.name}!` }
  }
})

cli.serve()
```

#### Create a CLI with root command

```typescript theme={null}
const cli = Cli.create('my-cli', {
  version: '1.0.0',
  args: z.object({ path: z.string() }),
  run(c) {
    return { path: c.args.path }
  }
})
```

#### Create CLI with environment variables

```typescript theme={null}
const cli = Cli.create('deploy', {
  env: z.object({
    API_TOKEN: z.string(),
    API_URL: z.string().default('https://api.example.com')
  }),
  run(c) {
    // c.env.API_TOKEN is typed and validated
    return { url: c.env.API_URL }
  }
})
```

## Cli Type

The CLI instance returned by `Cli.create()`. Also used as a command group when mounted on a parent CLI.

### Properties

<ResponseField name="name" type="string">
  The name of the CLI application.
</ResponseField>

<ResponseField name="description" type="string | undefined">
  A short description of the CLI.
</ResponseField>

<ResponseField name="vars" type="z.ZodObject<any> | undefined">
  The vars schema, if declared. Use `typeof cli.vars` with `middleware<vars, env>()` for typed middleware.
</ResponseField>

<ResponseField name="env" type="z.ZodObject<any> | undefined">
  The env schema, if declared. Use `typeof cli.env` with `middleware<vars, env>()` for typed middleware.
</ResponseField>

### Methods

#### command()

Registers a root command or mounts a sub-CLI as a command group. Returns the CLI instance for chaining.

```typescript theme={null}
command<
  const name extends string,
  const args extends z.ZodObject<any> | undefined = undefined,
  const cmdEnv extends z.ZodObject<any> | undefined = undefined,
  const options extends z.ZodObject<any> | undefined = undefined,
  const output extends z.ZodType | undefined = undefined,
>(
  name: name,
  definition: CommandDefinition<args, cmdEnv, options, output, vars, env>
): Cli<...>
```

**Parameters:**

<ParamField path="name" type="string" required>
  The command name. Used to invoke the command.
</ParamField>

<ParamField path="definition" type="CommandDefinition">
  The command definition. See [Commands](/api/commands) for details.
</ParamField>

**Mounting a sub-CLI:**

```typescript theme={null}
command<const name extends string>(
  cli: Cli & { name: name }
): Cli<...>
```

**Parameters:**

<ParamField path="cli" type="Cli">
  A sub-CLI instance to mount as a command group. All subcommands will be namespaced under this CLI's name.
</ParamField>

**Examples:**

```typescript theme={null}
// Register a command
cli.command('greet', {
  args: z.object({ name: z.string() }),
  run(c) {
    return { message: `Hello ${c.args.name}!` }
  }
})

// Mount a sub-CLI as a command group
const pr = Cli.create('pr', { description: 'PR management' })
pr.command('list', {
  run() {
    return { items: [] }
  }
})
cli.command(pr)
// Now available as: my-cli pr list
```

#### serve()

Parses argv, runs the matched command, and writes the output envelope to stdout.

```typescript theme={null}
serve(argv?: string[], options?: serve.Options): Promise<void>
```

**Parameters:**

<ParamField path="argv" type="string[]" default="process.argv.slice(2)">
  Command-line arguments to parse. Defaults to process arguments.
</ParamField>

<ParamField path="options" type="serve.Options">
  Options for serve, primarily used for testing.

  <Expandable title="serve.Options">
    <ParamField path="env" type="Record<string, string | undefined>">
      Override environment variable source. Defaults to `process.env`.
    </ParamField>

    <ParamField path="exit" type="(code: number) => void">
      Override exit handler. Defaults to `process.exit`.
    </ParamField>

    <ParamField path="stdout" type="(s: string) => void">
      Override stdout writer. Defaults to `process.stdout.write`.
    </ParamField>
  </Expandable>
</ParamField>

**Example:**

```typescript theme={null}
// In your bin entry file
#!/usr/bin/env node
import { cli } from './cli.js'

cli.serve()
```

#### use()

Registers middleware that runs around every command.

```typescript theme={null}
use(handler: MiddlewareHandler<vars, env>): Cli<commands, vars, env>
```

**Parameters:**

<ParamField path="handler" type="MiddlewareHandler">
  The middleware handler function. See [Middleware](/api/middleware) for details.
</ParamField>

**Example:**

```typescript theme={null}
cli.use(async (c, next) => {
  console.log('Before command')
  await next()
  console.log('After command')
})
```