Skip to main content

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

Agent-First Design

Built-in Skills and MCP support means agents discover your CLI automatically. No manual tool definitions required.

Type-Safe APIs

Full type inference from Zod schemas to run callbacks. Agents get immediate feedback on type mismatches.

Token Efficient

TOON output format uses up to 60% fewer tokens than JSON. Save on API costs across every session.

Well-Formed I/O

Schemas for arguments, options, environment variables, and output eliminate guessing.

​
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: 
# 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× │
└─────────────────┴────────────┴──────────────────┴─────────┴───────────────┘
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.

​
Call-to-Actions

Guide agents to the next relevant command without extra prompting: 
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

MCP

  • Injects all tool schemas into every turn
  • High token overhead at session start
  • JSON output only
  • Requires stdio server setup

incur

  • On-demand skill loading by command group
  • Minimal session start overhead
  • TOON output (60% fewer tokens)
  • Built-in MCP support via mcp add

​
vs. Traditional Skill Files

Skill Files

  • Single monolithic file per tool
  • Loaded entirely on first use
  • Manual skill file creation
  • No structured output

incur

  • Split by command group (configurable depth)
  • Load only relevant commands
  • Auto-generated via skills add
  • Structured output envelopes

​
Who Should Use incur?

CLI Developers

Building tools that need to work for both humans and AI agents with minimal friction.

Agent Developers

Creating specialized tools for agents where token efficiency and discoverability matter.

Teams

Internal tooling teams who want agents to discover and use CLIs without manual integration.

Library Authors

Package maintainers who want to expose APIs as both CLIs and agent-callable tools.

​
Key Features

Three functions: Cli.create(), .command(), .serve(). Everything else (parsing, help, validation, output formatting, agent discovery) is automatic.
Type safety flows from Zod schemas to run callbacks with zero manual annotations. Agents building CLIs get immediate feedback.
Token-efficient format that’s as readable as YAML but with no quoting, no braces, and no redundant syntax.
Every CLI gets --format, --json, --verbose, --help, --version, and --llms for free.
Composable before/after hooks with typed dependency injection via cli.use().
Mount any HTTP server as a CLI command. Pass an OpenAPI spec to generate typed subcommands.

​
Next Steps

Installation

Install incur and verify your setup

Quickstart

Build your first CLI in 5 minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us