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 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. The @struktoai/mirage-core/... type
imports need pnpm add @struktoai/mirage-core.
--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_IDdeclares a positional. Declare a file operand withtype: 'path'; a service ID stays a text operand. CLI.handlersmaps each leaf’s path below the root to itsCLIHandler:'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. configModelvalidates each install’s config when you register it. Without one, the CLI takes no config andaccessor.configisnull.- Mark a handler that changes the service
write: true. Policy reads it asCommandContext.write, so onepreCommandmethod 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
--helpandmanat 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.
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:
Files and the session
Build the service client inCLI.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
PathSpecatype: 'path'operand gives you, and derive paths withjoinandparent. For a path string from config, usePathSpec.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, andctx.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.vfsisundefinedwhen your code calls a handler directly; a handler that needs files throwsUsageErrorthen.
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.
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 noconfigModel, 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;
cdinto one. - A read-only subcommand runs on the first mount that has it.
--helpworks from anywhere.- A VFS gives the same tree to every mount of it through its
commandsoption. - 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: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-onlyhostmachine runs CPython with-c, which ownssys.argv[0]. Arguments start at index 1 everywhere. - A script declares no Mirage grammar, so every option reaches it unchanged,
--helpincluded. A script CLI built in code can add aCommandSpecto 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:
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
.jsfile follows its nearestpackage.jsontype;.mjsis always a module. - A
.tsfile 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
registerCliSpecfrom your code.
- 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
installcommand, so an agent can’t remove one. A shell function can still shadow a CLI, as in bash; refuse that with apreCommandpolicy.
clis key.
Snapshots and credentials
A snapshot saves a typed CLI install by its spec name. A Zod objectconfigModel 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’sclisentry. - 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.
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.