> ## 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.

# Introduction

> Build CLIs that work for AI agents and humans

## What is incur?

incur is a TypeScript framework for building CLIs that work seamlessly for both AI agents and humans. It provides type-safe command definitions with Zod schemas, automatic agent discovery via Skills and MCP, and token-efficient output formats.

<CardGroup cols={2}>
  <Card title="Agent-First Design" icon="robot">
    Built-in Skills and MCP support means agents discover your CLI automatically. No manual tool definitions required.
  </Card>

  <Card title="Type-Safe APIs" icon="shield-check">
    Full type inference from Zod schemas to run callbacks. Agents get immediate feedback on type mismatches.
  </Card>

  <Card title="Token Efficient" icon="gauge-high">
    TOON output format uses up to 60% fewer tokens than JSON. Save on API costs across every session.
  </Card>

  <Card title="Well-Formed I/O" icon="input-text">
    Schemas for arguments, options, environment variables, and output eliminate guessing.
  </Card>
</CardGroup>

## Why incur?

Most CLIs expose tools via MCP or monolithic skill files, leading to high token costs and poor discoverability. incur solves this with:

### Agent Discovery

Three built-in mechanisms for agents to find your CLI:

```bash theme={null}
# Auto-generate and install agent skill files (recommended)
my-cli skills add

# Register as an MCP server
my-cli mcp add

# Output machine-readable manifest
my-cli --llms
```

### Session Savings

incur combines on-demand skill loading with TOON output to cut token usage across the entire session:

```
┌─────────────────┬────────────┬──────────────────┬─────────┬───────────────┐
│                 │ MCP + JSON │ One Skill + JSON │   incur │ vs. incur     │
├─────────────────┼────────────┼──────────────────┼─────────┼───────────────┤
│ Session start   │      6,747 │              624 │     805 │         ↓8.4× │
│ Discovery       │          0 │           11,489 │     387 │        ↓29.7× │
│ Invocation (×5) │        110 │               65 │      65 │         ↓1.7× │
│ Response (×5)   │     10,940 │           10,800 │   5,790 │         ↓1.9× │
├─────────────────┼────────────┼──────────────────┼─────────┼───────────────┤
│ Cost            │    $0.0325 │          $0.0410 │ $0.0131 │         ↓3.1× │
└─────────────────┴────────────┴──────────────────┴─────────┴───────────────┘
```

<Note>
  Modeled on a 20-command CLI with verbose output. MCP injects all tool schemas into every turn; skills load frontmatter then full files on demand; incur splits by command group.
</Note>

### Call-to-Actions

Guide agents to the next relevant command without extra prompting:

```typescript theme={null}
cli.command('list', {
  args: z.object({ state: z.enum(['open', 'closed']).default('open') }),
  run(c) {
    const items = [{ id: 1, title: 'Fix bug' }]
    return c.ok(
      { items },
      {
        cta: {
          commands: [
            { command: 'get 1', description: 'View item' },
            { command: 'list', args: { state: 'closed' }, description: 'View closed' },
          ],
        },
      },
    )
  },
})
```

## Comparison with Alternatives

### vs. MCP

<CardGroup cols={2}>
  <Card title="MCP">
    * Injects all tool schemas into every turn
    * High token overhead at session start
    * JSON output only
    * Requires stdio server setup
  </Card>

  <Card title="incur">
    * On-demand skill loading by command group
    * Minimal session start overhead
    * TOON output (60% fewer tokens)
    * Built-in MCP support via `mcp add`
  </Card>
</CardGroup>

### vs. Traditional Skill Files

<CardGroup cols={2}>
  <Card title="Skill Files">
    * Single monolithic file per tool
    * Loaded entirely on first use
    * Manual skill file creation
    * No structured output
  </Card>

  <Card title="incur">
    * Split by command group (configurable depth)
    * Load only relevant commands
    * Auto-generated via `skills add`
    * Structured output envelopes
  </Card>
</CardGroup>

## Who Should Use incur?

<CardGroup cols={2}>
  <Card title="CLI Developers" icon="terminal">
    Building tools that need to work for both humans and AI agents with minimal friction.
  </Card>

  <Card title="Agent Developers" icon="code">
    Creating specialized tools for agents where token efficiency and discoverability matter.
  </Card>

  <Card title="Teams" icon="users">
    Internal tooling teams who want agents to discover and use CLIs without manual integration.
  </Card>

  <Card title="Library Authors" icon="book">
    Package maintainers who want to expose APIs as both CLIs and agent-callable tools.
  </Card>
</CardGroup>

## Key Features

<AccordionGroup>
  <Accordion title="Light API Surface">
    Three functions: `Cli.create()`, `.command()`, `.serve()`. Everything else (parsing, help, validation, output formatting, agent discovery) is automatic.
  </Accordion>

  <Accordion title="Inferred Types">
    Type safety flows from Zod schemas to run callbacks with zero manual annotations. Agents building CLIs get immediate feedback.
  </Accordion>

  <Accordion title="TOON Output">
    Token-efficient format that's as readable as YAML but with no quoting, no braces, and no redundant syntax.
  </Accordion>

  <Accordion title="Global Options">
    Every CLI gets `--format`, `--json`, `--verbose`, `--help`, `--version`, and `--llms` for free.
  </Accordion>

  <Accordion title="Middleware">
    Composable before/after hooks with typed dependency injection via `cli.use()`.
  </Accordion>

  <Accordion title="OpenAPI Integration">
    Mount any HTTP server as a CLI command. Pass an OpenAPI spec to generate typed subcommands.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Install incur and verify your setup
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Build your first CLI in 5 minutes
  </Card>
</CardGroup>