> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom CLI Reference

> The fields of CLI, CLIHandler, CommandSpec, Argument and Context, for writing a custom CLI.

[Adding a New CLI](https://docs.mirage.strukto.ai/python/cli/new.md) shows how to write one.

The constructors document exact types and defaults:
[`CLI` and `CLIHandler`](https://github.com/strukto-ai/mirage/blob/main/python/mirage/commands/cli/types.py),
and [`CommandSpec` and `Argument`](https://github.com/strukto-ai/mirage/blob/main/python/mirage/commands/spec/types.py).

## `CLI` and `CLIHandler`

| Field | Meaning |
| - | - |
| `CLI.spec` | The root `CommandSpec`. |
| `CLI.handlers` | Each leaf's path mapped to its `CLIHandler`. |
| `CLI.config_model` | The Pydantic model each install's config must match. |
| `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.write_when` | 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. |
| `usage_style` | 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. |
| `allow_abbrev` | 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. |

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`

| Argument or field | Holds |
| - | - |
| `accessor` | The install's accessor. The default `NOOPAccessor` holds the validated config at `accessor.config` (`None` 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 `None`. |
| `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; `None` 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.runtime`, `ctx.diff`, `ctx.find` | Not set for a CLI; they serve interpreter commands, `diff` and `find`. Run code through `ctx.shell` instead. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.