Cli

Core CLI creation and management API

Cli.create()

Creates a new CLI application. Can be used to create a single-command CLI with a root handler, or a router CLI that registers subcommands.

Signature

function create<
  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,
>(
  name: string,
  definition?: create.Options<args, env, opts, output, vars>
): Cli<{}, vars, env>

Parameters

name · string · required

The name of the CLI application. Used as the primary command name.

definition · create.Options

Configuration options for the CLI. Omit run for a router CLI that only registers subcommands, or include run to create a leaf CLI with a root command handler.

Show create.Options

args · z.ZodObject<any>

Zod schema for positional arguments. Keys define argument names, schemas define types and validation.

description · string

A short description of what the CLI does. Shown in help text and agent discovery.

env · z.ZodObject<any>

Zod schema for environment variables. Keys are the variable names (e.g. NPM_TOKEN). Parsed before middleware runs.

options · z.ZodObject<any>

Zod schema for named options/flags. Keys define flag names, schemas define types and defaults.

output · z.ZodType

Zod schema for the return value. Used for output validation and type inference.

vars · z.ZodObject<any>

Zod schema for middleware variables. Keys define variable names, schemas define types and defaults.

alias · Record<string, string>

Map of option names to single-char aliases (e.g. { verbose: 'v' }).

aliases · string[]

Alternative binary names for this CLI (e.g. shorter aliases in package.json bin). Shell completions are registered for all names.

examples · Example[]

Usage examples for this command. Shown in help output.

format · 'toon' | 'json' | 'yaml' | 'md'

Default output format. Can be overridden by --format or --json flags.

outputPolicy · 'all' | 'agent-only' · default: "'all'"

Controls when output data is displayed:

• 'all' — displays to both humans and agents
• 'agent-only' — suppresses data output in human/TTY mode while still returning it to agents

Inherited by child commands when set on a group or root CLI.

run · (context) => InferReturn<output> | Promise<InferReturn<output>> | AsyncGenerator

The root command handler. When provided, creates a leaf CLI with a root command. When omitted, creates a router CLI that only registers subcommands.

Show Context

agent · boolean

Whether the consumer is an agent (stdout is not a TTY).

args · InferOutput<args>

Positional arguments parsed according to the args schema.

name · string

The CLI name.

env · InferOutput<env>

Parsed environment variables according to the env schema.

options · InferOutput<options>

Named options/flags parsed according to the options schema.

var · InferVars<vars>

Variables set by middleware. Typed according to the vars schema.

ok · (data, meta?) => never

Return a success result with optional metadata (e.g. CTAs). Calling this short-circuits execution.

error · (options) => never

Return an error result with optional CTAs. Calling this short-circuits execution.

usage · Usage[]

Alternative usage patterns shown in help output.

version · string

The CLI version string. Displayed with --version flag.

mcp · object

Options for the built-in mcp add command.

Show MCP Options

agents · string[]

Target specific agents by default (e.g. ['claude-code', 'cursor']).

command · string

Override the command agents will run to start the MCP server. Auto-detected if omitted.

sync · object

Options for the built-in skills add command.

Show Sync Options

cwd · string

Working directory for resolving include globs. Pass import.meta.dirname when running from a bin entry. Defaults to process.cwd().

depth · number · default: "1"

Default grouping depth for skill files. Overridden by --depth.

include · string[]

Glob patterns for directories containing SKILL.md files to include (e.g. "skills/*", "my-skill").

suggestions · string[]

Example prompts shown after sync to help users get started.

Return Type

Cli · Cli<commands, vars, env>

A CLI application instance. Also used as a command group when mounted on a parent CLI.

Examples

Create a simple router CLI

import { Cli } from 'incur'

const cli = Cli.create('my-cli', {
  version: '1.0.0',
  description: 'My awesome CLI'
})

cli.command('greet', {
  args: z.object({ name: z.string() }),
  run(c) {
    return { message: `Hello ${c.args.name}!` }
  }
})

cli.serve()

Create a CLI with root command

const cli = Cli.create('my-cli', {
  version: '1.0.0',
  args: z.object({ path: z.string() }),
  run(c) {
    return { path: c.args.path }
  }
})

Create CLI with environment variables

const cli = Cli.create('deploy', {
  env: z.object({
    API_TOKEN: z.string(),
    API_URL: z.string().default('https://api.example.com')
  }),
  run(c) {
    // c.env.API_TOKEN is typed and validated
    return { url: c.env.API_URL }
  }
})

Cli Type

The CLI instance returned by Cli.create(). Also used as a command group when mounted on a parent CLI.

Properties

name · string

The name of the CLI application.

description · string | undefined

A short description of the CLI.

vars · z.ZodObject<any> | undefined

The vars schema, if declared. Use typeof cli.vars with middleware<vars, env>() for typed middleware.

env · z.ZodObject<any> | undefined

The env schema, if declared. Use typeof cli.env with middleware<vars, env>() for typed middleware.

Methods

command()

Registers a root command or mounts a sub-CLI as a command group. Returns the CLI instance for chaining.

command<
  const name extends string,
  const args extends z.ZodObject<any> | undefined = undefined,
  const cmdEnv extends z.ZodObject<any> | undefined = undefined,
  const options extends z.ZodObject<any> | undefined = undefined,
  const output extends z.ZodType | undefined = undefined,
>(
  name: name,
  definition: CommandDefinition<args, cmdEnv, options, output, vars, env>
): Cli<...>

Parameters:

name · string · required

The command name. Used to invoke the command.

definition · CommandDefinition

The command definition. See Commands for details.

Mounting a sub-CLI:

command<const name extends string>(
  cli: Cli & { name: name }
): Cli<...>

Parameters:

cli · Cli

A sub-CLI instance to mount as a command group. All subcommands will be namespaced under this CLI’s name.

Examples:

// Register a command
cli.command('greet', {
  args: z.object({ name: z.string() }),
  run(c) {
    return { message: `Hello ${c.args.name}!` }
  }
})

// Mount a sub-CLI as a command group
const pr = Cli.create('pr', { description: 'PR management' })
pr.command('list', {
  run() {
    return { items: [] }
  }
})
cli.command(pr)
// Now available as: my-cli pr list

serve()

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

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

Parameters:

argv · string[] · default: "process.argv.slice(2)"

Command-line arguments to parse. Defaults to process arguments.

options · serve.Options

Options for serve, primarily used for testing.

Show serve.Options

env · Record<string, string | undefined>

Override environment variable source. Defaults to process.env.

exit · (code: number) => void

Override exit handler. Defaults to process.exit.

stdout · (s: string) => void

Override stdout writer. Defaults to process.stdout.write.

Example:

// In your bin entry file
#!/usr/bin/env node
import { cli } from './cli.js'

cli.serve()

use()

Registers middleware that runs around every command.

use(handler: MiddlewareHandler<vars, env>): Cli<commands, vars, env>

Parameters:

handler · MiddlewareHandler

The middleware handler function. See Middleware for details.

Example:

cli.use(async (c, next) => {
  console.log('Before command')
  await next()
  console.log('After command')
})