Incur

https://github.com/wevm/incur
Admin
Incur is a modern CLI framework that enables agents to discover and use your commands with built-in...
Tokens:131,639
Snippets:804
Trust Score:8
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Register a command with args, options, aliases, and examples

Source: https://github.com/wevm/incur/blob/main/SKILL.md

Registers a command with args, options, aliases, output schema, and usage examples. The 'install' command demonstrates optional args, boolean options with aliases, and a typed output.

```ts
cli.command('install', {
  description: 'Install a package',
  args: z.object({
    package: z.string().optional().describe('Package name'),
  }),
  options: z.object({
    saveDev: z.boolean().optional().describe('Save as dev dependency'),
    global: z.boolean().optional().describe('Install globally'),
  }),
  alias: { saveDev: 'D', global: 'g' },
  output: z.object({
    added: z.number(),
    packages: z.number(),
  }),
  examples: [
    { args: { package: 'express' }, description: 'Install a package' },
    {
      args: { package: 'vitest' },
      options: { saveDev: true },
      description: 'Install as dev dependency',
    },
  ],
  run({ args, options }) {
    return { added: 1, packages: 451 }
  },
})
```

--------------------------------

### complete() usage example

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/completions.md

Example call to `Completions.complete` with a command map, root command, argv words, and cursor index. The comment shows the expected result: a candidate for the `install` subcommand with its description.

```ts
const candidates = Completions.complete(commands, rootCommand, ['my-cli', 'ins'], 1)
// [{ value: 'install', description: 'Install a package' }]

```

--------------------------------

### Quick start: create a single-command CLI with Cli.create

Source: https://github.com/wevm/incur/blob/main/SKILL.md

Quick start example: creates a single-command CLI named 'greet' that takes a 'name' argument and returns a message. The shell command shows the expected output when running 'greet world'.

```ts
import { Cli, z } from 'incur'

const cli = Cli.create('greet', {
  description: 'A greeting CLI',
  args: z.object({
    name: z.string().describe('Name to greet'),
  }),
  run({ args }) {
    return { message: `hello ${args.name}` }
  },
})

cli.serve()
```

```sh
greet world
# → message: hello world
```

--------------------------------

### Define install command with args and options

Source: https://github.com/wevm/incur/blob/main/SKILL.md

Define a command with arguments and options using Zod schemas. This example is used to demonstrate `--schema` output.

```ts
cli.command('install', {
  description: 'Install a package',
  args: z.object({
    package: z.string().describe('Package name'),
  }),
  options: z.object({
    saveDev: z.boolean().optional().describe('Save as dev dependency'),
  }),
  run({ args }) {
    return { added: 1 }
  },
})
```

--------------------------------

### Mcp.serve() example

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/mcp.md

Example usage of Mcp.serve() to start a stdio MCP server. It passes the CLI's command map and sets tool discovery to 'direct'.

```ts
await Mcp.serve('my-cli', '1.0.0', Cli.toCommands.get(cli)!, {
  tools: { discovery: 'direct' },
})
```

--------------------------------

### sync() usage example

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/sync-skills.md

Shows how to call SyncSkills.sync() with options for depth, global install, include globs, and suggestions. The result's skills names are logged.

```typescript
const result = await SyncSkills.sync('my-cli', commands, {
  depth: 1,
  global: true,
  include: ['skills/*'],
  suggestions: ['build a cli with incur'],
})
console.log(result.skills.map((s) => s.name))
```

--------------------------------

### Example: Help.formatCommand with options

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/help.md

Example usage of Help.formatCommand with a command name and options object. Demonstrates passing description, args schema, options schema, examples, and hint. The resulting text is stored in the variable 'text'.

```ts
const text = Help.formatCommand('my-cli deploy', {
  description: 'Deploy the app',
  args: z.object({ env: z.enum(['staging', 'production']) }),
  options: z.object({ force: z.boolean().optional() }),
  examples: [{ command: '--force', description: 'Force deploy' }],
  hint: 'Requires DEPLOY_TOKEN.',
})
```

--------------------------------

### cli.fetch host examples

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/cli.md

