Customize CLI

Define a custom CLI when an agent needs service operations with a stable command grammar. Use a typed CLI for parsed commands and generated help, or a script CLI when the program should parse its own arguments. Shell builtins and CLIs keep separate catalogs and dispatch. Both use CommandSpec for argument parsing.

Define a typed command

Each handler receives one CLIInvocation. The example below shows the registration and parsing contract; the runnable pager example adds a mutable incident service and shared cross-language coverage.

import {
  Argument,
  CLI,
  CLIHandler,
  CommandSpec,
  type CLIInvocation,
  IOResult,
  Workspace,
  z,
  type CommandFnResult,
} from '@struktoai/mirage-node'
import { FlagView } from '@struktoai/mirage-core/commands/spec/index'

const PagerConfigSchema = z.strictObject({ account: z.enum(['engineering', 'support']) })
type PagerConfig = z.infer<typeof PagerConfigSchema>

function acknowledge(inv: CLIInvocation): CommandFnResult {
  const { account } = inv.config as PagerConfig
  const incidentId = inv.texts[0]
  const by = new FlagView(inv.flags, inv.spec).asStr('by')
  return [
    new TextEncoder().encode(`[${account}] acknowledged ${incidentId} by ${by}\n`),
    new IOResult(),
  ]
}

const PAGER = new CLI({
  spec: new CommandSpec({
    name: 'pager',
    subcommands: [new CommandSpec({
      name: 'ack',
      arguments: [
        new Argument('INCIDENT_ID'),
        new Argument('--by', { required: true }),
      ],
    })],
  }),
  handlers: { ack: new CLIHandler({ fn: acknowledge, write: true }) },
  configModel: PagerConfigSchema,
})

const ws = new Workspace({})
ws.registerCli('pager-eng', PAGER, { account: 'engineering' })
ws.registerCli('pager-support', PAGER, { account: 'support' })

The same CLI can be installed for multiple accounts. Service IDs use textual operands; file operands use type: 'path'. Read flags through new FlagView(inv.flags, inv.spec) so a read of an undeclared option fails rather than looking like an omitted flag.

Choose the command shape

Node	Declares	Handler input
Leaf	`CommandSpec.arguments`, a `CLIHandler` binding	Parsed flags, paths and text on `inv`
Group	`subcommands`, optional inherited options	Dispatches to a leaf
Script CLI	`CLI.script`, optional runtime	Raw argv, stdin and environment

A typed node is a leaf or a group. Names and aliases are single words; child names and aliases share one namespace. Options cannot collide across ancestors and descendants. Construction validates the tree and compiles the grammar; do not repeat parser validation in every handler. CommandSpec.arguments holds options and positional arguments: a dashed name such as --by declares an option; a bare name declares a positional. CLI.handlers maps canonical paths below the root to CLIHandler bindings, such as "ack", "incident ack", or "" for a single-command program. Declare configModel on the account CLI. Registration validates each installation, and inv.config holds that account’s settings. Without a config model, a typed CLI accepts no config and receives null. Mark mutating CLIHandler bindings write: true. This classifies the command for policy and cache invalidation; it does not grant permission or perform the mutation. Descriptions, options and operands supply --help and man at every level.

Register the program

Installing a CLI directly is the shortest path:

ws.registerCli('pager-eng', PAGER, { account: 'engineering' })

The installed name is the dispatch key and does not have to equal the spec’s root name. This is what makes one tree usable for several accounts. To resolve a bare name from workspace YAML, register the CLI before loading the workspace:

import { registerCliSpec } from '@struktoai/mirage-node'

registerCliSpec(PAGER)

clis:
  pager-eng:
    cli: pager
    config:
      account: engineering

The Node config loader also accepts ./file.mjs:ATTR and package references such as my-clis/specs:PAGER. Relative files resolve next to the YAML file. A .js file follows its nearest package.json type; .mjs is unambiguous. A .ts file uses Node’s type stripping, not compilation, so syntax requiring transformation must be built first. Registered names and builtins win over direct references. A name collision fails rather than silently replacing another program. TypeScript has no Python entry-point discovery equivalent; use a package reference or call registerCliSpec from the host. Registration and installation are host-side lifecycle operations. There is no shell install or uninstall command, so an agent can use a CLI it was given but cannot remove it. A deployment that must pin the head word should enforce that with policy; shell functions can otherwise shadow it like they do in bash.

Use workspace files

Build the service client from inv.config. A CLI should not find a matching VFS to obtain credentials or a backend accessor. Reuse core service functions between CLI and VFS implementations where their behavior is the same. For file arguments such as uploads or attachments, use inv.view:

Entry point	Purpose
`dispatch`	Read, write and other filesystem operations with workspace policy and mount modes
`statPath`	Classify paths, including directories represented by prefix stores
`ns`	Namespace facts such as symlinks, mount boundaries and attributes
`sessionView`	Live, gated session reads and writes; `inv.env` is the frozen invocation snapshot

Declare file options and operands with type: 'path'; preserve the resulting PathSpec values when dispatching. Use PathSpec.fromStrPath(value, undefined, inv.cwd) for a path string from config, and derive paths with join and parent. Do not convert them to plain strings before filesystem access. Direct handler callers may omit the view; a handler requiring files must refuse when the needed entry point is absent. Account CLI writes, including failed writes that may have reached the service, expire mounted caches. Config-free filesystem CLIs rely on the dispatcher’s per-path invalidation. A script marked as a write also expires caches because its config and service access are opaque.

Snapshots and credentials

A named typed CLI is saved by spec name. A Zod object configModel doubles as the redaction schema; mark string credentials with secretStr(). Loading a snapshot with redacted fields must provide fresh install config through clis; Mirage refuses to restore redacted credentials as if they were usable values.

