{"_id":"@0xbigboss/incur","_rev":"12-678f1c79e81fcdedc79b4658d0815fe9","name":"@0xbigboss/incur","dist-tags":{"latest":"0.6.1"},"versions":{"0.3.1":{"name":"@0xbigboss/incur","version":"0.3.1","license":"MIT","_id":"@0xbigboss/incur@0.3.1","maintainers":[{"name":"0xbigboss","email":"0xbigboss@proton.me"}],"homepage":"https://github.com/0xBigBoss/incur#readme","bugs":{"url":"https://github.com/0xBigBoss/incur/issues"},"bin":{"incur":"dist/bin.js","incur.src":"src/bin.ts"},"dist":{"shasum":"6d630e87142d9ee8182d2d3621857714cc1a3b07","tarball":"https://registry.npmjs.org/@0xbigboss/incur/-/incur-0.3.1.tgz","fileCount":249,"integrity":"sha512-m7u+bFry9XP7Y9PyRshmOvdaXeQKhKCfETW4XF6jmPNKymBdCW6oOjZRhA0QWqB/0CA18iT12+7u5MdgAnNroQ==","signatures":[{"sig":"MEQCIBlT+vE0j+0mIIB+8pF736zpkY6IyZ0Jy+Kkk1iesImrAiAj0slGu0kLQd1Zw+Qd02XTwFr4ufkaSDl2BdlW3/2JZA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1437365},"main":"./dist/index.js","pnpm":{"onlyBuiltDependencies":["bun"]},"type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"src":"./src/index.ts","types":"./dist/index.d.ts","default":"./dist/index.js"}},"gitHead":"0e3762675f8f51a2743052c8b728dc135ff10706","scripts":{"dev":"zile dev","test":"vitest","build":"zile","check":"oxlint --fix --ignore-pattern package.json && oxfmt","incur":"node --import tsx src/bin.ts","cli:skills":"pnpm incur skills add","check:types":"tsc -b","changeset:publish":"zile publish:prepare && changeset publish && zile publish:post","changeset:version":"changeset version"},"_npmUser":{"name":"0xbigboss","email":"0xbigboss@proton.me"},"repository":{"url":"git+https://github.com/0xBigBoss/incur.git","type":"git"},"_npmVersion":"9.9.2","description":" \"incur\" \"incur\" \"incur\" \"incur\" \"incur\" \"incur\" \"incur\" =22"},"exports":{".":{"src":"./src/index.ts","types":"./dist/index.d.ts","default":"./dist/index.js"}},"_npmUser":{"name":"0xbigboss","email":"0xbigboss@proton.me"},"_resolved":"/private/var/folders/9b/khhz0hwd07z_p9n1wh5mqg_80000gn/T/2963da3f157e82ce99449199d1b5ee2d/0xbigboss-incur-0.5.0.tgz","_integrity":"sha512-VeV4S7/e8EuZ5t8PwOEjilEZf2YrL+PlDrlhiI6dwF/Huw9CWmzGxNJ/3C/7UGwaIw04CIMpyWJFFoYeX0A+tA==","repository":{"url":"git+https://github.com/0xBigBoss/incur.git","type":"git"},"_npmVersion":"11.13.0","description":" \"incur\" =22"},"exports":{".":{"src":"./src/index.ts","types":"./dist/index.d.ts","default":"./dist/index.js"}},"_npmUser":{"name":"alleneubank","email":"adeubank@gmail.com"},"repository":{"url":"https://github.com/0xBigBoss/incur","type":"git"},"directories":{},"sideEffects":false,"_nodeVersion":"26.5.0","dependencies":{"zod":"^4.3.6","yaml":"^2.8.2","tokenx":"^1.3.0","graphql":"^16.13.1","@toon-format/toon":"^2.1.0","@bufbuild/protobuf":"^2.11.0","@connectrpc/connect":"^2.1.1","@cfworker/json-schema":"^4.1.1","@scalar/openapi-types":"^0.8.0","@connectrpc/connect-node":"^2.1.1","@modelcontextprotocol/server":"2.0.0-alpha.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/incur_0.5.1_1785425572694_0.8431043761973849","host":"s3://npm-registry-packages-npm-production"}},"0.6.0":{"name":"@0xbigboss/incur","version":"0.6.0","license":"MIT","_id":"@0xbigboss/incur@0.6.0","maintainers":[{"name":"alleneubank","email":"adeubank@gmail.com"}],"bin":{"incur":"./dist/bin.js","incur.src":"./src/bin.ts"},"dist":{"shasum":"783f0d42583be6c9bcd0cfb213bc5edb3663c630","tarball":"https://registry.npmjs.org/@0xbigboss/incur/-/incur-0.6.0.tgz","fileCount":324,"integrity":"sha512-80TRHbq+P19W0v0zA43UkgN9ryrE0etJQLKz7QsrjTRV0d3jDdpMNHth2hRQZKAtw+fZ/93zk+uvvz7fJWGcag==","signatures":[{"sig":"MEUCIATsoSIx7keRR7yYP1FQRWl/IsJBzcM7WR1GloAI0HqnAiEAuZisd/uv3pbbVnQppzsh/I1xVsgMp9XbaYaF3lJ0mLg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2512324},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=22"},"exports":{".":{"src":"./src/index.ts","types":"./dist/index.d.ts","default":"./dist/index.js"}},"_npmUser":{"name":"alleneubank","email":"adeubank@gmail.com"},"repository":{"url":"https://github.com/0xBigBoss/incur","type":"git"},"directories":{},"sideEffects":false,"_nodeVersion":"26.5.0","dependencies":{"zod":"^4.3.6","yaml":"^2.8.2","tokenx":"^1.3.0","graphql":"^16.13.1","@toon-format/toon":"^2.1.0","@bufbuild/protobuf":"^2.11.0","@connectrpc/connect":"^2.1.1","@cfworker/json-schema":"^4.1.1","@scalar/openapi-types":"^0.8.0","@connectrpc/connect-node":"^2.1.1","@modelcontextprotocol/server":"2.0.0-alpha.4"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/incur_0.6.0_1785441017468_0.7066604064707289","host":"s3://npm-registry-packages-npm-production"}},"0.6.1":{"name":"@0xbigboss/incur","type":"module","version":"0.6.1","license":"MIT","repository":{"type":"git","url":"https://github.com/0xBigBoss/incur"},"publishConfig":{"access":"public"},"dependencies":{"@bufbuild/protobuf":"^2.11.0","@cfworker/json-schema":"^4.1.1","@connectrpc/connect":"^2.1.1","@connectrpc/connect-node":"^2.1.1","@modelcontextprotocol/server":"2.0.0-alpha.4","@scalar/openapi-types":"^0.8.0","@toon-format/toon":"^2.1.0","graphql":"^16.13.1","tokenx":"^1.3.0","yaml":"^2.8.2","zod":"^4.3.6"},"engines":{"node":">=22"},"sideEffects":false,"bin":{"incur":"./dist/bin.js","incur.src":"./src/bin.ts"},"main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","src":"./src/index.ts","default":"./dist/index.js"}},"_nodeVersion":"26.5.0","_id":"@0xbigboss/incur@0.6.1","dist":{"integrity":"sha512-k/y4GMEVVPpJ6ROMUX6PwZflhUOFUOSP0n8Lh1Usm28lBK5+QW7rBEVrn8Zja5ZABCLzqa7R8WH0d/D2D6DRjw==","shasum":"be7ec92222e9d786098c1d504dbad23e08a679ed","tarball":"https://registry.npmjs.org/@0xbigboss/incur/-/incur-0.6.1.tgz","fileCount":324,"unpackedSize":2515631,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDU/dEEs624VolXX/by6yOjnX+G8XJicLeNBAyP/VJo6wIhAI9GLB8wicRG69MHB0Bxy3t/q2EzMh1S1OSp2xY+S2j0"}]},"_npmUser":{"name":"alleneubank","email":"adeubank@gmail.com"},"directories":{},"maintainers":[{"name":"alleneubank","email":"adeubank@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/incur_0.6.1_1785448618851_0.9338740493830284"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-17T13:17:29.254Z","modified":"2026-07-30T21:56:59.210Z","0.3.1":"2026-03-17T13:17:29.565Z","0.4.1":"2026-04-13T17:39:56.599Z","0.4.2":"2026-04-13T19:25:47.774Z","0.4.3":"2026-04-13T19:30:46.393Z","0.4.4":"2026-04-13T22:02:42.132Z","0.4.5":"2026-04-15T16:22:04.499Z","0.4.6":"2026-04-16T00:34:13.366Z","0.5.0":"2026-06-18T18:31:50.407Z","0.5.1":"2026-07-30T15:32:52.898Z","0.6.0":"2026-07-30T19:50:17.671Z","0.6.1":"2026-07-30T21:56:59.042Z"},"license":"MIT","repository":{"type":"git","url":"https://github.com/0xBigBoss/incur"},"maintainers":[{"name":"alleneubank","email":"adeubank@gmail.com"}],"readme":"\n \n \n \"incur\"\n\n\n
\n\n

\n \n \n \n \"Version\"\n \n \n \n \n \n \"Code\n \n \n \n \n \n \"MIT\n \n \n

\n\n

\n Features · Quickprompt · Install · Usage · Walkthrough · License\n

\n\n## Features\n\n- [**Agent discovery**](#agent-discovery): built-in Skills and MCP sync (`skills add`, `mcp add`) so agents find your CLI automatically\n- [**Session savings**](#session-savings): up to **3× fewer tokens** per session vs. MCP or skill alternatives\n- [**Call-to-actions**](#call-to-actions): suggest next commands to agents and humans after a run\n- [**TOON output**](#toon-output): token-efficient default format that agents parse easily, with JSON, YAML, Markdown, and JSONL alternatives\n- [**`--llms` flag**](#agent-discovery): token-efficient command manifest in Markdown or JSON schema\n- [**Well-formed I/O**](#well-formed-io): Schemas schemas for arguments, options, environment variables, and output\n- [**Inferred types**](#inferred-types): generic type flow from schemas to `run` callbacks with zero manual annotations\n- [**Global options**](#global-options): `--format`, `--full-output`, `--help`, `--json`, `--update`, `--version` on every CLI for free\n- [**Standalone binaries**](#standalone-binaries): build macOS, Linux, and Windows executables with verified updates and initial installers\n- [**Light API surface**](#light-api-surface): `Cli.create()`, `.command()`, `.serve()` – that's it\n- [**Middleware**](#middleware): composable before/after hooks with typed dependency injection via `cli.use()`\n\n## Quickprompt\n\nPrompt your agent:\n\n**Skills (recommended – lighter on tokens)**\n\n```txt\nRun `npx incur skills add`, then show me how to build CLIs with incur.\n```\n\n**MCP**\n\n```txt\nRun `npx incur mcp add`, then show me how to build CLIs with incur.\n```\n\n## Install\n\n```bash\nnpm i incur\n```\n\n```bash\npnpm i incur\n```\n\n```bash\nbun i incur\n```\n\n## Usage\n\n### Single-command CLI\n\nPass `run` directly to `Cli.create()` for CLIs that do one thing.\n\n```ts\nimport { Cli, z } from 'incur'\n\nCli.create('greet', {\n description: 'A greeting CLI',\n args: z.object({\n name: z.string().describe('Name to greet'),\n }),\n run(c) {\n return { message: `hello ${c.args.name}` }\n },\n}).serve()\n```\n\n```sh\n$ greet world\n# → message: hello world\n```\n\n```sh\n$ greet --help\n# greet – A greeting CLI\n#\n# Usage: greet \n#\n# Arguments:\n# name Name to greet\n#\n# Built-in Commands:\n# completions Generate shell completion script\n# mcp add Register as MCP server\n# skills add Sync skill files to agents\n#\n# Global Options:\n# --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3])\n# --format Output format\n# --full-output Show full output envelope\n# --help Show help\n# --llms Print LLM-readable manifest\n# --mcp Start as MCP stdio server\n# --schema Show JSON Schema for command\n# --token-count Print token count of output instead of output\n# --token-limit Limit output to n tokens\n# --token-offset Skip first n tokens of output (for pagination)\n# --update Update to latest version\n# --version Show version\n```\n\n### Multi-command CLI\n\nChain `.command()` calls to register subcommands.\n\n```ts\nimport { Cli, z } from 'incur'\n\nCli.create('my-cli', {\n description: 'My CLI',\n})\n .command('status', {\n description: 'Show repo status',\n run() {\n return { clean: true }\n },\n })\n .command('install', {\n description: 'Install a package',\n args: z.object({\n package: z.string().optional().describe('Package name'),\n }),\n options: z.object({\n saveDev: z.boolean().optional().describe('Save as dev dependency'),\n }),\n alias: { saveDev: 'D' },\n run(c) {\n return { added: 1, packages: 451 }\n },\n })\n .serve()\n```\n\n```sh\n$ my-cli status\n# → clean: true\n\n$ my-cli install express -D\n# → added: 1\n# → packages: 451\n```\n\n```sh\n$ my-cli --help\n# my-cli – My CLI\n#\n# Usage: my-cli \n#\n# Commands:\n# install Install a package\n# status Show repo status\n#\n# Built-in Commands:\n# completions Generate shell completion script\n# mcp add Register as MCP server\n# skills add Sync skill files to agents\n#\n# Global Options:\n# --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3])\n# --format Output format\n# --full-output Show full output envelope\n# --help Show help\n# --llms Print LLM-readable manifest\n# --mcp Start as MCP stdio server\n# --schema Show JSON Schema for command\n# --token-count Print token count of output instead of output\n# --token-limit Limit output to n tokens\n# --token-offset Skip first n tokens of output (for pagination)\n# --update Update to latest version\n# --version Show version\n```\n\n### Sub-command CLI\n\nCreate a separate `Cli` and mount it with `.command(cli)` to nest command groups.\n\n```ts\nconst cli = Cli.create('my-cli', { description: 'My CLI' })\n\n// Create a `pr` group.\nconst pr = Cli.create('pr', { description: 'Pull request commands' }).command('list', {\n description: 'List pull requests',\n options: z.object({\n state: z.enum(['open', 'closed', 'all']).default('open'),\n }),\n run(c) {\n return { prs: [], state: c.options.state }\n },\n})\n\ncli\n .command(pr) // Link the `pr` group.\n .serve()\n```\n\n```sh\n$ my-cli pr list --state closed\n# → prs: (empty)\n# → state: closed\n```\n\n```sh\n$ my-cli --help\n# my-cli – My CLI\n#\n# Usage: my-cli \n#\n# Commands:\n# pr Pull request commands\n#\n# Built-in Commands:\n# completions Generate shell completion script\n# mcp add Register as MCP server\n# skills add Sync skill files to agents\n#\n# Global Options:\n# --filter-output Filter output by key paths (e.g. foo,bar.baz,a[0,3])\n# --format Output format\n# --full-output Show full output envelope\n# --help Show help\n# --llms Print LLM-readable manifest\n# --mcp Start as MCP stdio server\n# --schema Show JSON Schema for command\n# --token-count Print token count of output instead of output\n# --token-limit Limit output to n tokens\n# --token-offset Skip first n tokens of output (for pagination)\n# --update Update to latest version\n# --version Show version\n```\n\n### Mount APIs as CLIs\n\nMount any HTTP server as a command with the `fetch` property. Supports any API\nframework that exposes a [Web Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) handler.\n\nThe CLI translates HTTP requests using curl-style flags.\n\n```ts\nimport { Cli } from 'incur'\nimport { Hono } from 'hono'\n\nconst app = new Hono()\n .get('/users', (c) => c.json({ users: [{ id: 1, name: 'Alice' }] }))\n .post('/users', async (c) => c.json({ created: true, ...(await c.req.json()) }, 201))\n\nCli.create('my-cli', {\n description: 'My CLI',\n fetch: app.fetch,\n // OR\n // fetch: bunApp.fetch\n // fetch: denoApp.fetch\n // fetch: elysiaApp.fetch,\n}).serve()\n```\n\n```sh\n$ my-cli api users\n# → users:\n# → - id: 1\n# → name: Alice\n\n$ my-cli api users -X POST -d '{\"name\":\"Bob\"}'\n# → created: true\n# → name: Bob\n```\n\n#### As commands\n\nYou can also mount Hono apps onto commands:\n\n```ts\nimport { Cli } from 'incur'\nimport { Hono } from 'hono'\n\nconst app = new Hono()\n .get('/users', (c) => c.json({ users: [{ id: 1, name: 'Alice' }] }))\n .post('/users', async (c) => c.json({ created: true, ...(await c.req.json()) }, 201))\n\nCli.create('my-cli', { description: 'My CLI' }).command('users', { fetch: app.fetch }).serve()\n```\n\n#### OpenAPI\n\nPass an OpenAPI spec alongside `fetch` to generate typed subcommands with args, options, and descriptions extracted from the spec:\n\n```ts\nimport { Cli } from 'incur'\nimport { app, spec } from './my-hono-openapi-app.js'\n\nCli.create('my-cli', { description: 'My CLI' })\n .command('api', { fetch: app.fetch, openapi: spec })\n .serve()\n```\n\n```sh\n$ my-cli api --help\n# Commands:\n# listUsers List users\n# createUser Create a user\n# getUser Get a user by ID\n\n$ my-cli api listUsers --limit 5\n# → users: ...\n\n$ my-cli api getUser 42\n# → id: 42\n# → name: Alice\n\n$ my-cli api createUser --name Bob\n# → created: true\n# → name: Bob\n```\n\nSet `openapiConfig.mode` to `'namespace'` to generate nested commands from path segments instead of using `operationId`:\n\n```ts\nCli.create('my-cli', { description: 'My CLI' })\n .command('api', { fetch: app.fetch, openapi: spec, openapiConfig: { mode: 'namespace' } })\n .serve()\n```\n\n```sh\n$ my-cli api users --help\n# Commands:\n# get List users\n# id User ID\n# post Create a user\n\n$ my-cli api users get --limit 5\n# → users: ...\n```\n\nWhen served with `cli.fetch`, the generated spec is available at `/openapi.json`, `/openapi.yml`, `/openapi.yaml`, and `/.well-known/openapi.json`. Methods are inferred from command names: read-like commands use `GET`, update-like commands use `PATCH`, delete-like commands use `DELETE`, and other commands use `POST`.\n\n#### MCP command sources\n\nPass a remote MCP streamable-HTTP endpoint to generate a command group from its tools:\n\n```ts\nimport { Cli } from 'incur'\n\nCli.create('my-cli', { description: 'My CLI' })\n .command('docs', { mcp: 'https://mcp.tempo.xyz/mcp' })\n .serve()\n```\n\n```sh\n$ my-cli docs --help\n# Commands:\n# search Search docs\n\n$ my-cli docs search --query tempo\n# → results: ...\n```\n\nEach MCP tool becomes a plain incur subcommand, so it is also available through `cli.fetch` and through incur's own MCP server as `_`. Progressive remote catalogs are resolved automatically.\n\n### Serve CLIs as APIs\n\nThe inverse of mounting — 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`.\n\n```ts\nimport { Cli, z } from 'incur'\n\nconst cli = Cli.create('my-cli', { version: '1.0.0' }).command('users', {\n args: z.object({ id: z.coerce.number().optional() }),\n options: z.object({ limit: z.coerce.number().default(10) }),\n run(c) {\n if (c.args.id) return { id: c.args.id, name: 'Alice' }\n return { users: [{ id: 1, name: 'Alice' }], limit: c.options.limit }\n },\n})\n\nBun.serve(cli) // Bun\nDeno.serve(cli.fetch) // Deno\nexport default cli // Cloudflare Workers\napp.all('*', (c) => cli.fetch(c.request)) // Elysia\napp.use((c) => cli.fetch(c.req.raw)) // Hono\nexport const GET = cli.fetch // Next.js\nexport const POST = cli.fetch // Next.js\n```\n\nPath segments map to commands and positional args, query params to options (GET), and JSON body to options (POST):\n\n```\nGET /users?limit=5 → my-cli users --limit 5\nGET /users/42 → my-cli users 42\nPOST /users { \"name\": \"Bob\" } → my-cli users --name Bob\n```\n\nResponses use the same JSON envelope as `--full-output --format json`:\n\n```json\n{ \"ok\": true, \"data\": { \"users\": [...] }, \"meta\": { \"command\": \"users\", \"duration\": \"3ms\" } }\n```\n\nAsync generator commands stream as NDJSON (`application/x-ndjson`). Middleware runs the same as in `serve()`.\n\n#### MCP over HTTP\n\nThe `fetch` handler automatically exposes an MCP endpoint at `/mcp`. Agents can discover and call your CLI's commands over HTTP, with no stdio required:\n\n```\nPOST /mcp { \"jsonrpc\": \"2.0\", \"method\": \"initialize\", ... }\nPOST /mcp { \"jsonrpc\": \"2.0\", \"method\": \"tools/list\", ... }\nPOST /mcp { \"jsonrpc\": \"2.0\", \"method\": \"tools/call\", \"params\": { \"name\": \"search_tools\", ... } }\nPOST /mcp { \"jsonrpc\": \"2.0\", \"method\": \"tools/call\", \"params\": { \"name\": \"get_tool_details\", ... } }\nPOST /mcp { \"jsonrpc\": \"2.0\", \"method\": \"tools/call\", \"params\": { \"name\": \"call_read_tool\", ... } }\n```\n\nMCP servers use progressive discovery by default: clients search a compact catalog, inspect one full schema, then execute through a read or write gate. This keeps command schemas out of `tools/list`. Set `mcp.tools.discovery` to `'direct'` for clients that require every command as a top-level tool:\n\n```ts\nCli.create('my-cli', { mcp: { tools: { discovery: 'direct' } } })\n```\n\nNon-`/mcp` paths continue routing to the command API as usual.\n\n## Walkthrough\n\n### Agent discovery\n\nAgents can only use your CLI if they know it exists. incur solves this with three built-in discovery mechanisms – no manual config, no copy-pasting tool definitions:\n\n```sh\n# Auto-generate and install agent skill files (recommended – lighter on tokens)\nmy-cli skills add\n\n# Register as MCP server for your agents\nmy-cli mcp add\n\n# Output machine-readable manifest\nmy-cli --llms\n```\n\n### Session savings\n\nMost CLIs expose tools via MCP or a single monolithic skill file. incur combines on-demand skill loading with TOON output to cut token usage across the entire session – from discovery through invocation and response.\n\nThe table below models a session with a 20-command CLI producing full output envelopes.\n\n- **Session start** – tokens consumed just by having the tool available. _Traditional MCP servers inject all tool schemas into every turn; skills only load frontmatter (name + description)._\n- **Discovery** – tokens to learn what commands exist and how to call them. _MCP gets this at session start; skills load the full skill file on demand; incur splits by command group so only relevant commands are loaded._\n- **Invocation (×5)** – tokens per tool call.\n- **Response (×5)** – tokens in CLI output. _MCP and skills return JSON; incur defaults to TOON which strips braces, quotes, and keys._\n\n```\n┌─────────────────┬────────────┬──────────────────┬─────────┬───────────────┐\n│ │ MCP + JSON │ One Skill + JSON │ incur │ vs. incur │\n├─────────────────┼────────────┼──────────────────┼─────────┼───────────────┤\n│ Session start │ 6,747 │ 624 │ 805 │ ↓8.4× │\n│ Discovery │ 0 │ 11,489 │ 387 │ ↓29.7× │\n│ Invocation (×5) │ 110 │ 65 │ 65 │ ↓1.7× │\n│ Response (×5) │ 10,940 │ 10,800 │ 5,790 │ ↓1.9× │\n├─────────────────┼────────────┼──────────────────┼─────────┼───────────────┤\n│ Cost │ $0.0325 │ $0.0410 │ $0.0131 │ ↓3.1× │\n└─────────────────┴────────────┴──────────────────┴─────────┴───────────────┘\n```\n\n### Call-to-actions\n\nWithout CTAs, agents have to guess what to do next or ask the user. With CTAs, your CLI tells the agent exactly which commands are relevant after each run, so it can chain operations without extra prompting.\n\nReturn CTAs from `ok()` or `error()` to suggest next steps. `cta` parameters are also fully type-inferred, so agents get valid command names, arguments, and options for free.\n\n```ts\ncli.command('list', {\n args: z.object({ state: z.enum(['open', 'closed']).default('open') }),\n run(c) {\n const items = [{ id: 1, title: 'Fix bug' }]\n return c.ok(\n { items },\n {\n cta: {\n commands: [\n { command: 'get 1', description: 'View item' },\n { command: 'list', args: { state: 'closed' }, description: 'View closed' },\n ],\n },\n },\n )\n },\n})\n```\n\n```sh\n$ my-cli list\n# → items:\n# → - id: 1\n# → title: Fix bug\n# Next:\n# my-cli get 1 – View item\n# my-cli list closed – View closed\n```\n\n### Light API surface\n\nA small API means agents can build entire CLIs in a single pass without needing to learn framework abstractions. Three functions: `create`, `command`, `serve`, and everything else (parsing, help, validation, output formatting, agent discovery) is handled automatically:\n\n```ts\nimport { Cli, z } from 'incur'\n\n// Define sub-command groups\nconst db = Cli.create('db', { description: 'Database commands' }).command('migrate', {\n description: 'Run migrations',\n run: () => ({ migrated: true }),\n})\n\n// Create the root CLI\nCli.create('tool', { description: 'A tool' })\n // Register commands\n .command('run', { description: 'Run a task', run: () => ({ ok: true }) })\n // Mount sub-command groups\n .command(db)\n // Serve the CLI\n .serve()\n```\n\n```sh\n$ tool --help\n# Usage: tool \n#\n# Commands:\n# run Run a task\n# db Database commands\n```\n\n### TOON output\n\nEvery token an agent spends reading CLI output is a token it can’t spend reasoning. incur defaults to [TOON](https://github.com/toon-format/toon) – a format that’s as readable as YAML but with no quoting, no braces, and no redundant syntax. Agents parse it easily and use up to **60% fewer tokens compared to JSON**.\n\n```sh\n$ my-cli hikes --location Boulder --season spring_2025\n# → context:\n# → task: Our favorite hikes together\n# → location: Boulder\n# → season: spring_2025\n# → friends[3]: ana,luis,sam\n# → hikes[3]{id,name,distanceKm,elevationGain,companion,wasSunny}:\n# → 1,Blue Lake Trail,7.5,320,ana,true\n# → 2,Ridge Overlook,9.2,540,luis,false\n# → 3,Wildflower Loop,5.1,180,sam,true\n```\n\nSwitch formats with `--format` or `--json`:\n\n```sh\n$ my-cli status --format json\n# → {\n# → \"context\": {\n# → \"task\": \"Our favorite hikes together\",\n# → \"location\": \"Boulder\",\n# → \"season\": \"spring_2025\"\n# → },\n# → \"friends\": [\"ana\", \"luis\", \"sam\"],\n# → \"hikes\": [\n# → ... + 1000 more tokens\n# → ]\n# → }\n```\n\nSupported formats: `toon`, `json`, `yaml`, `md`, `jsonl`.\n\n### Well-formed I/O\n\nAgents fail when they guess at argument formats or misinterpret output structure. incur eliminates this by declaring schemas for arguments, options, environment variables, and output – every input is validated before `run` executes, and every output has a known shape that agents can rely on without parsing heuristics:\n\n```ts\ncli.command('deploy', {\n args: z.object({ env: z.enum(['staging', 'production']) }),\n options: z.object({ force: z.boolean().optional() }),\n env: z.object({ DEPLOY_TOKEN: z.string() }),\n output: z.object({ url: z.string(), duration: z.number() }),\n run(c) {\n return { url: `https://${c.args.env}.example.com`, duration: 3.2 }\n },\n})\n```\n\n### Streaming\n\nUse `async *run` to stream chunks incrementally. Yield objects for structured data or plain strings for text:\n\n```ts\ncli.command('logs', {\n description: 'Tail logs',\n async *run() {\n yield 'connecting...'\n yield 'streaming logs'\n yield 'done'\n },\n})\n```\n\n```sh\n$ my-cli logs\n# → connecting...\n# → streaming logs\n# → done\n```\n\nEach yielded value is written as a line in human/TOON mode. With `--format jsonl`, each chunk becomes `{\"type\":\"chunk\",\"data\":\"...\"}`. You can also yield objects:\n\n```ts\nasync *run() {\n yield { progress: 50 }\n yield { progress: 100 }\n}\n```\n\nUse `ok()` or `error()` as the return value to attach CTAs or signal failure:\n\n```ts\nasync *run(c) {\n yield { step: 1 }\n yield { step: 2 }\n return c.ok(undefined, { cta: { commands: ['status'] } })\n}\n```\n\n### Inferred types\n\nType safety isn’t just for humans – agents building CLIs with incur get immediate feedback when they pass the wrong argument type or return the wrong shape. Schemas flow through generics so `run` callbacks, `output`, and `cta` commands are all fully inferred with zero manual annotations:\n\n```ts twoslash\ncli.command('greet', {\n args: z.object({ name: z.string() }),\n options: z.object({ loud: z.boolean().default(false) }),\n output: z.object({ message: z.string() }),\n run(c) {\n c.args.name\n // ^? (property) name: string\n c.options.loud\n // ^? (property) loud: boolean\n return c.ok(\n { message: `hello ${c.args.name}` },\n //^? (property) message: string\n {\n cta: { commands: ['greet world'] },\n // ^? 'greet' | 'other-cmd'\n },\n )\n },\n})\n```\n\n### Output policy\n\nControl whether output data is displayed to humans. By default, output goes to everyone (`'all'`). Set `outputPolicy: 'agent-only'` to suppress data in TTY mode while still returning it to agents via `--json`, `--format`, or `--full-output`.\n\n```ts\ncli.command('deploy', {\n outputPolicy: 'agent-only',\n run() {\n // Agents get the structured data; humans see nothing (or just CTAs/errors)\n return { id: 'deploy-123', url: 'https://staging.example.com' }\n },\n})\n```\n\nSet it on a group or root CLI to inherit across all children:\n\n```ts\nconst internal = Cli.create('internal', {\n description: 'Internal commands',\n outputPolicy: 'agent-only',\n})\ninternal.command('sync', { run: () => ({ synced: true }) }) // inherits agent-only\ninternal.command('status', {\n outputPolicy: 'all', // overrides to show output\n run: () => ({ ok: true }),\n})\n```\n\n### CLI name\n\nThe `run` context (and middleware context) includes `name` — the CLI name passed to `Cli.create()`. Useful for composing help text, error messages, and user-facing strings:\n\n```ts\nconst cli = Cli.create('deploy-cli', { description: 'Deploy tools' })\n\ncli.command('check', {\n output: z.string(),\n run(c) {\n if (!authenticated()) return `Not logged in. Run \\`${c.name} auth login\\` to log in.`\n return 'OK'\n },\n})\n```\n\n### Deprecated options\n\nMark options as deprecated with `.meta({ deprecated: true })`. Deprecated flags show `[deprecated]` in `--help`, `**Deprecated.**` in skill docs, `deprecated: true` in JSON Schema (`--llms`), and emit a stderr warning when used in TTY mode:\n\n```ts\ncli.command('deploy', {\n options: z.object({\n zone: z.string().optional().describe('Availability zone').meta({ deprecated: true }),\n region: z.string().optional().describe('Target region'),\n }),\n run(c) {\n return { region: c.options.region }\n },\n})\n```\n\n```sh\n$ my-cli deploy --zone us-east-1\n# Warning: --zone is deprecated\n```\n\n### Agent detection\n\nThe `run` context includes an `agent` boolean — `true` when stdout is not a TTY (piped or consumed by an agent), `false` when running in a terminal. Use it to tailor behavior:\n\n```ts\ncli.command('deploy', {\n args: z.object({ env: z.enum(['staging', 'production']) }),\n run(c) {\n if (!c.agent) console.log(`Deploying to ${c.args.env}...`)\n return { url: `https://${c.args.env}.example.com` }\n },\n})\n```\n\n### Middleware\n\nRegister composable before/after hooks with `cli.use()`. Middleware executes in registration order, onion-style – each calls `await next()` to proceed to the next middleware or the command handler.\n\n```ts\nconst cli = Cli.create('deploy-cli', { description: 'Deploy tools' })\n .use(async (c, next) => {\n const start = Date.now()\n await next()\n console.log(`took ${Date.now() - start}ms`)\n })\n .command('deploy', {\n run() {\n return { deployed: true }\n },\n })\n```\n\n```sh\n$ deploy-cli deploy\n# → deployed: true\n# took 12ms\n```\n\nPer-command middleware runs after root and group middleware, and only for that command:\n\n```ts\nimport { Cli, middleware, z } from 'incur'\n\nconst cli = Cli.create('my-cli', {\n description: 'My CLI',\n vars: z.object({ user: z.custom() }),\n})\n\n// structured error with code — shows up in the output envelope\nconst requireAuth = middleware((c, next) => {\n if (!c.var.user) return c.error({ code: 'AUTH', message: 'must be logged in' })\n return next()\n})\n\n// throwing also works — produces an UNKNOWN error code\nconst requireAdmin = middleware((c, next) => {\n if (!c.var.user?.admin) throw new Error('admin required')\n return next()\n})\n\ncli.command('deploy', {\n middleware: [requireAuth],\n run() {\n return { deployed: true }\n },\n})\n```\n\n```sh\n$ my-cli deploy\n# Error (AUTH): must be logged in\n\n$ my-cli other-cmd\n# per-command middleware does not run\n```\n\n### Variables\n\nDeclare a `vars` schema on `create()` to enable typed variables. Middleware sets them with `c.set()`, and both middleware and command handlers read them via `c.var`. Use `.default()` for vars that don't need middleware:\n\n```ts\ntype User = { id: string; name: string }\n\nconst cli = Cli.create('my-cli', {\n description: 'My CLI',\n vars: z.object({\n user: z.custom(),\n requestId: z.string(),\n debug: z.boolean().default(true),\n }),\n})\n\ncli.use(async (c, next) => {\n c.set('user', await authenticate())\n c.set('requestId', crypto.randomUUID())\n await next()\n})\n\ncli.command('whoami', {\n run(c) {\n return { user: c.var.user, requestId: c.var.requestId, debug: c.var.debug }\n },\n})\n```\n\n```sh\n$ my-cli whoami\n# → user:\n# → id: u_123\n# → name: Alice\n# → requestId: 550e8400-e29b-41d4-a716-446655440000\n# → debug: true\n```\n\n### Standalone binaries\n\nBuild standalone macOS, Linux, and Windows executables with Bun:\n\n```sh\nincur build ./src/bin.ts --installer\n```\n\nThe default build creates unsigned binaries for every supported platform. Add `--installer` to include shell installation scripts.\n\nCopy this workflow to `.github/workflows/binary-release.yml` to prepare a release and upload its unsigned binaries:\n\n```yaml\nname: Binary Release\n\non:\n workflow_dispatch:\n\nconcurrency:\n group: binary-release\n\njobs:\n release:\n runs-on: ubuntu-latest\n permissions:\n contents: write\n steps:\n - id: release\n uses: wevm/incur/release@v1\n```\n\nAfter the release is published, users can install without a package manager:\n\n```sh\ncurl -fsSL https://github.com///releases/latest/download/install.sh | sh\n```\n\nConnect those assets to a public GitHub repository:\n\n```ts\nimport { Binary, Cli } from 'incur'\n\nconst cli = Cli.create('my-cli', {\n update: Binary.github({ repository: 'example/my-cli' }),\n})\n```\n\nThe provider activates only inside an Incur-built executable. Source and package installations continue to use their inferred npm, pnpm, or Bun updater. See the [standalone binary guide](./docs/binaries.md) for installer behavior, the target matrix, and the release action.\n\n### Update notices\n\nIncur CLIs installed from npm packages automatically check for updates in human TTY mode. Results are cached for one day and refreshed in a detached process, so checks do not delay commands or change agent, JSON, MCP, help, or completion output.\n\nWhen a newer version is available, Incur suggests the built-in root flag:\n\n```text\nUpdate available for my-cli:\n my-cli --update # upgrade from 1.0.0 to 1.1.0\n```\n\nRunning `my-cli --update` uses npm, pnpm, or Bun to update the package globally. Incur infers the package and package manager from the executing binary. Set `update.package` to opt into registry updates when package metadata is unavailable:\n\n```ts\nconst cli = Cli.create('my-cli', {\n update: { package: '@example/my-cli' },\n version: '1.0.0',\n})\n```\n\nStandalone executables configured with `Binary.github` use the same detached check path and install only after an explicit `--update`.\n\nSet `update: false` to disable automatic notices. `NO_UPDATE_NOTIFIER`, `CI`, and `npm_config_update_notifier=false` also suppress notices without disabling explicit updates.\n\n### Global options\n\nEvery incur CLI includes these flags automatically:\n\n| Flag | Description |\n| ------------------------ | ------------------------------------------------------ |\n| `--filter-output ` | Filter output by key paths (e.g. `foo,bar.baz,a[0,3]`) |\n| `--format ` | Output format: `toon`, `json`, `yaml`, `md` |\n| `--full-output` | Include full envelope (`ok`, `data`, `meta`) |\n| `--help`, `-h` | Show help for the CLI or a specific command |\n| `--llms` | Output agent-readable command manifest |\n| `--mcp` | Start as an MCP stdio server |\n| `--json` | Shorthand for `--format json` |\n| `--schema` | Show JSON Schema for command's args, options, output |\n| `--token-count` | Print token count of output instead of output |\n| `--token-limit ` | Limit output to n tokens (for pagination) |\n| `--token-offset ` | Skip first n tokens of output (for pagination) |\n| `--update` | Update to the latest version |\n| `--version` | Print CLI version |\n\n### Config file\n\nLoad option defaults from a JSON config file. Opt in with `config` on `Cli.create()`:\n\n```ts\nconst cli = Cli.create('my-cli', {\n config: {\n flag: 'config',\n files: ['my-cli.json', '~/.config/my-cli/config.json'],\n },\n})\n```\n\n- `flag` — registers `--config ` and `--no-config` as global flags. The flag name is configurable (`{ flag: 'settings' }` → `--settings`/`--no-settings`). Omit to auto-load only.\n- `files` — ordered search paths. First existing file wins. Supports resolving `~`. Defaults to `['.json']`.\n- `loader` — custom loader function for non-JSON formats. Receives the resolved path (or `undefined`) and returns the config tree:\n\n```ts\nconst cli = Cli.create('my-cli', {\n config: {\n files: ['my-cli.toml'],\n async loader(path) {\n if (!path) return undefined\n return TOML.parse(await readFile(path, 'utf8'))\n },\n },\n})\n```\n\nConfig files use a structured format with `options` and `commands` keys, mirroring the `Cli.create()` / `.command()` hierarchy:\n\n```json\n{\n \"options\": {\n \"verbose\": true\n },\n \"commands\": {\n \"echo\": {\n \"options\": {\n \"upper\": true,\n \"prefix\": \"cfg\"\n }\n },\n \"project\": {\n \"commands\": {\n \"list\": {\n \"options\": {\n \"limit\": 25,\n \"save-dev\": true\n }\n }\n }\n }\n }\n}\n```\n\nPrecedence is `argv > config > zod defaults`. Only command `options` are loaded — `args`, `env`, and built-in commands are unaffected.\n\nUse `incur gen` to auto-generate a `config.schema.json` to distribute with your CLI for consumer autocomplete.\n\n### Filtering output\n\nUse `--filter-output` to prune command output to specific keys. Supports dot-notation for nested keys, array slices, and comma-separated paths:\n\n```ts\ncli.command('users', {\n description: 'List users',\n run() {\n return {\n users: [\n { name: 'Alice', email: 'alice@example.com', role: 'admin' },\n { name: 'Bob', email: 'bob@example.com', role: 'user' },\n { name: 'Carol', email: 'carol@example.com', role: 'user' },\n ],\n }\n },\n})\n```\n\n```sh\n$ my-cli users --filter-output users.name\n# → [3]: Alice,Bob,Carol\n\n$ my-cli users --filter-output users[0,2].name\n# → users[2]{name}:\n# → Alice\n# → Bob\n```\n\n### Token pagination\n\nUse `--token-count`, `--token-limit`, and `--token-offset` to manage large outputs. Tokens are estimated using LLM tokenization rules (~96% accuracy).\n\n```sh\n# Check how many tokens a command produces\n$ my-cli users --token-count\n# → 42\n\n# Limit output to the first 20 tokens\n$ my-cli users --token-limit 20\n# → users[3]{name,email,role}:\n# → Alice,alice@example.\n# → [truncated: showing tokens 0–20 of 42]\n\n# Paginate: get the next page\n$ my-cli users --token-offset 20 --token-limit 20\n# → com,admin\n# → Bob,bob@example.com,\n# → [truncated: showing tokens 20–40 of 42]\n```\n\n### Command schema\n\nUse `--schema` to inspect the JSON Schema for a command's arguments, options, environment variables, and output — useful for code generation, validation, and tooling:\n\n```sh\n$ my-cli install --schema\n# → args:\n# → type: object\n# → properties:\n# → package:\n# → type: string\n# → options:\n# → type: object\n# → properties:\n# → saveDev:\n# → type: boolean\n```\n\nCombine with `--format json` for machine-readable output:\n\n```sh\n$ my-cli install --schema --format json\n```\n\n### Shell completions\n\nEvery incur CLI has a built-in `completions` command that generates 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.\n\n```sh\n# Generate and install completions\neval \"$(my-cli completions bash)\" # add to ~/.bashrc\neval \"$(my-cli completions zsh)\" # add to ~/.zshrc\nmy-cli completions fish | source # add to ~/.config/fish/config.fish\n```\n\nCompletions are dynamic — subcommands, `--options`, short aliases, and enum values are all suggested based on the current command context. Command groups suppress the trailing space so you can keep tabbing into subcommands.\n\nRun `my-cli completions --help` for setup instructions.\n\n## API Reference\n\n> TODO\n\n## License\n\nMIT\n","readmeFilename":""}