Incur

const cli = Cli.create("tool", {
  description: "Does one thing",
  args: z.object({ file: z.string() }),
  run({ args, options }) {
    return { processed: args.file };
  },
});

Router CLI (subcommands)

Omit run to create a CLI that registers subcommands via .command():

const cli = Cli.create("gh", {
  version: "1.0.0",
  description: "GitHub CLI",
});

cli.command("status", {
  description: "Show repo status",
  run() {
    return { clean: true };
  },
});

cli.serve();

Commands

Registering commands

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 };
  },
});

.command() is chainable — it returns the CLI instance:

cli
  .command("ping", { run: () => ({ pong: true }) })
  .command("version", { run: () => ({ version: "1.0.0" }) });

Subcommand groups

Create a sub-CLI and mount it as a command group:

const cli = Cli.create("gh", { description: "GitHub CLI" });

const pr = Cli.create("pr", { description: "Pull request commands" });

pr.command("list", {
  description: "List pull requests",
  options: z.object({
    state: z.enum(["open", "closed", "all"]).default("open"),
  }),
  run({ options }) {
    return { prs: [], state: options.state };
  },
});

pr.command("view", {
  description: "View a pull request",
  args: z.object({ number: z.number() }),
  run({ args }) {
    return { number: args.number, title: "Fix bug" };
  },
});

// Mount onto the parent CLI
cli.command(pr);

cli.serve();

gh pr list --state closed
gh pr view 42

Groups nest arbitrarily:

const cli = Cli.create("gh", { description: "GitHub CLI" });
const pr = Cli.create("pr", { description: "Pull requests" });
const review = Cli.create("review", { description: "Review commands" });

review.command("approve", { run: () => ({ approved: true }) });
pr.command(review);
cli.command(pr);
// → gh pr review approve

Fetch API

Mount an HTTP server as a command with .command('name', { fetch }). Argv is translated into HTTP requests using curl-style flags:

import { Cli } from "incur";
import { Hono } from "hono";

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

Cli.create("my-cli", { description: "My CLI" }).command("api", { fetch: app.fetch }).serve();

my-cli api users                          # GET /users
my-cli api users -X POST -d '{"name":"Bob"}'  # POST /users
my-cli api users --limit 5                # GET /users?limit=5

Fetch API + OpenAPI

Pass an OpenAPI spec alongside fetch to generate typed subcommands with args, options, and descriptions from the spec:

Cli.create("my-cli", { description: "My CLI" })
  .command("api", { fetch: app.fetch, openapi: spec })
  .serve();

my-cli api listUsers --limit 5     # GET /users?limit=5
my-cli api getUser 42              # GET /users/42
my-cli api createUser --name Bob   # POST /users with body
my-cli api --help                  # shows typed subcommands

Works with any (Request) => Response handler — Hono, Elysia, etc. Specs from @hono/zod-openapi are supported directly.

Serve CLI as Fetch API

Expose your CLI as a standard Fetch API handler with cli.fetch. Works with Bun, Cloudflare Workers, Deno, Hono, and anything that accepts (req: Request) => Response.

import { Cli, z } from "incur";

const cli = Cli.create("my-cli", { version: "1.0.0" }).command("users", {
  args: z.object({ id: z.coerce.number().optional() }),
  options: z.object({ limit: z.coerce.number().default(10) }),
  run(c) {
    if (c.args.id) return { id: c.args.id, name: "Alice" };
    return { users: [{ id: 1, name: "Alice" }], limit: c.options.limit };
  },
});

Bun.serve(cli); // Bun
Deno.serve(cli.fetch); // Deno
export default cli; // Cloudflare Workers
app.all("*", (c) => cli.fetch(c.request)); // Elysia
app.use((c) => cli.fetch(c.req.raw)); // Hono
export const GET = cli.fetch; // Next.js
export const POST = cli.fetch;

Request mapping:

Responses are JSON envelopes: { "ok": true, "data": { ... }, "meta": { "command": "users", "duration": "3ms" } }.

Error status codes: 400 for validation errors, 404 for unknown commands, 500 for thrown errors.

Async generator commands stream as NDJSON (application/x-ndjson). Middleware runs the same as serve().

Fetch gateways

If a resolved command is a fetch gateway (.command('api', { fetch })), the request is forwarded to the nested handler.

MCP over HTTP

The fetch handler exposes an MCP endpoint at /mcp. Agents can discover and call commands as MCP tools over HTTP:

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": "users", ... } }

The MCP server is initialized lazily on the first /mcp request. Non-/mcp paths route to the command API as usual.

Arguments & Options

All schemas use Zod. Arguments are positional (assigned by schema key order). Options are named flags.

Arguments