Examples of using cli.fetch with different hosts: Bun, Deno, Cloudflare Workers, and Hono.

```ts
Bun.serve(cli)            // Bun
Deno.serve(cli.fetch)     // Deno
export default cli        // Cloudflare Workers
app.use((c) => cli.fetch(c.req.raw)) // Hono
```

--------------------------------

### Full CLI example with `Cli.create` and `cli.command`

Source: https://github.com/wevm/incur/blob/main/SKILL.md

Complete example of creating a CLI with `Cli.create`, defining commands with `cli.command`, and serving with `cli.serve()`. It shows how to define args, options, aliases, output schemas, examples, and run functions. Always `export default cli` so that `incur gen` can import it and generate types.

```ts
import { Cli, z } from 'incur'

const cli = Cli.create('npm', {
  version: '10.9.2',
  description: 'The package manager for JavaScript.',
  sync: {
    suggestions: ['install react as a dependency', 'check for outdated packages'],
  },
})

cli.command('install', {
  description: 'Install a package',
  args: z.object({
    package: z.string().optional().describe('Package name to install'),
  }),
  options: z.object({
    saveDev: z.boolean().optional().describe('Save as dev dependency'),
    global: z.boolean().optional().describe('Install globally'),
  }),
  alias: { saveDev: 'D', global: 'g' },
  output: z.object({
    added: z.number().describe('Number of packages added'),
    packages: z.number().describe('Total packages'),
  }),
  examples: [
    { args: { package: 'express' }, description: 'Install a package' },
    {
      args: { package: 'vitest' },
      options: { saveDev: true },
      description: 'Install as dev dependency',
    },
  ],
  run({ args }) {
    if (!args.package) return { added: 120, packages: 450 }
    return { added: 1, packages: 451 }
  },
})

cli.command('outdated', {
  description: 'Check for outdated packages',
  options: z.object({
    global: z.boolean().describe('Check global packages'),
  }),
  alias: { global: 'g' },
  output: z.object({
    packages: z.array(
      z.object({
        name: z.string(),
        current: z.string(),
        wanted: z.string(),
        latest: z.string(),
      }),
    ),
  }),
  run() {
    return {
      packages: [{ name: 'express', current: '4.18.0', wanted: '4.21.2', latest: '4.21.2' }],
    }
  },
})

cli.serve()

export default cli
```

--------------------------------

### Install standalone binary via curl

Source: https://github.com/wevm/incur/blob/main/README.md

After the release is published, users can install without a package manager by piping the install script to `sh`. Replace `<org>` and `<repo>` with the actual GitHub organization and repository.

```sh
curl -fsSL https://github.com/<org>/<repo>/releases/latest/download/install.sh | sh
```

--------------------------------

### HTTP to CLI mapping examples

Source: https://github.com/wevm/incur/blob/main/README.md

Shows how HTTP requests map to CLI invocations: path segments become commands and positional args, query params become options (GET), and JSON body becomes options (POST).

```text
GET  /users?limit=5    → my-cli users --limit 5
GET  /users/42         → my-cli users 42
POST /users { "name": "Bob" }  → my-cli users --name Bob
```

--------------------------------

### Using Binary.github() with Cli.create()

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/binary.md

Example of using `Binary.github()` to configure the update provider for a CLI created with `Cli.create()`. The `repository` option must be in `owner/name` form. This example is from the `github()` section.

```ts
import { Binary, Cli } from 'incur'

const cli = Cli.create('my-cli', {
  update: Binary.github({ repository: 'example/my-cli' }),
})
```

--------------------------------

### formatRoot() usage example

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/help.md

Example call to Help.formatRoot() with options for description, commands, and root flag. Produces help text for a CLI named 'my-cli'.

```typescript
const text = Help.formatRoot('my-cli', {
  description: 'My CLI',
  commands: [{ name: 'status', description: 'Show repo status' }],
  root: true,
})
```

--------------------------------

### Example: Parser.parseEnv()

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/parser.md

Example usage of Parser.parseEnv() with a Zod schema for environment variables and process.env as the source. Demonstrates optional and required fields.

