incur CLI Framework

incur is a CLI framework designed for agentic workflows with the following core features:

• Agent discovery: Built-in Skills and MCP sync (skills add, mcp add) for automatic agent discovery.
• Session savings: Optimized to use up to 3× fewer tokens per session compared to MCP or skill alternatives.
• Call-to-actions: Suggests next commands to both agents and humans after a run.
• TOON output: A token-efficient default output format optimized for agent parsing. Supports JSON, YAML, Markdown, and JSONL alternatives.
• --llms flag: Provides a token-efficient command manifest in Markdown or JSON schema.
• Well-formed I/O: Uses schemas for arguments, options, environment variables, and output.
• Inferred types: Provides generic type flow from schemas to run callbacks without manual annotations.
• Global options: Every CLI automatically includes --format, --full-output, --help, --json, --update, and --version.
• Standalone binaries: Supports building macOS, Linux, and Windows executables.
• Light API surface: Minimalist API consisting of Cli.create(), .command(), and .serve().
• Middleware: Composable before/after hooks with typed dependency injection via cli.use().

You can declare a vars schema on Cli.create() to implement typed dependency injection.

• Declaration: Define the schema using z.object() in the create() options.
• Setting: Use c.set(key, value) within middleware to inject values into the context.
• Accessing: Access injected values via c.var.key within command handlers.
• Defaults: Use .default() in the schema for variables that do not require middleware to initialize.

This pattern is useful for injecting authentication state, request IDs, or configuration throughout your CLI commands.

const cli = Cli.create('my-cli', {
  description: 'My CLI',
  vars: z.object({
    user: z.custom<{ id: string; name: string }>(),
    requestId: z.string(),
    debug: z.boolean().default(false),
  }),
})

cli.use(async (c, next) => {
  c.set('user', await authenticate())
  c.set('requestId', crypto.randomUUID())
  await next()
})

cli.command('whoami', {
  run(c) {
    return { user: c.var.user, requestId: c.var.requestId, debug: c.var.debug }
  },
})

Arguments and options are defined using Zod schemas.

• Arguments are positional and assigned based on the order of keys in the Zod object.
• Options are named flags (e.g., --flag).

Supported features include:

• Aliases: Use the alias property to define short flags (e.g., { state: 's' }).
• Types: Automatic coercion (string $\rightarrow$ number/boolean) and support for arrays (z.array()).
• Defaults: Use .default() for option values.
• Environment Variables: Define an env schema to validate and parse process.env values.

// Arguments (positional)
args: z.object({
  repo: z.string().describe('Repository in owner/repo format'),
  branch: z.string().optional().describe('Branch name'),
})

// Options (named flags)
options: z.object({
  state: z.enum(['open', 'closed']).default('open'),
  limit: z.number().default(30),
  verbose: z.boolean().optional(),
})

// Environment Variables
env: z.object({
  NPM_TOKEN: z.string().optional(),
})

Middleware allows you to register composable before/after hooks using cli.use(). Middleware executes in registration order using an "onion-style" pattern: each middleware must call await next() to proceed to the next handler in the chain.

There are three levels of middleware:

1. Root Middleware: Registered on the main Cli instance via .use(). Runs for all commands.
2. Sub-CLI Middleware: Registered on a sub-CLI instance. Only applies to commands within that sub-CLI.
3. Per-command Middleware: Registered directly on a command definition. Runs only for that specific command and after root/group middleware.

Note: Middleware does not run for built-in commands like --help, --llms, --mcp, mcp add, or skills add.

const cli = Cli.create('deploy-cli', { description: 'Deploy tools' })
  .use(async (c, next) => {
    const start = Date.now()
    await next()
    console.log(`took ${Date.now() - start}ms`)
  })
  .command('deploy', {
    run() {
      return { deployed: true }
    },
  })

To automate the creation and upload of standalone binaries to GitHub Releases, use the wevm/incur/release@v1 action. This action compiles unsigned targets, verifies checksums, tests Linux executables (glibc and musl), and uploads assets including .gz binaries, SHA256SUMS, install.sh, and install.ps1.

Default Behavior:

• Entry point: ./src/bin.ts
• CLI name: Derived from the root package.json.
• Version: The stable version in the root package.json.
• Release target: The latest published GitHub release.

Important Notes:

• The action appends assets to existing releases. If using changesets/action@v1, run Incur after Changesets has published the release.
• The action rejects pull request merge refs; run it from a trusted push or manual workflow.
• It does not sign executables. macOS and Windows users may encounter Gatekeeper or SmartScreen warnings.

name: Binary Release

on:
  workflow_dispatch:

concurrency:
  group: binary-release

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - id: release
        uses: wevm/incur/release@v1