Cli

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.

(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')
})

Core

Utilities

Integrations

Cli.create()

Signature

Parameters

Return Type

Examples

Create a simple router CLI

Create a CLI with root command

Create CLI with environment variables

Cli Type

Properties

Methods

command()

serve()

use()

Build docs developers (and LLMs) love

Core

Utilities

Integrations

​Cli.create()

​Signature

​Parameters

​Return Type

​Examples

​Create a simple router CLI

​Create a CLI with root command

​Create CLI with environment variables

​Cli Type

​Properties

​Methods

​command()

​serve()

​use()

Build docs developers (and LLMs) love

Cli.create()

Signature

Parameters

Return Type

Examples

Create a simple router CLI

Create a CLI with root command

Create CLI with environment variables

Cli Type

Properties

Methods

command()

serve()

use()