```ts
const env = Parser.parseEnv(
  z.object({ NPM_TOKEN: z.string().min(1), DEBUG: z.boolean().optional() }),
  process.env,
)
```

--------------------------------

### Define CLI command with typed examples

Source: https://github.com/wevm/incur/blob/main/SKILL.md

Define a CLI command with typed arguments and options using Zod schemas. The `examples` array provides usage examples that appear in `--help` output and generated skill files.

```ts
cli.command('deploy', {
  args: z.object({ env: z.enum(['staging', 'production']) }),
  options: z.object({ force: z.boolean().optional() }),
  examples: [
    { args: { env: 'staging' }, description: 'Deploy to staging' },
    { args: { env: 'production' }, options: { force: true }, description: 'Force deploy to prod' },
  ],
  run({ args }) {
    return { deployed: args.env }
  },
})
```

--------------------------------

### fromCli usage example

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/openapi.md

Example call to fromCli with a title and version. The CLI instance must have registered commands.

```typescript
const spec = Openapi.fromCli(cli, { title: 'my-cli', version: '1.0.0' })
```

--------------------------------

### MCP over HTTP request examples

Source: https://github.com/wevm/incur/blob/main/README.md

Example MCP requests to the `/mcp` endpoint exposed by the fetch handler. Shows the progressive discovery flow: initialize, tools/list, then tools/call with different tool names.

```text
POST /mcp  { "jsonrpc": "2.0", "method": "initialize", ... }
POST /mcp  { "jsonrpc": "2.0", "method": "tools/list", ... }
POST /mcp  { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "search_tools", ... } }
POST /mcp  { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "get_tool_details", ... } }
POST /mcp  { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "call_read_tool", ... } }
```

--------------------------------

### parseArgv() example with output

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/fetch.md

Example usage of Fetch.parseArgv with a sample argv array. The output shows the resulting FetchInput object with path, method, body, query, and headers properties.

```ts
const input = Fetch.parseArgv(['users', '-X', 'POST', '-d', '{"name":"Bob"}', '--limit', '5'])
// { path: '/users', method: 'POST', body: '{"name":"Bob"}', query: { limit: '5' }, headers: Headers{} }
```

--------------------------------

### Build installers with default repository

Source: https://github.com/wevm/incur/blob/main/docs/binaries.md

Builds all default targets and generates Unix and Windows installers. Incur reads the public GitHub repository from the nearest package.json repository field.

```sh
pnpm exec incur build ./src/bin.ts --installer
```

--------------------------------

### Example: registering an MCP server with SyncMcp.register()

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/sync-mcp.md

Example usage of `SyncMcp.register()`. Registers the CLI with the given package and version for the specified agents, including Amp which only skips `add-mcp`.

```ts
const result = await SyncMcp.register('my-cli', {
  cli: 'my-cli',
  package: '@example/my-cli',
  version: '1.0.0',
  agents: ['claude-code', 'amp'],
})
```

--------------------------------

### fromCli() usage example

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/typegen.md

Calls `Typegen.fromCli` to get the declaration string and writes it to a file using `fs.writeFile`.

```typescript
const dts = Typegen.fromCli(cli)
await fs.writeFile('incur.generated.ts', dts)
```

--------------------------------

### Create a CLI with create, command, and serve

Source: https://github.com/wevm/incur/blob/main/README.md

Build a CLI with the three core functions: `create`, `command`, and `serve`. This example defines a sub-command group, registers commands, mounts the group, and serves the CLI. The help output shows the generated command list.

```ts
import { Cli, z } from 'incur'

// Define sub-command groups
const db = Cli.create('db', { description: 'Database commands' }).command('migrate', {
  description: 'Run migrations',
  run: () => ({ migrated: true }),
})

// Create the root CLI
Cli.create('tool', { description: 'A tool' })
  // Register commands
  .command('run', { description: 'Run a task', run: () => ({ ok: true }) })
  // Mount sub-command groups
  .command(db)
  // Serve the CLI
  .serve()
```

```sh
$ tool --help
# Usage: tool <command>
#
# Commands:
#   run  Run a task
#   db   Database commands
```

