--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 aContext.
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.
- Python
- TypeScript
--by, Mirage refuses
the line before acknowledge runs and exits 2:
Command shape
- In
arguments, a dashed name such as--bydeclares an option and a bare name such asINCIDENT_IDa positional. A file operand takestype="path"; a service ID stays a text operand. handlersmaps each leaf’s path below the root to itsCLIHandler:"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 onepre_commandrule can refuse every writing subcommand, and Mirage drops cached mount listings after it runs. - Descriptions on the spec, its options and operands become
--helpandmanat 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,
--helpincluded. - Piped input arrives on stdin, and the entry’s
configas JSON inMIRAGE_CLI_CONFIG. - Its stdout, stderr and exit status become the command’s.
- Without a
machinesentry 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:
- Python
- TypeScript
workspace.yaml
- Only code can install or remove a CLI. The shell has no
installcommand, 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
cliskey.
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.