Skip to main content
A custom CLI gives an agent your own command, with fixed subcommands and flags: a client for your service, a tool over workspace files, or a script. For a typed CLI, Mirage parses each line, refuses a bad one and generates --help and man. A script CLI is a program that reads its own arguments. A typed CLI declares its grammar with CommandSpec, the same parser Mirage’s built-in commands use, so its --help, error messages and exit codes work the same way as theirs.

Write a typed CLI

A handler gets the same four arguments a shell command’s handler gets: the install’s accessor, the path operands, the text operands and a Context. Mirage builds the accessor once per install from the install’s validated config, and closes it when the install goes. The default NOOPAccessor only holds that config, at accessor.config. The @struktoai/mirage-core/... type imports need pnpm add @struktoai/mirage-core.
One CLI, installed twice, serves two accounts. Without --by, Mirage refuses the line before acknowledge runs and exits 2:
The runnable pager example adds an incident service the handlers change.

Command shape

  • In arguments, a dashed name such as --by declares an option and a bare name such as INCIDENT_ID declares a positional. Declare a file operand with type: 'path'; a service ID stays a text operand.
  • CLI.handlers maps each leaf’s path below the root to its CLIHandler: 'ack', 'incident ack', or '' for a program with no subcommands.
  • Names and aliases are single words, and a group’s children share one set of names. An option can’t repeat in a parent and its child.
  • new CLI(...) refuses a bad tree when you build it, and Mirage refuses a bad line before the handler runs, so a handler never re-checks its flags.
  • Read flags through new FlagView(ctx.flags, ctx.spec). Reading an option the spec doesn’t declare throws, instead of looking like an omitted flag.
  • configModel validates each install’s config when you register it. Without one, the CLI takes no config and accessor.config is null.
  • Mark a handler that changes the service write: true. Policy reads it as CommandContext.write, so one preCommand method can refuse every writing subcommand, and Mirage drops cached mount listings after it runs. It grants no permission.
  • Descriptions on the spec, its options and operands become --help and man at every level.

Output and status

A handler returns [stdout, IOResult]. stdout is a Uint8Array, an AsyncIterable<Uint8Array> for output that arrives in pieces, or null. The IOResult carries the exit status and stderr. Piped input arrives on ctx.stdin as bytes, an async byte source, or null when nothing is piped; materialize reads all of it.
Bound as pager count, pager watch INCIDENT_ID... and pager close INCIDENT_ID: new UsageError(message, exitCode) (exit code 2 by default) prints its message to stderr and sets the exit status, and the rest of the line keeps running. A CLI that prints paths from its own data, as git prints its index, returns rows instead of bytes. Each row names the path it shows. Mirage drops the rows the session can’t see, then calls your renderer with the rest, so no line, count or column width gives a hidden path away:
The renderer runs inside the command’s timeout. A handler returns rows or stdout, not both.

Files and the session

Build the service client in CLI.accessor, from the install’s config, so every call on one install shares one client. Don’t look for a matching VFS to borrow its credentials or accessor; share core service functions and accessor classes between a CLI and a VFS instead. ctx.vfs is the session’s files, with workspace policy and mount modes applied: read, write, stat, readdir, symlink, readlink and the rest, the same API as session.vfs.
  • Keep the PathSpec a type: 'path' operand gives you, and derive paths with join and parent. For a path string from config, use PathSpec.fromStrPath(value, undefined, ctx.cwd).
  • ctx.vfs.stat(path, undefined, { nofollow: true }) reports a link itself.
  • ctx.vfs.mountOf(path) names the mount serving a path, ctx.vfs.isMount(path) says whether a path is a mount root, and ctx.vfs.submounts(path) lists the mounts below a folder. A mount the session hides shows as the nearest folder above it that the session sees, so a CLI that removes a folder can refuse without learning the hidden name.
  • ctx.vfs is undefined when your code calls a handler directly; a handler that needs files throws UsageError then.
After an install’s write, Mirage drops the caches of every mount its accessor may reach, even when the write failed, since it may still have reached the service. Implement reaches(peer) on your accessor to return false for a mount’s accessor your writes can’t change; an accessor without it reaches every mount. A script CLI marked as a write drops them too, since Mirage can’t see what it touched. A CLI with no config that works on files, such as git, needs none of this: Mirage drops the cache of each path it writes. ctx.env is a copy of the environment taken when the command starts. ctx.session reads and writes the live session under the shell’s rules, so writing a readonly or hidden variable fails. Reads are plain calls. Writes return promises: await them, or a failure goes unseen.
After pager-eng login, echo $PAGER_ACCOUNT prints engineering. If PAGER_ACCOUNT is readonly, the command exits 1 with pager-eng login: PAGER_ACCOUNT: readonly variable. To run another command from a handler, use await ctx.shell(line); see Context.