--------------------------------

### Example — after-hook timing

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/middleware.md

Shows how to use `middleware` to measure execution time of a command. The middleware records the start time, awaits `next()`, and logs the elapsed time. This example is a simple timing hook that runs after the command completes.

```typescript
cli.use(middleware(async (c, next) => {
  const start = Date.now()
  await next()
  console.log(`took ${Date.now() - start}ms`)
}))
```

--------------------------------

### serve()

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/mcp.md

Starts a stdio MCP server that exposes commands as tools. It accepts a server name, version, command map, and optional configuration options.

```APIDOC
## serve()

### Description
Starts a stdio MCP server that exposes commands as tools. It accepts a server name, version, command map, and optional configuration options.

### Method
serve

### Signature
```ts
export async function serve(
  name: string,
  version: string,
  commands: Map<string, any>,
  options: serve.Options = {},
): Promise<void>
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | `string` | yes | — | MCP server name. |
| `version` | `string` | yes | — | MCP server version. |
| `commands` | `Map<string, any>` | yes | — | The CLI's internal command map (`Cli.toCommands.get(cli)`). |
| `options.env` | `z.ZodObject<any> \| undefined` | no | `undefined` | CLI-level env schema. |
| `options.input` | `Readable \| undefined` | no | `process.stdin` | Override input stream. |
| `options.middlewares` | `MiddlewareHandler[] \| undefined` | no | `undefined` | Root middleware handlers. |
| `options.output` | `Writable \| undefined` | no | `process.stdout` | Override output stream. |
| `options.vars` | `z.ZodObject<any> \| undefined` | no | `undefined` | Vars schema for middleware variables. |
| `options.version` | `string \| undefined` | no | `undefined` | CLI version string. |
| `options.instructions` | `string \| undefined` | no | `undefined` | Instructions describing the server. |
| `options.title` | `string \| undefined` | no | `undefined` | Human-readable server title. |
| `options.tools` | `ToolFilter \| undefined` | no | `undefined` | Tool discovery/filter options. |

### Example
```ts
await Mcp.serve('my-cli', '1.0.0', Cli.toCommands.get(cli)!, {
  tools: { discovery: 'direct' },
})
```

### Returns
`Promise<void>` - Resolves when the server is connected and running.
```

--------------------------------

### Example — structured error short-circuit

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/middleware.md

Shows how to use `middleware` to create a typed middleware that short-circuits with a structured error when a condition fails. The middleware checks `c.var.user` and returns an error object if not present, otherwise calls `next()`. The example includes a CLI setup with a `vars` schema and a command that uses the middleware.

```typescript
import { Cli, middleware, z } from 'incur'

type User = { id: string; admin?: boolean }
const cli = Cli.create('my-cli', {
  description: 'My CLI',
  vars: z.object({ user: z.custom<User>() }),
})

const requireAuth = middleware<typeof cli.vars>((c, next) => {
  if (!c.var.user) return c.error({ code: 'AUTH', message: 'must be logged in' })
  return next()
})

cli.command('deploy', { middleware: [requireAuth], run: () => ({ deployed: true }) })
```

--------------------------------

### Single-command CLI with root handler

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/cli.md

Example of a single-command CLI using `Cli.create` with a root handler. It defines an `args` schema with Zod, uses the `run` function to access `c.args.name`, and calls `.serve()` to start the CLI.

```ts
import { Cli, z } from 'incur'

