Skip to main content
A custom CLI gives an agent your own command: 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, with the same parser its built-in commands use. A script CLI is a program that reads its own arguments.

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.
One CLI, installed twice, serves two accounts. Without --by, Mirage refuses the line before acknowledge runs and exits 2:

Command shape

  • In arguments, a dashed name such as --by declares an option and a bare name such as INCIDENT_ID a positional. A file operand takes type="path"; a service ID stays a text operand.
  • handlers maps each leaf’s path below the root to its CLIHandler: "ack", "incident ack", or "" for a program with no subcommands.
  • Read flags through FlagView. Reading an option the spec does not declare raises an error, instead of looking like an omitted flag.
  • config_model (configModel) validates each install’s config when it is registered. Without one, the CLI takes no config.
  • Mark a handler that changes the service write. Policy reads it, so one pre_command rule can refuse every writing subcommand, and Mirage drops cached mount listings after it runs.
  • Descriptions on the spec, its options and operands become --help and man at every level.

Script CLIs

A script reads its own arguments and needs no Mirage imports. Name it in the workspace config, with a machine that runs its language:
workspace.yaml
hello.py
hello sam prints hi sam.
  • Words after the command name arrive as argv, from index 1. Every option reaches the script unchanged, --help included.
  • Piped input arrives on stdin, and the entry’s config as JSON in MIRAGE_CLI_CONFIG.
  • Its stdout, stderr and exit status become the command’s.
  • Without a machines entry for its language, it exits 127.
Monty, WASI and QuickJS read and write workspace files but have no network and no extra packages. Pyodide loads packages, and in a browser its worker keeps fetch; see its containment. machine: host runs the host’s own interpreter when the script needs more.

Install it

register_cli (registerCli) installs a CLI under a 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:
workspace.yaml
  • Only code can install or remove a CLI. The shell has no install command, so an agent can’t remove one.
  • A registered name or a builtin wins over a file reference, and registering a name a builtin already holds fails.
  • CLI entries lists every clis key.

SDK guides

Python

Output and streams, files and the session, entry points, snapshots and the full reference.

TypeScript

Output and streams, files and the session, file references, snapshots and the full reference.