On a mount

A typed CLI registered on a mount runs its subcommands there, with the mount’s accessor, so it declares no configModel, accessor or script:
notes tag /notes/a.md draft parses, shows help and refuses bad flags the same way an installed CLI does.
  • It runs on the working directory’s mount when that mount has notes.
  • Otherwise a writing subcommand runs on the only writable mount that has it. With two, Mirage refuses the line and names both; cd into one.
  • A read-only subcommand runs on the first mount that has it.
  • --help works from anywhere.
  • A VFS gives the same tree to every mount of it through its commands option.
  • Its handlers reach the backend directly, without Mirage’s file layer. A writing one must declare write: true; it runs only on a writable mount, and Mirage drops cached listings after it.

Script CLIs

A script CLI is a program file that reads its own arguments and needs no Mirage imports:
It runs on the machine its entry names, as Script CLIs describes; without a machines entry for its language it exits 127. Mirage embeds the file when the workspace loads.
  • Words after the command name arrive as argv. On Pyodide, Monty and QuickJS, argv[0] is the installed name, so two installs can tell themselves apart; the Node-only host machine runs CPython with -c, which owns sys.argv[0]. Arguments start at index 1 everywhere.
  • A script declares no Mirage grammar, so every option reaches it unchanged, --help included. A script CLI built in code can add a CommandSpec to get Mirage’s parsing and help.
  • Piped input arrives on stdin.
  • Config arrives as JSON in MIRAGE_CLI_CONFIG, alongside the session’s environment. Changes the program makes to its environment stay with it.
  • Its stdout, stderr and exit status become the command’s.
  • A script CLI takes no configModel, subcommands or handlers.
Pyodide, Monty and QuickJS read and write workspace files but have no network and no Node builtins. Use the Node-only machine: host to run the host’s own interpreter when the script needs more.

Install it

ws.registerCli(name, cli, config) installs a typed or script CLI under name. The agent types that name, pager-eng, not the spec’s name, pager. To install a typed CLI from workspace YAML, register its spec first, then load the workspace:
A script CLI needs no registration: its entry names the file with script:, as in Script CLIs. cli: can also point at ./file.mjs:ATTR or a package reference such as my-clis/specs:PAGER; a relative file resolves next to the YAML file.
  • A .js file follows its nearest package.json type; .mjs is always a module.
  • A .ts file runs through Node’s type stripping, not compilation, so build first if it uses syntax that needs transforming.
  • TypeScript has no entry points like Python’s. Use a package reference, or call registerCliSpec from your code.
Registration follows these rules:
  • A registered name or a builtin wins over a file or package reference.
  • Registering a name another registration or a builtin already holds fails.
  • Only your code can install or remove a CLI. The shell has no install command, so an agent can’t remove one. A shell function can still shadow a CLI, as in bash; refuse that with a preCommand policy.
See CLI entries for every clis key.

Snapshots and credentials

A snapshot saves a typed CLI install by its spec name. A Zod object configModel also says what to redact; mark each string credential with secretStr():
  • Loading the snapshot needs fresh config for that install through clis; Mirage refuses to restore a redacted credential as if it were real.
  • The loading process must also resolve the spec name, or pass [cli, config] as that install’s clis entry.
  • A normalizer function also works as configModel, but Mirage can’t see inside its result, so the snapshot saves it as it is. Use a Zod object for config that holds credentials.
  • Workspace.copy() carries a CLI installed in code, with its real config.
A script CLI’s snapshot embeds the script, and saves its config as it is, since there is no config model to mark secrets. Keep credentials in the environment, or pass fresh config through clis when loading.

Reference

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

CLI and CLIHandler

CommandSpec

Argument

The names follow argparse, which Mirage supports in part. Positionals take no default, and options take no variable count. append collects one value per use; extend flattens fixed groups. The other fields of CommandSpec and Argument describe shell builtins’ grammars, such as tar’s old-style options; a CLI doesn’t need them.

Context