Cli.create('greet', {
  description: 'A greeting CLI',
  args: z.object({
    name: z.string().describe('Name to greet'),
  }),
  run(c) {
    return { message: `hello ${c.args.name}` }
  },
}).serve()
```

--------------------------------

### Serve the CLI with cli.serve()

Source: https://github.com/wevm/incur/blob/main/SKILL.md

Parses process.argv and runs the CLI. Call this in your entry point to start the command-line interface.

```ts
cli.serve()
```

--------------------------------

### Augment Register interface with commands

Source: https://github.com/wevm/incur/blob/main/_autodocs/types.md

Shows how to augment the `Register` interface via declaration merging to add command definitions. This example adds `get` and `list` commands with their respective args and options schemas, enabling typed autocomplete for `Cta`.

```typescript
declare module 'incur' {
  interface Register {
    commands: {
      get: { args: { id: number }; options: {} }
      list: { args: {}; options: { limit: number } }
    }
  }
}
```

--------------------------------

### Mount HTTP server as CLI with fetch property

Source: https://github.com/wevm/incur/blob/main/README.md

Mount any Web Fetch API handler as a CLI command using the `fetch` property. The CLI translates HTTP requests using curl-style flags. The example shows a Hono app with GET and POST routes, and the resulting CLI invocations.

```ts
import { Cli } from 'incur'
import { Hono } from 'hono'

const app = new Hono()
  .get('/users', (c) => c.json({ users: [{ id: 1, name: 'Alice' }] }))
  .post('/users', async (c) => c.json({ created: true, ...(await c.req.json()) }, 201))

Cli.create('my-cli', {
  description: 'My CLI',
  fetch: app.fetch,
  // OR
  // fetch: bunApp.fetch
  // fetch: denoApp.fetch
  // fetch: elysiaApp.fetch,
}).serve()
```

```sh
$ my-cli api users
# → users:
# →   - id: 1
# →     name: Alice

$ my-cli api users -X POST -d '{"name":"Bob"}'
# → created: true
# → name: Bob
```

--------------------------------

### Show help for greet CLI

Source: https://github.com/wevm/incur/blob/main/README.md

Display the help output for the 'greet' CLI. It shows the usage, arguments, built-in commands, and global options.

```sh
$ greet --help
# greet – A greeting CLI
#
# Usage: greet <name>
#
# Arguments:
#   name  Name to greet
#
# Built-in Commands:
#   completions  Generate shell completion script
#   mcp add      Register as MCP server
#   skills add   Sync skill files to agents
#
# Global Options:
#   --filter-output <keys>              Filter output by key paths (e.g. foo,bar.baz,a[0,3])
#   --format <toon|json|yaml|md|jsonl>  Output format
#   --full-output                       Show full output envelope
#   --help                              Show help
#   --llms                              Print LLM-readable manifest
#   --mcp                               Start as MCP stdio server
#   --schema                            Show JSON Schema for command
#   --token-count                       Print token count of output instead of output
#   --token-limit <n>                   Limit output to n tokens
#   --token-offset <n>                  Skip first n tokens of output (for pagination)
#   --update                            Update to latest version
#   --version                           Show version
```

--------------------------------

### Install latest stable release on Windows

Source: https://github.com/wevm/incur/blob/main/docs/binaries.md

Installs the latest stable release on Windows. The installer downloads its executable and SHA256SUMS from the tagged release.

```powershell
irm https://github.com/wevm/frog/releases/latest/download/install.ps1 | iex
```

--------------------------------

### cli.serve usage

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/cli.md

Example of calling serve with default arguments.

```ts
await cli.serve()
```

--------------------------------

### Install latest stable release on Unix

Source: https://github.com/wevm/incur/blob/main/docs/binaries.md

Installs the latest stable release on Unix. The installer downloads its executable and SHA256SUMS from the tagged release.

```sh
curl -fsSL https://github.com/wevm/frog/releases/latest/download/install.sh | sh
```

--------------------------------

### sync()

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/sync-skills.md

Generates skill files from a command map and installs them natively.

```APIDOC
## `sync()`

### Description
Generates skill files from a command map and installs them natively.