import { secretStr, z } from '@struktoai/mirage-node'

const ConfigSchema = z.object({ token: secretStr(), account: z.string() })

A normalizer function is also accepted as configModel, but its result is opaque to snapshot redaction and is serialized as-is. Prefer a Zod object for credential-bearing config. The loading process must also make the spec name resolvable, or pass [cli, config] as that install’s clis override. Workspace.copy() carries the live CLI and config together, including a tree installed directly in code. A script CLI is different: the script source is embedded in the snapshot and its opaque config is serialized verbatim because there is no config model to identify secrets. Keep credentials in the environment, or provide fresh script config through clis when loading.

Script CLIs

Use script: when the program should own its grammar or should have no Mirage imports:

clis:
  pager:
    script: ./cli/pager.py
    runtime: pyodide
    config:
      width: 80

The file is embedded at load. Words after the head arrive as argv, piped input arrives on stdin, and config arrives as JSON in MIRAGE_CLI_CONFIG. The program’s stdout, stderr, and exit status become the shell result. A script CLI cannot declare configModel, subcommands, or function handlers; it parses and documents its own options, including --help. Slot 0 is the installed name on pyodide, monty, and quickjs, so two installs can identify themselves and user-facing errors can name the invoked program. The Node-only local runtime runs CPython with -c, which owns sys.argv[0]; arguments still begin at index 1. A YAML script declares no Mirage grammar, so every option reaches the program unchanged. A script CLI constructed in code may supply a CommandSpec to opt into Mirage parsing and generated help. Runtime argument spellings differ:

Runtime	Arguments	Standard input
pyodide	`sys.argv`	`sys.stdin`
monty	`argv` global	`stdin` global
quickjs	`scriptArgs`	`std.in`

The sandboxed runtimes provide files plus compute, not arbitrary networking or Node builtins. The Node-only local runtime selects the host interpreter when that broader authority is intentional.

Authoring reference

The public constructors document exact types and defaults: CLI and CLIHandler, and CommandSpec and Argument.

`CLI` and `CLIHandler`

Field	Authoring meaning
`CLI.spec`	Root `CommandSpec` describing the program’s grammar.
`CLI.handlers`	Canonical leaf paths mapped to `CLIHandler` bindings.
`CLI.configModel`	Zod schema or normalizer for per-install account validation.
`CLI.script`, `CLI.runtime`	Embedded script and optional runtime; used instead of typed handlers.
`CLIHandler.fn`	Leaf handler, called as `fn(inv)`.
`CLIHandler.write`, `CLIHandler.limit`	Mutation classification and optional execution-limit category.

`CommandSpec`

Field	Authoring meaning
`name`, `aliases`	Command word and alternate subcommand words.
`subcommands`	Child nodes for a group.
`arguments`	Options and positional arguments; group options are inherited by leaves.
`description`, `epilog`	Help text and trailing help text.
`usageStyle`	Root help and refusal dialect: argparse, Git, clap or Cobra. Cobra keeps standard help and option errors; handlers own missing positional refusals.
`allowAbbrev`	Whether unique long-option prefixes are accepted.

`Argument`

Field	Authoring meaning
Names	One positional name, or one or more dashed option spellings.
`type`	`str` (default), `int`, `float`, or virtual `path`.
`action`	`store` (default), `store_true`, `count`, `append`, or `extend`.
`nargs`	One value by default; `?` for optional or an integer for fixed arity. Positionals also accept `*`, `+`, or `REMAINDER`.
`choices`	Allowed values, validated by the parser.
`required`	Require an option; positional arity comes from `nargs`.
`default`, `env`	Option fallbacks; an environment value counts as supplied.
`help`, `metavar`	Help description and displayed value name.

This follows argparse’s naming conventions and supports a subset of its features. Positional defaults and variadic options are unsupported; append collects single option values, while extend flattens fixed groups.

`CLIInvocation`

Field	Handler view
`config`	This installation’s validated config, or `null`.
`argv`	Verbatim words after the installed head word, including subcommands.
`paths`	Cwd-resolved path operands.
`texts`	Textual and numeric operands in declaration order.
`flags`	Group and leaf flags keyed by normalized property name.
`stdin`	Piped bytes or an async byte source, or `null`.
`env`	Frozen environment snapshot for this invocation.
`view`	Optional workspace state-plane access for verbs that explicitly need it.

Verify a custom CLI

Check help, successful execution, a refusal and isolation between two account installations. Exercise VFS access with path and mount policy, and verify snapshot restoration with credentials supplied again. Keep service request construction and internal edge cases in unit tests; put observable shell results in shared integration cases when both hosts implement the program. The shared grammar also serves shell commands. Prefer its existing argparse and POSIX concepts; keep a program-specific rule in its handler, or use a script when the whole program needs to own parsing.

Getting Started

Access

AI Agents

VFS

CLIs

Watch

Runtimes

Define a typed command

Choose the command shape

Register the program

Use workspace files

Snapshots and credentials

Script CLIs

Authoring reference

`CLI` and `CLIHandler`

`CommandSpec`

`Argument`

`CLIInvocation`

Verify a custom CLI

​Define a typed command

​Choose the command shape

​Register the program

​Use workspace files

​Snapshots and credentials

​Script CLIs

​Authoring reference

​CLI and CLIHandler

​CommandSpec

​Argument

​CLIInvocation

​Verify a custom CLI

Define a typed command

Choose the command shape

Register the program

Use workspace files

Snapshots and credentials

Script CLIs

Authoring reference

`CLI` and `CLIHandler`

`CommandSpec`

`Argument`

`CLIInvocation`

Verify a custom CLI