CLI and CLIHandler,
and CommandSpec and Argument.
CLI and CLIHandler
| Field | Meaning |
|---|---|
CLI.spec | The root CommandSpec. |
CLI.handlers | Each leaf’s path mapped to its CLIHandler. |
CLI.configModel | The Zod schema, or a normalizer function, each install’s config must pass. |
CLI.accessor | Builds the install’s accessor from its config, once per install; Mirage closes it when the install goes. Default NOOPAccessor. |
CLI.script, CLI.machine, CLI.runtime | The embedded script, the machine type that runs it (in_process, the default in code, or host) and the runtime there, if named. A CLI without a script runs on in_process only. |
CLIHandler.fn | The handler, called as fn(accessor, paths, texts, ctx). |
CLIHandler.write, CLIHandler.limit | Whether the handler changes the service, and its execution limit. |
CLIHandler.writeWhen | Options that make an otherwise read-only leaf a write on the line that passes them, as himalaya message read --seen marks mail read. |
CommandSpec
| Field | Meaning |
|---|---|
name, aliases | The command word, and other words for a subcommand. |
subcommands | A group’s children. |
arguments | Options and positionals; a group’s options pass to its leaves. |
description, epilog | Help text, and text after it. |
usageStyle | How help and refusals read: argparse, Git, clap, Cobra or poppler. Cobra leaves a missing positional to the handler. poppler answers an option error with the help page and exit 99. |
allowAbbrev | Whether a unique prefix of a long option counts as the option. |
Argument
| Field | Meaning |
|---|---|
| Names | One positional name, or one or more dashed option spellings. |
type | str (default), int, float, or path for a workspace path. |
action | store (default), store_true, count, append, or extend. |
nargs | One value by default; ? for optional or an integer for a fixed count. Positionals also take *, + or REMAINDER; only one positional may take a variable count, and it must come last. |
choices | The allowed values. |
required | Whether an option must be given; a positional’s count comes from nargs. |
default, env | An option’s fallbacks; a value from the environment counts as given. |
help, metavar | Help text, and the value’s name in help. |
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
| Argument or field | Holds |
|---|---|
accessor | The install’s accessor. The default NOOPAccessor holds the validated config at accessor.config (null without a config model). |
paths | The path operands, resolved against the working directory. |
texts | The text and number operands, in declaration order. |
ctx.argv | The words after the command name as typed, subcommands included. |
ctx.flags | Group and leaf flags keyed by option name, --dry-run as dry_run. |
ctx.spec | The leaf’s CommandSpec. |
ctx.stdin | Piped bytes, an async byte source, or null. |
ctx.cwd | The session’s working directory. |
ctx.env | A copy of the environment taken when the command starts. |
ctx.vfs, ctx.session | The session’s files and live session; absent outside a workspace. |
ctx.shell | await ctx.shell(line) runs another line in the calling session and returns its IOResult. Calling it after the command returns raises an error. |
ctx.processes | The session’s processes, as ps and jobs see them. |
ctx.ids | The workspace’s source of generated names and random values, so a seeded workspace replays them. |
ctx.signal | Aborts when the line is cancelled or times out. |
ctx.runtime, ctx.diff, ctx.find | Not set for a CLI; they serve interpreter commands, diff and find. Run code through ctx.shell instead. |