### Signature
```ts
export async function sync(
  name: string,
  commands: Map<string, any>,
  options: sync.Options = {},
): Promise<sync.Result>
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | `string` | yes | — | CLI name. |
| `commands` | `Map<string, any>` | yes | — | Command map. |
| `options.cwd` | `string \| undefined` | no | package root (global) / `process.cwd()` (local) | Working directory for resolving `include` globs. |
| `options.depth` | `number \| undefined` | no | `1` | Grouping depth for skill files. |
| `options.description` | `string \| undefined` | no | `undefined` | CLI description used as the top-level group description. |
| `options.global` | `boolean \| undefined` | no | `true` | Install globally (`~/.agents/skills/` canonical) instead of project-local. |
| `options.include` | `string[] \| undefined` | no | `undefined` | Glob patterns of directories containing `SKILL.md` to include (e.g. `"skills/*"`; `"_root"` matches a root `SKILL.md`). |
| `options.rootCommand` | `{ description?, args?, destructive?, env?, hint?, mcp?, options?, output?, examples? } \| undefined` | no | `undefined` | Root command definition (when the CLI itself has a `run` handler). |

### Returns
```ts
type Result = {
  agents: import('./internal/agents.js').install.AgentInstall[]
  paths: string[]
  skills: Skill[]
}
type Skill = {
  description?: string | undefined
  external?: boolean | undefined
  name: string
}
```

### Behavior
Builds skill files in a temp dir, merges included external skills, installs via `Agents.install` (canonical `~/.agents/skills/<name>` + symlinks/copies for non-universal agents), removes stale skills from previous installs (`Agents.remove`), and writes metadata (hash + names + paths) to `$XDG_DATA_HOME/incur/<name>.json` (default `~/.local/share/incur/<name>.json`) for staleness detection (`writeMeta`, `src/SyncSkills.ts:287`).

### Example
```ts
const result = await SyncSkills.sync('my-cli', commands, {
  depth: 1,
  global: true,
  include: ['skills/*'],
  suggestions: ['build a cli with incur'],
})
console.log(result.skills.map((s) => s.name))
```
```

--------------------------------

### Config file format example

Source: https://github.com/wevm/incur/blob/main/_autodocs/configuration.md

JSON configuration file for the `config` option. Only command `options` are loaded; `args`, `env`, and built-ins are unaffected. Precedence is `argv > config > zod defaults`.

```json
{
  "options": { "verbose": true },
  "commands": {
    "echo": { "options": { "upper": true } },
    "project": { "commands": { "list": { "options": { "limit": 25 } } } }
  }
}
```

--------------------------------

### Generate shell completions for bash, zsh, and fish

Source: https://github.com/wevm/incur/blob/main/README.md

Generate and install shell hook scripts for tab completion. The hook calls back into your binary at every tab press, so completions are always in sync with your commands. Completions are dynamic, suggesting subcommands, --options, short aliases, and enum values based on context. Run `my-cli completions --help` for setup instructions.

```sh
# Generate and install completions
eval "$(my-cli completions bash)"    # add to ~/.bashrc
eval "$(my-cli completions zsh)"     # add to ~/.zshrc
my-cli completions fish | source     # add to ~/.config/fish/config.fish
```

--------------------------------

### Create a multi-command CLI with .command()

Source: https://github.com/wevm/incur/blob/main/README.md

Create a multi-command CLI with subcommands 'status' and 'install'. Chain `.command()` calls to register subcommands. The 'install' command defines an optional argument and an option with alias 'D'.

```ts
import { Cli, z } from 'incur'

Cli.create('my-cli', {
  description: 'My CLI',
})
  .command('status', {
    description: 'Show repo status',
    run() {
      return { clean: true }
    },
  })
  .command('install', {
    description: 'Install a package',
    args: z.object({
      package: z.string().optional().describe('Package name'),
    }),
    options: z.object({
      saveDev: z.boolean().optional().describe('Save as dev dependency'),
    }),
    alias: { saveDev: 'D' },
    run(c) {
      return { added: 1, packages: 451 }
    },
  })
  .serve()
```

--------------------------------

### create()

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/cli.md

Creates a CLI instance with four overloads. Supports root handlers, subcommand registration, and single-argument configuration.

```APIDOC
## create()

### Description
Creates a CLI instance. Four overloads are available: with a root handler, as a router, from a single options object with a root handler, or from a single options object as a router.

### Method
Function

### Signature
```ts
export function create<
  const name extends string,
  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,
  const globals extends z.ZodObject<any> | undefined = undefined,
>(
  name: name,
  definition: create.Options<args, env, opts, output, vars, globals> & { run: Function },
): Cli<{ [key in typeof name]: { args: InferOutput<args>; options: InferOutput<opts> } }, vars, env, globals, name>
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | `string` | yes (overloads 1–2) | — | CLI name; used in help, skills, MCP registration, and CTA prefixes. |
| `nameOrDefinition` | `string \| ({ name: string } & Options)` | yes (overloads 3–4) | — | Single-argument form; `definition.name` becomes the CLI name. |
| `definition` | `create.Options<...>` | no (overload 2) | `{}` | Full option object; see configuration.md. |

### Returns
`Cli<...>` or a `Root<...>` (when `run` is provided). The version defaults to `def.version ?? Binary.version`.

### Throws
- `Error` — if a `globals` schema key collides with a built-in flag name, or a `globalAlias` short alias collides with the reserved `-h` alias.
- Global option/alias conflicts are validated per-command via `assertNoGlobalOptionConflicts` when commands are registered.

### Examples

Single-command CLI:
```ts
import { Cli, z } from 'incur'

Cli.create('greet', {
  description: 'A greeting CLI',
  args: z.object({
    name: z.string().describe('Name to greet'),
  }),
  run(c) {
    return { message: `hello ${c.args.name}` }
  },
}).serve()
```

Router CLI with a sub-command group:
```ts
const db = Cli.create('db', { description: 'Database commands' }).command('migrate', {
  description: 'Run migrations',
  run: () => ({ migrated: true }),
})

Cli.create('tool', { description: 'A tool' })
  .command('run', { description: 'Run a task', run: () => ({ ok: true }) })
  .command(db)
  .serve()
```

Error propagation via `c.error(...)`:
```ts
Cli.create('deploy', {
  run(c) {
    if (!process.env.DEPLOY_TOKEN) return c.error({ code: 'AUTH', message: 'missing DEPLOY_TOKEN' })
    return { deployed: true }
  },
}).serve()
```
```

--------------------------------

### Run greet CLI with argument

Source: https://github.com/wevm/incur/blob/main/README.md

Run the 'greet' CLI with the 'world' argument. The output shows the returned message.

```sh
$ greet world
# → message: hello world
```

--------------------------------

### Example: Parser.zodParse()

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/parser.md

Example usage of Parser.zodParse() with an option schema and raw options. The parsed result is assigned to a variable.

```ts
const parsed = Parser.zodParse(optionSchema, rawOptions)
```

--------------------------------

### Cli.serve()

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/cli.md

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

```APIDOC
## Cli.serve()

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

### Method
serve

### Signature
```ts
serve(argv?: string[], options?: serve.Options): Promise<void>
```

### Parameters
- **argv** (string[]) - Optional - The command-line arguments to parse. Defaults to `process.argv`.
- **options** (serve.Options) - Optional - Additional options for serving.

### Returns
- **Promise<void>** - A promise that resolves when the command has been executed.
```

--------------------------------

### Example JSON manifest from --llms --format json

Source: https://github.com/wevm/incur/blob/main/SKILL.md

Example JSON schema manifest output from the --llms --format json flag. Shows the structure with version, commands, and schema for args, options, and output.

```json
{
  "version": "incur.v1",
  "commands": [
    {
      "name": "install",
      "description": "Install a package",
      "schema": {
        "args": { "type": "object", "properties": { "package": { "type": "string" } } },
        "options": { "type": "object", "properties": { "saveDev": { "type": "boolean" } } },
        "output": { "type": "object", "properties": { "added": { "type": "number" } } }
      }
    }
  ]
}
```

--------------------------------

### resolve() usage example

Source: https://github.com/wevm/incur/blob/main/_autodocs/api-reference/openapi.md

Example call to resolve() with an absolute URL string. Returns a Promise resolving to an OpenAPISpec.

```typescript
const spec = await Openapi.resolve('https://example.com/openapi.json')
```

--------------------------------

### Install specific release on Unix

Source: https://github.com/wevm/incur/blob/main/docs/binaries.md

Installs a specific release by using an exact tag URL, avoiding newer releases.

```sh
curl -fsSL https://github.com/wevm/frog/releases/download/v1.2.3/install.sh | sh
```
Tokens:
Raw