<!-- AUTO-GENERATED by codegen-cli.py — do not edit -->
# i9 CLI Reference

Machine readers: `i9 --json help` prints the full command tree and
`i9 --json help <command>` one command's flags, examples and exit codes.

## Global Flags

| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--json` |  | boolean | False | Machine-readable JSON output |
| `--quiet` | -q | boolean | False | Errors only, each with its one fix line: no other guidance or progress lines. Accepted before or after the verb |
| `--verbose` |  | boolean | False | Also print diagnostics: subsystem notices, trace archive paths, config echoes. Accepted before or after the verb |
| `--help` | -h | boolean | False | Print help for this command and exit |
| `--version` | -v | boolean | False | Print version info (top level only) |
| `--help-all` |  | boolean | False | Show all commands including advanced and hidden |
| `--config` |  | string |  | Config file path override |
| `--home` |  | string |  | i9 home directory override |
| `--data` |  | string |  | Data root override — traces, archives and caches (default: the i9 home) |
| `--debug` |  | boolean | False | Diagnostic stderr output, and per-request guest-agent detail in the VM's trace |
| `--no-trace` |  | boolean | False | Disable trace-span persistence for this invocation |
| `--trace-gc-max-bytes` |  | integer |  | Byte cap for automatic trace retention, this invocation only: over it, the oldest finished traces of other runs are removed. Overrides the trace.retention_max_bytes config key (default 4294967296) |

## Exit codes

A refusal ends `i9` with one of these statuses and prints `error: <what happened>` on
stderr, then `hint: <what to do>` when i9 knows the fix. Under `--json` it is one
envelope, `{"error":{"code":"<NAME>",…}}`. A status that is not an error code carries
no envelope. Each verb's section lists the statuses it returns.

| Status | Name | The same command can succeed again | Meaning |
|--------|------|------------------------------------|---------|
| 0 | `SUCCESS` |  | Success |
| 1 | `EINTERNAL` | no | i9's own defect; the hint names the diagnostic verb to run |
| 2 | `EUSAGE` | no | The invocation is malformed; the hint is the corrected line |
| 3 | `ENOTFOUND` | no | The named session, archive, path or page does not exist |
| 4 | `EVALIDATION` | no | The input exists and is not acceptable |
| 5 | `ENETWORK` | yes | A network step failed |
| 6 | `EREFUSED` | no | A cap, tier or trust refusal; the hint names what lifts it |
| 7 | `ESERVER` | yes | The session server refused, failed to start or is absent |
| 8 | `EPLATFORM` | no | This host cannot do it; the hint names a host that can |
| 9 | `ENVELOPE_VIOLATED` |  | A measured value fell outside its declared envelope |
| 10 | `RATCHET_REGRESSED` |  | A ratchet floor regressed; the floor was not moved |
| 11 | `EVMPAUSED` | no | The VM is paused; `vm resume` lifts it |
| 12 | `EVMUNREACHABLE` | no | The VM can never answer again (its VM process exited, its parent was restored or destroyed, or its backing object failed), but the snapshots it saved are intact: `i9 run <snapshot>` boots one and `vm stop --discard` frees its slot |
| 13 | `EVMBUSY` | yes | The VM is busy with a save or rewind; wait for it to finish, then run the command again |
| 14 | `EVMINTERRUPTED` | yes | A rewind replaced the VM while the command was running; it did not finish, so run it again on the restored VM only if what it had already done outside the VM (a push, a request) is safe to repeat |
| 15 | `ENOSPACE` | no | The disk holding the i9 home is full; free space there (or remove snapshots with `snapshot rm`), then run the command again |
| 42 | `NOT_IMPLEMENTED` |  | Not implemented by this backend or mode |
| 75 | `SKIPPED` |  | Skipped because this host cannot run it |
| 99 | `CHECKPOINT_REQUEUE` |  | Checkpointed on a signal; the caller requeues from the archive |
| 134 | `ABORTED` |  | Aborted by the panic hook (SIGABRT); there is no clean exit |

Any other status is the guest command's own exit status, passed through unchanged with no error envelope; a guest that itself exits with a number in this table looks like that error by status alone, so tell them apart by i9's `error:` line on stderr, or under --json by the error envelope against the result's `exitCode` and `timedOut`.

## Commands

### `i9 run`

Run a VM image as a live session, from a URL or a local path

Run a VM image as a live session. The target is a URL, or a local
*.i9io / *.aio path, to a self-bootable image: `i9 run https://…`
restores it and serves it from this one binary — no flags, no
sidecar. A VM-image manifest URL
(`i9 run https://a.i9.io/vm/manifest.json`) resolves to this host's
image first: the manifest's `images.<arch>.url` for the arch this
binary runs on, refused by name when the manifest has none. An image
can require a newer i9: one whose `format` is a newer snapshot format
generation than this i9 reads is refused before any of it is fetched,
with exit 6 and a hint naming `i9 update`.

A session prints its control URL as the last line of stdout (the one
`{"session":…}` object under `--json`), so `URL=$(i9 run <image> --detach)`
captures it; the ready block and next steps go to stderr.

`run` starts sessions only.

```
i9 run [target] [cmd] [--egress <deny|warn|allow>] [--allow <string>] [--secret <string>] [--secrets-profile <string>] [--session] [--publish <string>] [--name <string>] [--port <integer>] [--host <string>] [--memory <integer>] [--vcpus <integer>] [--nested-virt] [--detach]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--show-token` | boolean |  | Print the VM's control URL with its bearer token, for a caller on another machine. Without it the URL is printed without the token on a terminal, a pipe and --json alike, and a vm verb given that URL takes the token from this machine's own registry |
| `--secret-budget` | string |  | Cap the requests this VM may spend a proxy secret on: NAME=N, repeatable; NAME must also be given with --secret. Each VM counts its own requests, so a fork child never spends its parent's |
| `--secrets-profile` | string |  | The secretspec.toml profile to admit (default: default). A secretspec.toml in the working directory is admitted before the run: its references and defaults are stored, and every secret it grants is given as --secret; a run it would refuse stops before anything is pulled. `i9 secret check` shows the plan |
| `--quiet` | boolean |  | Suppress progress output (errors are still printed) |

**Network flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--egress` | enum: deny, warn, allow |  | Egress policy for the guest NIC: deny refuses anything not allowed, warn permits and records, allow restricts nothing but the host's own networks (LAN, VPN, loopback), which every mode refuses unless a literal --allow names them. From inside the guest the host is its default gateway (ip route shows it) |
| `--allow` | string |  | Permit egress to `<host>` or <host:port>; repeatable; with no --egress it means --egress deny. Enforced by a DNS proxy plus a connect-site check, so raw-IP connects and DNS rebinding are covered too, and by the name a connection carries: a TLS server name or HTTP Host that is not allowed is refused even on an allowed host's shared address; a protocol that carries no name is allowed by address, and its trace says so; a literal address (192.168.1.20:22) is how a host-network destination is opened, and --allow 127.0.0.1:`<port>` opens the host's loopback port to the guest through its default gateway (localhost is a name and opens nothing, so it is refused) |

**Container flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--secret` | string |  | Give the entrypoint a stored secret by name (NAME or NAME,NAME), repeatable; values never appear on the command line |

**Session flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--session` | boolean | False | Start a session: a local terminal attach (interactive stdin) or the agent API — chosen from the image, --terminal and the terminal behind stdin |
| `--publish` | string |  | --session port forward HOST:GUEST[/proto] (default tcp); repeatable |
| `--name` | string |  | --session: a memorable name for this sandbox. The name is claimed atomically before anything boots: a live sandbox already running under it is reused (its control URL is printed, no duplicate boot), and a run that loses a concurrent race while the winner is still starting is refused by name (exit 1, the winner's pid in the message). Look it up later with `i9 vm ls`. |
| `--port` | integer |  | Port for the session HTTP server |
| `--host` | string |  | Bind address for the session HTTP server: a loopback address or localhost |
| `--no-viewer-gate` | boolean | False | Bring up the guest agent immediately instead of deferring it (scripted and detached runs) |
| `--terminal` | boolean | False | Drop into an interactive shell inside the VM (a headless/agent image selects this automatically) |
| `--snapshot-dir` | string |  | Base directory snapshots go in (default snapshots/ under the i9 home: --home, else $I9_HOME, else ~/.i9): where the session writes them and what GET /api/agent/snapshots enumerates; also bounds the paths /api/agent/snapshot and /api/agent/restore will accept. Resolved and created before the VM boots, so a bad path refuses up front rather than after the guest is running. |
| `--shell` | string |  | Shell to spawn in the VM for the terminal run-mode (default /usr/local/bin/i9-shell if present, else /bin/bash) |
| `--guest-agent-timeout-ms` | integer |  | Readiness deadline (ms) for the guest-agent wait gate (default 120000) — diagnostic override for a slow-boot config |
| `--detach` | boolean | False | Fire-and-forget: a VM image with --session exits 0 once the session prints its control URL, leaving it running under its own process group with a filtered environment: the session, locale, proxy, CA-bundle and I9_ variables, never the launching shell's other variables (startup log: `<home>`/detach/`<pid>`.log, reported by --json; the newest 20 logs of exited sessions are kept, alongside every still-running session's own log) |

**Resources flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--memory` | integer |  | Guest memory in MiB. The published VM image resumes from a checkpoint captured at 2048 MiB / 2 vCPUs; a different size boots it from scratch instead of resuming it, which takes longer, and the checkpoint's memory is not resumed. A boot from scratch needs userfaultfd on Linux just as a resume does |
| `--vcpus` | integer |  | Number of virtual CPUs. The published VM image's checkpoint was captured with 2; a different count boots it from scratch instead of resuming it, at the cost given under --memory |
| `--cpus` | integer |  | Alias for --vcpus |

**VMM flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--nested-virt` | boolean | False | Let the guest run its own VMs: it gets a working /dev/kvm. Needs the nested-virt grant feature (i9 grant request --feature nested-virt) and a host that can nest: an Apple M3 or later on macOS 15+, Linux arm64 booted kvm-arm.mode=nested on FEAT_NV2 silicon, or Linux x86 with kvm_intel/kvm_amd nested=1; any other host refuses by name. A checkpoint captured without it cannot gain it, so the image boots from scratch instead of resuming. On a Mac a nested VM uses about 10x the host resources of a plain VM (about 12 per Mac vs about 125) |
| `--vmm-cpu-template` | string |  | Clip the guest's CPUID to a portable generation (e.g. T2S) so a capture taken here restores on a narrower host. Applied before the guest dispatches, which is the only sound direction |
| `--trace-level` | enum: info, debug, trace |  | What this run's trace archive keeps of i9's own high-rate internals: info writes their counters, debug or trace also every span they count. Also `trace.level` |

**Examples:**

- Warm-restore the published VM image and stream it: `i9 run https://a.i9.io/vm/manifest.json`
- Boot a local VM image as a headless session and print its control URL: `i9 run ./agent-dev.boot.i9io --session`
- Boot a VM image and drop into a shell inside it: `i9 run ./agent-dev.boot.i9io --terminal`
- Boot with a named sandbox and a published port: `i9 run ./agent-dev.boot.i9io --session --name dev --publish 8080:80`

**Exit codes:**

- `0`: The session ended, or the command run inside it exited 0
- `1`: Runtime error
- `2`: Missing target, or a target this build cannot run
- `3`: The VM image or archive named does not exist
- `4`: The archive named is not a complete snapshot (truncated, unsealed or unreadable); `i9 archive validate` gives the full report
- `7`: The session server could not start, such as a --port another listener already holds
- `8`: The archive named exists but cannot be read, or the host has no usable home or snapshot directory

### `i9 update`

Update this binary to the current release

Replace this i9 binary with the release published for its platform.
i9 is one file, so an update is one file. The verb reads the release's
release.json and refuses it unless a release key compiled into this
binary signed it; the signed sha256 is what the download must match.
It hashes the running executable and stops when they match; otherwise
it downloads the release next to the executable, verifies the signed
digest over the bytes it received, and renames the download into
place — the installed binary is untouched until the digest checks
out. A release whose withdrawal is signed is refused, and so is one
older than the installed binary unless `--allow-downgrade` is passed.
On the stable channel (the default) the release is the one the live VM
image names for this CPU (https://a.i9.io/vm/manifest.json), so the
host binary and the agent inside the guest stay one build — the
release the installer pins. `--channel edge` (or the `update.channel`
config key) follows every published release instead. Setting the
`update.url` config key names a release prefix; it changes where the
release is read, not what is trusted. `--home`/`--config` pick the
config it reads. `--json` reports which: `source` is `manifest`,
`edge` or `config`.

```
i9 update [--check] [--force] [--channel <stable|edge>] [--allow-downgrade]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--check` | boolean | False | Report whether this binary is the release the VM image names (or update.url names); install nothing |
| `--force` | boolean | False | Download and reinstall the release even when the installed binary already matches it |
| `--channel` | enum: stable, edge |  | The release channel: stable (the release the VM image names, the default) or edge (every published release); overrides update.channel |
| `--allow-downgrade` | boolean | False | Install the release even when it is older than this binary |

**Examples:**

- Install the current release: `i9 update`
- Only report whether one is available: `i9 update --check`

**Exit codes:**

- `0`: Up to date, updated, or the check answered
- `1`: The download could not be written next to the binary or moved into place (the binary's directory is not writable)
- `4`: The download does not match the signed release's sha256; nothing was installed
- `5`: The release edge could not be reached
- `6`: The release is not signed by a release key this binary carries, is withdrawn, or is older than this binary without --allow-downgrade; nothing was installed
- `8`: The release has no build for this platform
- `2`: --check with --force, or an undeclared --channel value

### `i9 uninstall`

Remove i9 from this machine: its agent wiring, its home and what it left outside it

Remove i9 and say what went. It removes the MCP entry and skill
`i9 agent install` wrote into each detected agent harness; the residue
i9 leaves outside its home, by name only: the `$TMPDIR` and `/tmp`
state-dir fallbacks (`i9-sessions`, `i9-traces`, `i9-store`,
`i9-snapshots`), the live-VM registry (`i9/vms` under `$TMPDIR`, or
`i9-<uid>/vms` where `/tmp` stands in for it), the control sockets of VMs that have exited (`i9-*.sock`
and their `.pid` files) and their trace regions under `/dev/shm`, each only
when the VM that made it has exited; and the i9 home (`~/.i9`, or
`--home`), which holds the installed binary. A data root `--data` puts
outside the home is named and kept, since it can be shared across
installs, and an `i9` still on PATH outside the home is named.

It refuses a home that is `/`, your home directory, an ancestor of either
or of the current directory, or one that holds nothing of i9's. It refuses
while any VM is running, because a VM's disk lives under the home it would
delete; stop each one first. It refuses to delete saved snapshots, session
traces, the secrets store (`secrets/` under the home: the encrypted
store and its key file, which cannot be recovered) and an installed grant
(in the home's `config.json`; a reinstall starts on the free tier until
`i9 grant install` installs one again) unless you confirm with `--force`. A finished command's own record (the archive a CLI verb writes
as it exits) is housekeeping, not a saved trace, and goes with the home.
`--dry-run` lists all of it and removes nothing, saved state and
the secrets store included, with or without `--force`; when the real run
would refuse, the listing ends with a "a real run would refuse" line and
the exit is still 0.

```
i9 uninstall [--dry-run] [--force]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--dry-run` | boolean | False | List what would be removed, with sizes, and remove nothing |
| `--force` | boolean | False | Also delete saved snapshots, session traces and the secrets store, which uninstall otherwise refuses to remove |

**Examples:**

- See what would be removed: `i9 uninstall --dry-run`
- Remove i9, including saved snapshots, traces and secrets: `i9 uninstall --force`

**Exit codes:**

- `0`: Removed, or (--dry-run) listed
- `6`: A VM is running, or saved state exists and --force was not passed; nothing was removed
- `1`: Some paths could not be removed; each is named on stderr, and the rest were removed

### `i9 feedback`

Send a report about i9 to feedback.i9.io, where a person reads it

Post one report to https://feedback.i9.io: an i9 failure, a refusal whose
hint did not tell you how to go on, a wrong hint or doc, a step far slower
than its docs said, or something i9 does not do. A person reads every post;
it is how i9 gets fixed. Posts are anonymous and get no reply.

The text is the positional argument, or the contents of `--file`.
i9 adds its version (`X-I9-Version`) and the agent that sent it
(`X-Agent`: the MCP client's name when an MCP client calls it, else
`--agent`, else `cli`), and nothing else: no account,
no machine identifier, no trace, no file you did not name. It sends only
when called; i9 never sends a report on its own.
`--dry-run` returns what would be sent and sends nothing.

Include the i9 version, the command you ran, its exit status and error
envelope, and `i9 trace search --failed` for the session that failed. Never
include secrets, tokens, file contents or personal data. A report is at
most 64 KiB; the service accepts 3 per 10 minutes and 12 per day from one
client, and answers an exact repeat of today's report without storing it
again.

```
i9 feedback [text] [--file <string>] [--agent <string>] [--dry-run]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--file` | string |  | Read the report text from this file instead of the argument |
| `--agent` | string |  | The agent or harness sending the report (X-Agent); when an MCP client calls it, the client's own name is used |
| `--dry-run` | boolean | False | Print the request that would be sent, and send nothing |

**Examples:**

- Report a refusal whose hint did not help: `i9 feedback "i9 vm cp refused with ENOTFOUND; the hint named vm ls, which listed the VM. i9 2026.11.11. Command: i9 vm cp ./a vm1:/tmp"`
- Send a report written to a file: `i9 feedback --file report.txt`
- See what would be sent: `i9 feedback --dry-run --file report.txt`

**Exit codes:**

- `0`: Sent (or, with --dry-run, printed); the result carries the report id
- `2`: No text, both text and --file, empty text, or the service refused the report as malformed or over 64 KiB
- `3`: The --file path does not exist
- `5`: The post failed or the service is rate-limiting this client; the hint names the wait
- `1`: The service answered with something i9 does not understand

### `i9 version`

Print version information

Print the version and the build flavour. Also available as `i9 --version`. Add
`--verbose` for the per-component rows.

```
i9 version
```

**Examples:**

- Show version: `i9 version`

**Exit codes:**

- `0`: Version printed

### `i9 help`

Print help

Without arguments, prints top-level help. With a command path,
prints that command's help. --json emits the full command tree.

```
i9 help [command] [--env]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--env` | boolean | False | List the environment variables this binary reads (also `i9 help env-vars`) |

**Examples:**

- Top-level help: `i9 help`
- Help for a subcommand: `i9 help vm exec`
- Full command tree as JSON: `i9 help --json`

**Exit codes:**

- `0`: Help printed
- `2`: Unknown command path

### `i9 completions`

Emit shell completion script

Emits a shell completion script to stdout. Source the output
to enable tab completion. Not affected by --json.

```
i9 completions <shell>
```

**Examples:**

- Bash completions: `i9 completions bash`
- Source in .bashrc: `source <(i9 completions bash)`

**Exit codes:**

- `0`: Completion script emitted
- `2`: Unknown shell type

### `i9 trace`

Query and inspect traces

Trace data query and analysis. Five query verbs, not a verb per question:
`ls` enumerates, `show` renders, `tail` streams, `search` finds, `stats`
aggregates. Each reads one source: a positional `<archive.i9io>` (all five),
--archive PATH (`ls`, `show` and `stats`), or --session PID. Given none, it
resolves by this process's own TRACEPARENT, then the single in-flight
session, then refuses (never a newest-mtime guess). Default --limit 10;
--since defaults to the whole source when one is named, 24h for a query
across sessions.

A name not listed under Subcommands is refused as an unknown `i9 trace`
subcommand, with the nearest listed one named in the hint.

```
i9 trace
```

**Examples:**

- Which VM sessions exist, by PID: `i9 trace ls --kind sessions`
- Everything one session recorded, in time order: `i9 trace tail --session <PID> --reverse -n 0`
- What failed in it: `i9 trace search --failed --session <PID>`
- What was slow in it: `i9 trace stats --by slowest --session <PID>`
- The full recipe cookbook: `i9 trace search --examples`

**Exit codes:**

- `2`: Missing or unknown subcommand

#### `i9 trace ls`

List recent traces, VM sessions, or one trace's archives

One listing verb over the three things a caller enumerates before querying
anything else. `--kind` picks which:

  recent    (default) the most recent traces of this shell's own work, else
            of the one running VM; the same columns, with no rows, when
            neither exists
  sessions  in-flight and recent VM sessions (builds + interactive runs),
            each classified in-flight / crashed / completed; the trace a
            finished command (a `vm exec`, a stop, a snapshot) kept of
            itself is not a VM and is listed only with `--all`
  archives  the archives that carry a given `--trace-id`, found by matching
            the FixedSizeBinary(16) trace_id column rather than by decoding
            spans, so a damaged archive is still matched to its trace

`--kind sessions` is the discovery anchor for `--session <PID>` on
`i9 trace tail` and `i9 trace search`: it tells you which PID to pass.
It probes the newest 200 sessions unless `--all` is given, and reports a
skipped count rather than silently dropping older ones.

`--kind archives` MATCHES rather than enumerates, and the encoding forces
that: the `trace_id` column holds blake3(id)[0..16], a digest, so testing
for a KNOWN id is 16 bytes of comparison while recovering the ids in an
archive would need both attribute pools — the expensive path, and the one
that fails when a pool is missing. `--trace-id` is therefore required for
that kind; there is deliberately no enumerate-every-trace mode.

Absence is never overstated: an unreadable batch or file is counted and
printed, because "not found in what I could read" is a different claim
from "not present".

```
i9 trace ls [root] [--kind <recent|sessions|archives>] [--limit <integer>] [--archive <string>] [--session <string>] [--session-kind <build|run|gate>] [--all] [--trace-id <string>] [--json] [--otlp] [--internal]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--kind` | enum: recent, sessions, archives | recent | What to list |
| `--limit` | integer |  | Maximum rows (default 10 for --kind recent, 5 completed sessions for --kind sessions; 0 = unlimited, as on search and stats) |
| `--archive` | string |  | Path to a .i9io archive to list from (default: this session's own archive); with --kind archives, a directory or archive file to scan (default: the working directory) |
| `--session` | string |  | List from the archive of one VM session, by PID or by the --name it was run as (the newest VM of that name). Never auto-selects: exits non-zero, naming the nearest VM, if neither is known. |
| `--session-kind` | enum: build, run, gate |  | With --kind sessions: only show sessions of this kind |
| `--all` | boolean | False | With --kind sessions: scan every historical session archive, not just the newest 200, and also list the finished commands whose own trace is kept (a live one is always listed), which the listing otherwise hides (forensics on an old run) |
| `--trace-id` | string |  | With --kind archives: the trace id to look for; required for that kind, because there is no enumerate-all mode |
| `--json` | boolean | False | Machine-readable output (NDJSON rows for --kind recent, a JSON array otherwise) |
| `--otlp` | boolean | False | Output the listed spans as OTLP-JSON, one ExportTraceServiceRequest line, in listing order: the encoding tail --otlp and the live span stream use, joined to the --json rows by span id. --kind recent only |
| `--internal` | boolean | False | With --kind recent: list internal spans raw instead of folding them out of the default view (--verbose groups what was folded) |

**Examples:**

- Which VM sessions exist, and which PID to query: `i9 trace ls --kind sessions`
- The most recent traces in the resolved archive: `i9 trace ls`
- Every archive carrying one trace id: `i9 trace ls --kind archives --trace-id <TRACE_ID>`

**Exit codes:**

- `0`: Listed (possibly nothing)
- `1`: Archive read error
- `2`: Invalid arguments, or --kind archives without --trace-id

#### `i9 trace show`

Render a trace as a process tree, flamegraph, or diagram

One rendering verb over a trace or an archive. `--format` picks the shape:

  tree     (default) the subprocess tree under a trace id
  flame    depth-bucketed ASCII bar chart, self-time per span
  folded   the same fold as Brendan-Gregg "stack count" lines, for
           flamegraph.pl
  mermaid  a deterministic Mermaid diagram of the span DAG

```
i9 trace show <target> [--format <tree|flame|folded|mermaid>] [--archive <string>] [--session <string>] [--json] [--otlp] [--internal]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--format` | enum: tree, flame, folded, mermaid | tree | What to render |
| `--archive` | string |  | tree: look the id up in this .i9io archive — the source `i9 trace ls --archive` listed it from (default: this session's own archive) |
| `--session` | string |  | One VM session, by PID or by its --name. tree: look the id up in its archives — the source `i9 trace ls --session` listed it from. flame/folded/mermaid: render every archive of the session as one |
| `--name-prefix` | string |  | flame/folded/mermaid: restrict to spans whose name starts with this prefix |
| `--top` | integer | 40 | flame: maximum rows to render |
| `--style` | string | graph | mermaid: diagram style — graph | seq | gantt |
| `--max-spans` | integer | 400 | mermaid: cap on spans rendered (oldest first) |
| `--label-attr` | string |  | mermaid graph: comma-separated attribute keys whose values label each node (the span name when a span carries none) |
| `--edge-attr` | string |  | mermaid graph: attribute whose value is another rendered span's id; draws a dashed edge to it |
| `--edge-style-attr` | string |  | mermaid graph: attribute whose value starting with `refuse` draws the span and its attribute edge red |
| `--json` | boolean | False | Emit the raw frame/rows as JSON; field names are the wire names |
| `--otlp` | boolean | False | Output the shown spans as OTLP-JSON, one ExportTraceServiceRequest line, in the order the tree draws them: the encoding tail --otlp and the live span stream use, joined to the --json rows by span id. --format tree only |
| `--internal` | boolean | False | tree: render internal spans raw instead of folding them out of the default view |

**Examples:**

- The subprocess tree under a trace id, from `i9 trace ls`: `i9 trace show <TRACE_ID>`
- Where the time went in an archive, as an ASCII flamegraph: `i9 trace show --format flame ./run.i9io`
- A Mermaid diagram of the span DAG: `i9 trace show --format mermaid ./run.i9io`

**Exit codes:**

- `0`: Rendered
- `1`: Read or decode failure, or the archive decoded zero spans
- `2`: Bad arguments, or an archive was not found
- `3`: Trace not found

#### `i9 trace tail`

Stream spans from an archive (newest-first by default)

Prints the newest 20 spans of an i9io archive; --follow streams new ones.

--follow blocks until the archive's change notification wakes it (never a poll).

Output format: one line per span —
  `<ISO-ts>` `<name>` `<status>` `<duration>` key=val key=val…

Attributes are shown inline, except the recorder's own bookkeeping attributes, which
--verbose adds. Use --json for NDJSON output suitable for jq piping; it
carries every attribute. Use --fields to restrict which attributes are
shown (a field named there is shown whatever it is).

Use --otlp for the stream a live session serves at GET /api/agent/spans:
OTLP-JSON, one ExportTraceServiceRequest per line (one ResourceSpans, a scope
per registry channel named by `i9 schema io-channels`, the attribute mapping
`i9 archive export-otel` uses, and an i9.trust and i9.completeness attribute
on each span). It prints every span, as --internal does. Without --follow
it prints the newest spans as one request; with --follow, one request per
pass that found new spans.

Filtering: --where takes a VDSL program, a predicate over one span (`i9 docs vdsl` has the
grammar): comparisons of a key with a value (= != < <= > >= =~ !~, and in [a, b]),
has(key), channel(name), event(name), link(), trust >= label, and complete,
incomplete and unknown, joined with and, or, not and parentheses. A key is a span
field (name, duration, status, kind, start, end, trace_id, span_id, parent_id,
source) or an attribute; a comparison on a key the span lacks is false, != included,
and absence is not has(key). Values are text, numbers, true and false, durations
(100ms) and sizes (4KiB). Repeat --where and every program must hold. A program has
no loops or recursion and costs its node count (a pattern costs its automaton's
states); one over the bound is refused with a hint.
--target filters by span name glob. --since/--until bound by time.

`--follow --transcript <session.jsonl>` follows the OTHER end of the same
live stream: it projects an agent-session transcript that is still being
appended to into an i9io archive that is still being appended to, so the
archive grows with the session instead of being rebuilt. Driven by
inotify (kqueue on macOS), never a poll — a watch event is a hint to look, and every wake
re-derives what is new from the span ids themselves, so a coalesced or
duplicated event cannot corrupt the result. The archive is left UNSEALED
while following (that is what makes it tailable) and is sealed on
interrupt.

```
i9 trace tail [archive] [--follow] [--reverse] [--target <string>] [--where <string>] [--since <string>] [--until <string>] [--last <string>] [--limit <integer>] [--json] [--otlp] [--otlp-push] [--all-sessions] [--otlp-endpoint <string>] [--internal] [--session <string>] [--run <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--follow` | boolean | False | Block and stream new spans as they are appended |
| `--transcript` | string |  | With --follow: project this still-growing agent-session transcript (.jsonl) into an archive instead of reading one |
| `--keyframe` | string |  | With --follow: emit a roll-up row every `<interval>` (e.g. 5s, 1m) summarising spans since the last keyframe — the live equivalent of `stats`. Refused without --follow |
| `--reverse` | boolean | False | Show oldest first (default is newest first) |
| `--target` | string |  | Filter by span name glob (e.g. 'python*', 'guest.*') |
| `--where` | string |  | A VDSL program over one span, such as 'status=error and duration>100ms' (repeatable, every program must hold); `i9 docs vdsl` has the grammar |
| `--fields` | string |  | Comma-separated list of fields/attributes to show (others hidden) |
| `--since` | string |  | Only spans newer than this: a duration ago (10s, 5m, 1h) or a UTC time (2026-10-20T07:20:00Z); a span still open at that point counts as inside the window; anything else is refused |
| `--until` | string |  | Only spans started at or before this: a duration ago (5m, 1h, 2d) or a UTC time (2026-10-20T07:20:00Z); a scan the batch cap or a budget bounds starts here, so an earlier --until reaches older spans; anything else is refused |
| `--last` | string |  | Alias for --since |
| `--limit` | integer | 20 | Stop after N matching spans (default 20, 0 = unlimited) |
| `--cursor` | string |  | Resume from this cursor token (from previous paginated query) |
| `--page-size` | integer |  | Page size for cursored output (emits next_cursor at end) |
| `--json` | boolean | False | Output NDJSON: one object per span row, plus records with synthetic:true and a type (hints, truncated, scan_partial, collapse_summary, collapse_footer) that a reader filters on |
| `--otlp` | boolean | False | Output OTLP-JSON, one ExportTraceServiceRequest per line, every span: the terminal view of the live span stream (GET /api/agent/spans); it is the JSON output under --json too. Not with --fields or --keyframe |
| `--otlp-push` | boolean | False | Send the spans to an OTLP/HTTP collector instead of printing them: each pass's closed spans as ExportTraceServiceRequests of at most 4 MiB POSTed to `<endpoint>`/v1/traces. The endpoint is --otlp-endpoint, else the config key otel.endpoint, else OTEL_EXPORTER_OTLP_ENDPOINT; a request not accepted is sent again from the archive on the next pass. With --follow, the exporter for the user's own stack |
| `--all-sessions` | boolean | False | With --otlp-push: export every session in this host's own sessions directory, each archive on its own (its own requests, under its own session.id), skipping this process's own. The sessions still being written, and every one that appears later under --follow; a finished one only when --since covers it |
| `--otlp-endpoint` | string |  | The OTLP/HTTP endpoint --otlp-push sends to (implies --otlp-push), e.g. http://localhost:4318 |
| `--internal` | boolean | False | Stream internal spans raw instead of folding them out of the default view (--verbose groups what was folded) |
| `--session` | string |  | Read a VM session's archive by its PID or by the --name it was run as (refuses, naming the nearest VM, if neither is known) |
| `--run` | string |  | Read all archives from a single run by its trace ID (refuses and lists known IDs if none match) |

**Examples:**

- Everything one session recorded, in time order: `i9 trace tail --session <PID> --reverse -n 0`
- Follow a live session as spans are written: `i9 trace tail --follow --session <PID>`
- The newest 50 spans of an archive on disk: `i9 trace tail -n 50 ./run.i9io`
- A live session's spans as OTLP-JSON, one request per line: `i9 trace tail --follow --otlp --session <PID>`

**Exit codes:**

- `0`: Exited cleanly (end of archive, sealed transcript, or user interrupt)
- `1`: Read error or archive not found
- `2`: Invalid arguments, or the transcript was not found
- `5`: No answer from the OTLP collector: nothing listening, the connection closed, a write failed, or the TLS handshake failed
- `7`: The OTLP collector refused part of the export

#### `i9 trace search`

Grep-like span search with attribute display

Finds spans whose name, kind, status, status_msg or any attribute key or
value matches a pattern; --attr narrows the match to one key.

Pattern is optional when --where or --target is set, allowing
pure predicate-based queries.

Output format (default): one line per match —
  `<kind>` `<span-id>` `<duration>` `<name>` [status_msg=`<reason>`] key=val key=val…
Attributes are shown inline, except the recorder's own bookkeeping attributes, which
--verbose adds. Matched values are highlighted in the terminal. Use
--json for NDJSON; it carries every attribute. A span that recorded why it
failed carries the reason as status_msg: on the row, as a --json field, and
as the last column of the --failed table.

Filtering: --where takes a VDSL program, a predicate over one span (`i9 docs vdsl` has the
grammar): comparisons of a key with a value (= != < <= > >= =~ !~, and in [a, b]),
has(key), channel(name), event(name), link(), trust >= label, and complete,
incomplete and unknown, joined with and, or, not and parentheses. A key is a span
field (name, duration, status, kind, start, end, trace_id, span_id, parent_id,
source) or an attribute; a comparison on a key the span lacks is false, != included,
and absence is not has(key). Values are text, numbers, true and false, durations
(100ms) and sizes (4KiB). Repeat --where and every program must hold. A program has
no loops or recursion and costs its node count (a pattern costs its automaton's
states); one over the bound is refused with a hint.
--target filters by span name glob, and a span the target names is
listed even when it is internal: the default view folds internal spans,
never the one a search asked for by name. --since/--until/--last bound
by time. --fields restricts which attributes are shown.

When the default view folded internal spans out of a search, the count
is said before the rows (and as a leading folded_internal record under
--json); --internal searches them too.

Three flags answer a fixed question instead of a pattern: --failed lists
the non-zero-exit traces, --parent lists one span's children, and
--examples prints the recipe cookbook (pure static text, no archive I/O, so
it is available in every build). They take the same source selectors as a
pattern search — the positional `<archive>`, or --session `<PID>`.

```
i9 trace search [pattern] [archive] [--failed] [--parent <string>] [--kind <string>] [--target <string>] [--where <string>] [--fields <string>] [--since <string>] [--until <string>] [--limit <integer>] [--budget-ms <integer>] [--json] [--otlp] [--internal] [--session <string>] [--run <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--failed` | boolean | False | List the spans that failed (error status, a non-zero exit or a signal) instead of matching a pattern |
| `--parent` | string |  | List the children of this span id instead of matching a pattern |
| `--examples` | boolean | False | Print the cookbook of common query recipes and exit (no archive I/O) |
| `--regex` | boolean | False | Treat pattern as a regular expression |
| `--kind` | string |  | Filter by span kind (e.g. internal, client, server) |
| `--attr` | string |  | Restrict pattern matching to this attribute key only |
| `--target` | string |  | Filter by span name glob (e.g. 'python*', 'guest.*'); a span the glob names is listed even when internal |
| `--where` | string |  | A VDSL program over one span, such as 'status=error and duration>100ms' (repeatable, every program must hold); `i9 docs vdsl` has the grammar |
| `--fields` | string |  | Comma-separated list of fields/attributes to show (others hidden) |
| `--since` | string |  | Only spans newer than this: a duration ago (10s, 5m, 1h) or a UTC time (2026-10-20T07:20:00Z); a span still open at that point counts as inside the window; anything else is refused |
| `--until` | string |  | Only spans started at or before this: a duration ago (5m, 1h, 2d) or a UTC time (2026-10-20T07:20:00Z); a scan the batch cap or a budget bounds starts here, so an earlier --until reaches older spans; anything else is refused |
| `--last` | string |  | Alias for --since |
| `--limit` | integer | 10 | Maximum number of results (0 = unlimited) |
| `--budget-ms` | integer |  | Stop reading after this many milliseconds and answer from what was read, newest span batches first; replaces the default cap of the newest 20000 span batches, so a larger budget reads further back; a cut-short answer leads with a scan_partial record (--json) or a note naming how many batches went unread |
| `--context` | boolean | False | Show full attribute values (no truncation) |
| `--full` | boolean | False | Alias for --context (show full, untruncated attribute values) |
| `--tree` | boolean | False | Render the matched processes as a tree (pid<-ppid, argv, exit or signal, duration); with no pattern, every process, uncapped unless --limit is given |
| `--around` | integer |  | Show N spans before and after each match (context window) |
| `--around-before` | integer |  | Show N spans before each match |
| `--around-after` | integer |  | Show N spans after each match |
| `--json` | boolean | False | Output NDJSON: one object per span row, plus records with synthetic:true and a type (hints, truncated, scan_partial, folded_internal, collapse_summary, collapse_footer) that a reader filters on |
| `--otlp` | boolean | False | Output the matched spans as OTLP-JSON, one ExportTraceServiceRequest line (an empty one when nothing matched), every span: the encoding tail --otlp and the live span stream use; it is the JSON output under --json too. Not with --fields, nor with the process tree, context lines or a grouping |
| `--internal` | boolean | False | Match and print internal spans raw instead of folding them out of the default view (--verbose groups what was folded) |
| `--session` | string |  | Search a VM session's archive by its PID or by the --name it was run as (refuses, naming the nearest VM, if neither is known) |
| `--run` | string |  | Search all archives from a single run by its trace ID (refuses and lists known IDs if none match) |
| `--sort` | string |  | Order results: duration | time. Forces a full scan; --limit applies after ordering |

**Examples:**

- Everything one session recorded that failed: `i9 trace search --failed --session <PID>`
- Spans whose name matches a glob, newest first: `i9 trace search --target 'i9.oci.*' --session <PID>`
- One attribute's value, filtered by a predicate: `i9 trace search --where 'duration>100ms' --fields process.command_args --session <PID>`
- The recipe cookbook, no archive needed: `i9 trace search --examples`

**Exit codes:**

- `0`: Search complete
- `1`: Read error
- `2`: Invalid arguments
- `3`: Span not found (--parent)

#### `i9 trace stats`

Aggregate a trace archive into stats and percentiles

One aggregation verb. `--by` picks which rollup, over the same resolved
source every other trace verb reads (positional `<archive>`, `--archive
PATH`, or `--session <PID>`):

  overview     the first look at a VM, one call: spans by family, user
               process count, every failure with its exit and signal, the
               five slowest commands, crash checkpoints, archives read, and
               three exact next queries; --json tags each line by `section`
  cmd          (default) per-command statistics
  slowest      the slowest traces
  percentiles  duration percentiles, acceleration-aware; --name filters
               to one tool; --attr KEY measures that attribute's numeric
               values instead (p50..p99, max, mean, sum)
  by-name      per span name with p50/p95
  by-attr      top-K distribution of --attr's values (e.g. process.command_args →
               the top commands)
  busy         per span name, or per --group label, the wall time its spans
               covered: the union of their intervals, so parallel spans count
               once; an open span is clipped at the window's end and counted
               in clipped_open
  concurrency  per span name, or per --group label, the most of its spans
               running at one instant and the mean over the window; with
               --bins N, a row per key per bin with the spans running in it
  cardinality  unique value counts per attribute (HLL); --attr picks it
  span-summary span count, batch count and time range from acceleration
               metadata — no span payload decode, O(accel segments)
  counters     every channel's cumulative totals at one cut, read from the
               counter nodes alone: events, kept, suppressed, each sum, the
               request-key hash, and the cut's seq and host time on every
               row; --at SEQ picks the latest cut at or before it (default:
               the archive's latest); a channel the cut did not change
               carries the totals from its last change, which `changed_seq`
               names; no per-request span is decoded. --json prints an OTLP-JSON
               ExportMetricsServiceRequest: one cumulative Sum per counter, .kept,
               .suppressed and .sum.`<a>`, one data point per channel
  losses       what the read could not show, from the one loss ledger:
               spans a producer dropped (a ring overwrote, a forwarder
               overflowed) by kind, spans the writer failed to write,
               batches withheld, archives that would not read or verify;
               each loss is marked LOSS with the ledger's id for it,
               and the last line
               says whether the read is complete; --json prints the
               ledger's object (`lost`, `drop_kinds`, `complete`)
  metrics      the same spans as Prometheus text exposition
  hints        per hint, a total row (scope total) then one row per
               model-and-harness profile: class, shown, followed, follow
               rate, and an action. 10+ showings over 14+ days under a 10
               percent rate is retire on the total (rewrite for a blocker
               or an unnamed class); under a keep total, rewrite on a
               profile row whose own variant fails. Read from the home's
               hint archives, so it needs no --session; --session narrows
               to the hints shown about that VM. Its rows carry ids and
               counts only, safe to paste into a report

`--by metrics` is a verb over the existing record set rather than a
separate collector, so a scrape and `--by by-name` cannot disagree about
the same archive. Span names become Prometheus LABELS, never metric names:
`i9.restore.stage` is not a legal metric name, and folding names into
families would make family cardinality unbounded, which scrapers handle
far worse than label cardinality. The histogram is the point — a gauge
holding the last value seen cannot produce a quantile.

--where takes a VDSL program, a predicate over one span (`i9 docs vdsl` has the
grammar): comparisons of a key with a value (= != < <= > >= =~ !~, and in [a, b]),
has(key), channel(name), event(name), link(), trust >= label, and complete,
incomplete and unknown, joined with and, or, not and parentheses. A key is a span
field (name, duration, status, kind, start, end, trace_id, span_id, parent_id,
source) or an attribute; a comparison on a key the span lacks is false, != included,
and absence is not has(key). Values are text, numbers, true and false, durations
(100ms) and sizes (4KiB). Repeat --where and every program must hold. A program has
no loops or recursion and costs its node count (a pattern costs its automaton's
states); one over the bound is refused with a hint.
The engine judges the program during the scan, so it narrows every rollup that
reads spans and batch-skip still applies. `cardinality` and `span-summary`
read acceleration metadata, never spans, so they refuse `--where` rather than
ignore it. `counters` reads counter nodes and answers one cut over every
channel, so it refuses `--where`, `--since` and `--limit`.

```
i9 trace stats [archive] [--by <overview|cmd|slowest|percentiles|by-name|by-attr|busy|concurrency|cardinality|span-summary|metrics|hints|counters|losses|secret>] [--since <string>] [--limit <integer>] [--budget-ms <integer>] [--archive <string>] [--session <string>] [--attr <string>] [--weight-attr <string>] [--name <string>] [--where <string>] [--bins <integer>] [--group <string>] [--json] [--internal]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--by` | enum: overview, cmd, slowest, percentiles, by-name, by-attr, busy, concurrency, cardinality, span-summary, metrics, hints, counters, losses, secret | cmd | Which rollup to compute |
| `--since` | string |  | Time window: a duration back from now (5m, 2h, 1d), a UTC time (2026-10-20T07:20:00Z), or `all`; a span still open at the start of the window counts as inside it; anything else is refused. Default: the whole source when --session, --archive or --run names one; 24h for a query across sessions |
| `--limit` | integer | 10 | Maximum rows (top-K) |
| `--budget-ms` | integer |  | Stop reading after this many milliseconds and answer from what was read, newest span batches first; replaces the default cap of the newest 20000 span batches, so a larger budget reads further back; a cut-short answer leads with a scan_partial record (--json) or a note naming how many batches went unread |
| `--archive` | string |  | The flag spelling of the positional `<archive>` |
| `--session` | string |  | Aggregate the archive of one VM session, by PID or by the --name it was run as (the newest VM of that name). Never auto-selects: exits non-zero, naming the nearest VM, if neither is known. |
| `--at` | integer |  | With --by counters: the cut to read, by sequence number; the latest cut at or before it answers (default: the archive's latest) |
| `--attr` | string |  | With --by by-attr / cardinality: the attribute key to group or count; with --by percentiles: the numeric attribute to measure instead of duration |
| `--weight-attr` | string |  | With --by by-attr: sum this numeric attribute per group and order by the sum (a span without it weighs 0, counted on stderr) |
| `--name` | string |  | With --by cmd, slowest or percentiles: restrict to the command this name (a glob) ran |
| `--where` | string |  | A VDSL program over one span, such as 'status=error and duration>100ms' (repeatable, every program must hold); `i9 docs vdsl` has the grammar |
| `--bins` | integer |  | With --by concurrency: split the window into this many equal bins and answer, per span name or --group label, the spans running in each bin |
| `--group` | string |  | With --by busy or concurrency: a row per LABEL holding the spans its VDSL PROGRAM selects, instead of a row per span name (repeatable, at most 16; each program is costed into the --where total). A span counts in every label it matches, and the output says how many did; a span in no label counts under other |
| `--json` | boolean | False | Machine-readable output |
| `--internal` | boolean | False | Aggregate internal spans as themselves instead of folding them out of the default view (cmd, slowest, percentiles, by-name, by-attr, metrics; --verbose groups what was folded) |

**Examples:**

- Per-command statistics for one session: `i9 trace stats --session <PID>`
- What was slow in it: `i9 trace stats --by slowest --session <PID>`
- Duration percentiles for one tool: `i9 trace stats --by percentiles --name python3 --session <PID>`
- The commands that ran, most frequent first: `i9 trace stats --by by-attr --attr process.command_args --session <PID>`

**Exit codes:**

- `0`: Rollup computed
- `1`: Archive or directory unreadable
- `2`: Invalid arguments
- `3`: No session resolved (ambiguous or no default; pass --session), or the archive carries none of the rollup's input (--by working-set)

#### `i9 trace add-span`

Add a span of your own to the trace: a step of your script or program, timed, under the process that ran it

Writes one span into the trace this process belongs to. In a VM it goes to
the intake socket ($I9_TRACE_SOCK); on a host, where no agent listens, it is
written as a contribution federation reads. The span parents under the
process that ran the verb (its TRACEPARENT), so `i9 trace stats`,
`search` and `show` place it inside that process. A program that emits many
spans writes JSON records to $I9_TRACE_SOCK directly: `i9 docs spans` has
the record and emitters for Python, Node, Go, Rust, C and shell; `--batch`
files a file of those records at once. `--span-id` files a span under an id
you already gave out (a root you put in TRACEPARENT), so the spans that
name it as their parent are not left dangling. A name or attribute key
under `i9.` is i9's own and must be a trace vocabulary name; any other
name is yours. POSIX only.

```
i9 trace add-span [--name <string>] [--parent <string>] [--trace <string>] [--status-ok] [--status-fail] [--status-msg <string>] [--span-id <string>] [--batch] [--attr <string>] [--start-ns <string>] [--end-ns <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--name` | string |  | Span name [required] |
| `--parent` | string |  | Parent span id (hex); defaults to the span in $TRACEPARENT |
| `--trace` | string |  | Trace id (hex); defaults to the trace in $TRACEPARENT |
| `--status-ok` | boolean | False | Mark the span status OK |
| `--status-fail` | boolean | False | Mark the span status failed |
| `--status-msg` | string |  | The span's status message, the reason it failed, as text |
| `--span-id` | string |  | This span's id (hex; default: minted), to file a span others already name as their parent, such as a root put in TRACEPARENT |
| `--batch` | boolean | False | Read span records from stdin, one JSON object per line (the record of i9 docs spans), and file them together: one intake connection, or one archive; only --parent, --trace and --socket apply |
| `--attr` | string |  | Span attribute as k=v (repeatable); a key under i9. is i9's own vocabulary, any other key is yours |
| `--start-ns` | string |  | Start time as epoch nanoseconds (default: now) |
| `--end-ns` | string |  | End time as epoch nanoseconds, not before --start-ns (default: now) |
| `--socket` | string |  | Intake socket path (default: $I9_TRACE_SOCK, else /run/i9/trace.sock) |

**Examples:**

- A step of a script as a span, with its measured duration: `i9 trace add-span --name build.make --start-ns 1761600000000000000 --end-ns 1761600002500000000`
- A span with attributes of your own: `i9 trace add-span --name myapp.load --attr rows=1200 --attr cached=false`
- A failed span that says why: `i9 trace add-span --name myapp.gate --status-fail --status-msg 'lint: 3 files'`
- Many spans from a file of records, filed together: `i9 trace add-span --batch < spans.jsonl`

**Exit codes:**

- `0`: Span published
- `2`: The span name is empty, an i9.* --attr key is not a trace vocabulary name, --span-id is not an id, or a --batch line was refused (the rest are filed)
- `1`: Failed to publish (socket unavailable, bad args)

#### `i9 trace run`

Run a command on this host as one traced session: every process it starts is a span, and its programs' own spans join them

Starts the command under i9's process capture (ptrace). Every process
it runs becomes a span: its parent, its start and end, its executable,
working directory, argument count and argument digest (the arguments
themselves are not recorded), and its exit code or signal. A
non-zero exit or a signal is a failed span that says which.

For the run i9 serves an intake socket and gives the command
I9_TRACE_SOCK and a TRACEPARENT naming the command's own span, so a
program writes its own spans there, the record of `i9 docs spans`, and
they land in the same session: a record with no parent_id under the
process that wrote it, one that names a parent under that span.

The run ends when the command ends. Processes it left running are let
go and recorded as open spans. The whole run is ONE archive in the
sessions directory: `i9 trace ls --kind sessions` lists it as
`trace-run`, and `--session <PID>` (the pid this verb ran as, printed
on stderr with the archive path) reads it.

Where ptrace is refused (Yama ptrace_scope 2 or 3, a seccomp policy,
another tracer), the command still runs; the run says so on stderr and
on its span (i9.trace.run.capture=unavailable, the refusal in
i9.reason) and records the command's own span and its programs' spans,
but no other process. Linux only.

```
i9 trace run <command>
```

**Examples:**

- A build as one session: every compiler and linker a span: `i9 trace run -- make -j8`
- A script whose own spans join its processes': `i9 trace run -- python3 release.py`

**Exit codes:**

- `2`: No command was given
- `*`: Any other status is the guest command's own exit status, passed through unchanged with no error envelope; a guest that itself exits with a number in this table looks like that error by status alone, so tell them apart by i9's `error:` line on stderr, or under --json by the error envelope against the result's `exitCode` and `timedOut`

### `i9 config`

Inspect and edit configuration

Read, write and validate the layered JSON configuration. Files are
merged from the data root, the instance root (~/.i9/) and any
project-local .i9/config.json ancestors of the current directory,
lowest to highest priority.

```
i9 config
```

**Examples:**

- Print the merged configuration: `i9 config show`
- Read one key: `i9 config get hints.level`
- Set a value in the user config: `i9 config set hints.level verbose`
- Show which config files are merged and in what order: `i9 config paths`

**Exit codes:**

- `2`: Missing subcommand

#### `i9 config show`

Dump merged configuration

Print the effective configuration: the deep-merge of every layer
(`~/.i9/config.json`, a project-level `.i9/config.json` if present,
and CLI overrides). A project layer overrides the user one, so a
repository you cloned can change what the runtime does. The output is
what the runtime reads — not what any single file says.

```
i9 config show
```

**Examples:**

- Dump the merged configuration: `i9 config show`
- The same, for a script to read: `i9 config show --json`

**Exit codes:**

- `0`: Config shown
- `4`: A config layer does not parse. Nothing is printed: a layer that failed to parse contributes nothing, so the document would describe a configuration the files on disk do not. `i9 config paths` names the layer to fix.

#### `i9 config get`

Read one config key

Look up a single key by its dot-separated path (e.g.
`telemetry.enabled`). Returns the merged value — the one the
runtime uses — accounting for every config layer.

```
i9 config get <key>
```

**Examples:**

- Read one key from the merged configuration: `i9 config get telemetry.enabled`

**Exit codes:**

- `0`: A value is in force: written in a config layer, or the key's declared default
- `2`: Missing key argument, unknown option, or extra argument
- `3`: No such key — the schema declares none by that name (a typo). A key at its default is NOT this: it has a value in force and exit 0 returns it
- `4`: Config file is malformed (distinct from key-not-found, so a caller falling back on failure does not treat a corrupt config as an absent key)

#### `i9 config set`

Write one config key to this install's config file

Writes `<key>` = `<value>` to `<i9 home>/config.json`, the user layer of
the config ladder (flag > env > config file > default). The key must be
one the schema declares (`i9 config keys` lists each with its type), and the value is coerced to that type: a boolean takes
true/false, on/off, yes/no or 1/0; an integer or number must parse
whole; a string is taken as given; an array is a JSON array literal.
A key the schema does not declare is refused rather than written, since
nothing would ever read it.

The write is atomic and never replaces a config.json it cannot parse:
a malformed file is reported, not overwritten. A project-level
`.i9/config.json` sits above the user layer in the merge, so a key set
here can still be shadowed there; `config get` reports the value in
force.

```
i9 config set <key> <value>
```

**Examples:**

- Opt this machine out of the telemetry beacon: `i9 config set telemetry.enabled false`
- Give the forked sandbox tier more guest RAM: `i9 config set execution.forkedMemoryMib 4096`

**Exit codes:**

- `0`: Key written
- `2`: Missing argument, unknown option, a key the schema does not declare, or a value the key's type refuses
- `4`: The existing config.json is malformed or not writable; nothing was changed
- `6`: The key is user-only, and the caller is an MCP client

#### `i9 config unset`

Remove one config key from this install's config file

Removes `<key>` from `<i9 home>/config.json` so the key falls back to
the next layer of the ladder (env, then the compiled default). The key
must be one the schema declares; a key that is declared but not set in
this file is reported as not found, so a script can tell "already at
the default" from "removed just now". The write is atomic and never
replaces a config.json it cannot parse.

```
i9 config unset <key>
```

**Examples:**

- Return the telemetry beacon to its default (on): `i9 config unset telemetry.enabled`

**Exit codes:**

- `0`: Key removed
- `2`: Missing argument, unknown option, or a key the schema does not declare
- `3`: The key is not set in this install's config.json
- `4`: The existing config.json is malformed or not writable; nothing was changed
- `6`: The key is user-only, and the caller is an MCP client

#### `i9 config fix`

Apply auto-fixable configuration repairs

Detect and repair auto-fixable configuration issues (the ones `i9 doctor`
counts as `fixable`). Prompts for confirmation unless --yes is given.

```
i9 config fix [--yes]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--yes` | boolean | False | Apply fixes without interactive confirmation |

**Examples:**

- Apply the repairs `i9 doctor` proposes: `i9 config fix`

**Exit codes:**

- `0`: Config fixed (or nothing to fix)

#### `i9 config paths`

Show resolved config file paths

List the config files that were merged and the order they were
merged in. The project layer (highest priority) is named separately
so you know which file an edit has to land in to take effect.

```
i9 config paths
```

**Examples:**

- Which files the merged configuration came from: `i9 config paths`
- The layer an edit has to land in to win: `i9 config paths --json`

**Exit codes:**

- `0`: Paths shown
- `2`: Usage error (unexpected argument)
- `4`: A layer in `malformed` does not parse. The paths still print — this verb is how you find which file to fix — but the exit status says the merged configuration is not what the files describe.

#### `i9 config keys`

List every config key with its type and default

Print each key `i9 config set` accepts: its dot-separated path, the
type its value is coerced to, the default in force while no layer sets
it, and what it controls. Public keys are listed; `--all` adds the
advanced and hidden ones.

```
i9 config keys [--all]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--all` | boolean |  | Also list the advanced and hidden keys |

**Examples:**

- Every public key, its type and its default: `i9 config keys`
- Every key, for a script to read: `i9 config keys --all --json`

**Exit codes:**

- `0`: Keys listed
- `2`: Unexpected argument

### `i9 doctor`

Check this install: packed payloads, host capabilities, merged config

The one health verb. Three sections, one verdict:

- **payloads** — the running binary's pack trailer and TOC: every required
  payload present, non-zero, readable at its offset, blake3-verified
  against the packed manifest; optional platform payloads reported, and one
  this binary does not pack is `n/a` with a reason, not a failure.
- **host** — what this machine can do with a guest: /dev/kvm, userfaultfd
  and its write-protect feature (run / restore / capture), and on arm64 Linux
  the PSCI versions KVM will hold (the macOS arm64 report has no PSCI row).
- **config** — the merged configuration (or the file passed with the global
  `--config`): unknown command keys, unreachable paths, stale shims,
  isolation vs discovered files, and the strict schema validation, with
  what `i9 config fix` can repair.

The human report is the checks and the verdict; `--verbose` adds the
payload table, the pack's size and manifest, optional payloads that are
absent, and the host details behind each check (feature masks, the PSCI
versions the host accepts). `--json` emits one object with the three
sections and `ok`, plus `passed`, `failed` and `warnings`: the same totals
the text summary line prints.

```
i9 doctor
```

**Examples:**

- Full check, human report: `i9 doctor`
- Machine-readable verdict: `i9 --json doctor`
- Validate one config file instead of the merged view: `i9 doctor --config ./i9.json`

**Exit codes:**

- `0`: Every required check passed
- `2`: Usage error: an unexpected argument, or --config with no path
- `4`: Issues found: a required payload failed, or the config has errors

### `i9 schema`

Dump CLI schema (JSON Schema format)

Reads the packed i9io CONFIG_SCHEMA segment and dumps it as
JSON Schema. Useful for tooling that needs type information
about flags, args, and config keys.

```
i9 schema [path]
```

**Examples:**

- Full CLI schema: `i9 schema`
- Schema for a specific command: `i9 schema trace`
- The published channel registry (ingress and egress channels, trust, counters, holes): `i9 schema io-channels`

**Exit codes:**

- `0`: Schema or channel registry dumped
- `3`: Command path not found

### `i9 docs`

Read i9's documentation from inside the binary — no network

Lists and prints the documentation embedded in this binary. `i9 docs`
writes one document path per line; `i9 docs <name>` writes that
document's raw bytes to stdout.

The docs are an i9io segment packed into the binary at build time and
read back by mapping it in place, so this works with no network, no
install tree, and no files beside the binary itself. Nothing is
written to disk and no pager is invoked — pipe the output wherever
you want it.

A name resolves against every document in the segment: an exact path,
a path without its extension, a unique basename, or a unique trailing
path segment. `i9 docs cli` and `i9 docs mcp-tools` both
work. A name that matches more than one document is reported as
ambiguous rather than silently resolved.

```
i9 docs [name]
```

**Examples:**

- List every embedded document: `i9 docs`
- Print a document: `i9 docs cli`
- Machine-readable listing: `i9 docs --json`

**Exit codes:**

- `0`: Listed or printed
- `2`: Usage error
- `3`: Unknown or ambiguous document name
- `4`: This build carries no embedded documentation

### `i9 archive`

Inspect, validate, and manage i9io archives

Unified operations on i9io archives. Eight capabilities — ls, info,
validate, trust, rm, redact, purge, export-otel — cover discovery, integrity,
provenance, conversion and removal. `ls` enumerates the archives on this machine and says which
of them boot; `info` prints a one-line summary of ONE archive by default
and a per-kind breakdown with `--by-kind`. `validate` runs every
integrity check the archive supports (checkpoint, config, manifest) and
reports one verdict. `trust` lists and pins the producer keys whose
archives this install runs.

```
i9 archive
```

**Examples:**

- One-line summary of an archive: `i9 archive info ./run.i9io`
- Full integrity check: `i9 archive validate ./run.i9io`
- List the archives on this machine and which of them boot: `i9 archive ls`

**Exit codes:**

- `2`: Missing subcommand or not available in this build

#### `i9 archive ls`

List local i9io archives and whether each one boots

Enumerates the local boot targets on this machine — `*.i9io` and
`*.aio`, the two suffixes `i9 run <target>` accepts for a local
artifact — and answers, per file, whether `i9 run` can boot it.
`archive info` inspects ONE path you already hold; this is the verb
that tells you which paths exist.

Where it looks, with no positional:

  `<i9-home>`/builds          this install's own build output
  `<state dir>`/parked        sessions `vm stop` parked
  `<i9-home>`/snapshots       `vm save` output
  the working directory     (not recursed)

A positional names any other file or directory to scan instead, so an
artifact kept elsewhere is one argument away. A parked archive and a
`vm save` snapshot list as bootable, because `i9 run` boots them on the
host that saved them. An archive with no boot source, such as a trace
archive, lists with `boot no` and a `reason`.

Two facts decide bootability, and both are read from the file rather
than inferred from its name:

  bootable  the segment table is one `i9 run` takes as a boot target —
            a kernel and an initramfs, a checkpoint parent reference
            (a parked layer carries no boot segments of its own; its
            parent supplies them), or a checkpoint with its boot record
            (a `vm save` snapshot; the record names the root the restore
            re-adopts). The check is the one the run side makes before it
            boots a local archive.
  trust     which pinned key its authorship key resolves to —
            `authority`, `local-producer`, `pinned-producer` (a peer
            install's key pinned with `i9 archive trust add`), or `unknown`

Both are load-bearing, and they answer different questions.
`runnable` is what `run` will accept, decided on provenance and never
on where the file came from: a row whose signer is `unknown` is
runnable only where `provenance.mode` lets an unknown signer through
(`development`, or `interactive` at a terminal, where `run` asks
first). An agent, `--json` or a non-TTY stdin without that setting is
`strict`, so the same row is not runnable there and `reason` carries
the refusal. `trust` is who wrote it, and `unknown` there is the fact
to weigh before booting something a caller handed you. A row is
non-runnable when it lacks a boot segment, or when its signer
resolves nowhere and the mode in force refuses that.

Neither is inferred from the filename. Names carry no authority here: a
`.boot.i9io` whose segment table lacks a kernel lists as `bootable:
false`, and two files a pipeline named `.boot` and `.ingest` list
identically when they carry the same segments, because the bytes are
what is read.

Every root is reported with whether it existed AND whether it could be
read: a directory this install lacks permission on carries `unreadable`
rather than reporting zero archives, and a listing cut short partway
says so instead of presenting itself as complete. "Nothing there",
"could not look" and "did not finish looking" are three answers, and
collapsing them is the failure this verb exists to avoid.

Reads the segment table through one mmap per file and a 64 KiB prefix
read for the authority probe; no payload is copied and nothing is
extracted to disk, so a directory of multi-gigabyte VM images lists in
flat RSS.

```
i9 archive ls [root] [--json]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--json` | boolean | False | Machine-readable JSON output |

**Examples:**

- What can this install boot: `i9 archive ls`
- The same, for a script or an agent to read: `i9 archive ls --json`
- Scan an artifact directory kept outside the i9 home: `i9 archive ls ~/i9-artifacts`

**Exit codes:**

- `0`: Listed (including zero archives, and including roots that do not exist)
- `3`: Usage error

#### `i9 archive info`

Inspect an archive: a one-line summary, a by-kind rollup, or every segment

Read an archive you did not write, without booting it or extracting
anything. The default is one line: the file's size, how many segments it
holds, whether it was sealed, and the archive it layers on, if any. A
damaged archive adds a line saying so, and so does a snapshot whose
referenced chunks are not in this install's snapshot chunk store (`not
restorable here`; `--json` carries `chunk_store` and `restorable_here`).
`--by-kind` groups the segments by
semantic category (Meta/Traces/Snapshots/Config/Indices/Accel, with
span/snapshot/config decode where the category has one); `--verbose` lists
every segment (index, kind, flags, body offset/length, hash). All three
read the same mmap'd bytes.

`--by-kind` is the categorized view: `--verbose` under it also breaks
each category down by segment kind. `--json` renders any view as one
JSON object on stdout.

```
i9 archive info <path> [--by-kind] [--verbose] [--json]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--by-kind` | boolean | False | Group segments by semantic category (traces/snapshots/config/…) instead of the one-line summary |
| `--verbose` | boolean | False | List every segment (index, kind, offsets, hash); with --by-kind, show per-segment-kind counts and bytes within each category |
| `--json` | boolean | False | Machine-readable JSON output |

**Examples:**

- A one-line summary: `i9 archive info ./run.i9io`
- A rollup by semantic category instead: `i9 archive info ./run.i9io --by-kind`
- Every segment: `i9 archive info ./run.i9io --verbose`
- The same, for a script to read: `i9 archive info ./run.i9io --json`

**Exit codes:**

- `0`: Info displayed
- `1`: `<path>` could not be mapped into memory
- `2`: Usage error
- `3`: `<path>` cannot be opened
- `4`: `<path>` is empty or not a readable i9io archive (header, chain or framing error, naming the offset); the same bytes fail `archive validate` with the same code. Under --json the error envelope names the code and the fault, and carries the damaged segment as fields: `offset` (its first byte) and `segment` (its 0-based index). A damaged archive is refused by every view, text and --json alike

#### `i9 archive validate`

Validate an archive's structure and check who signed it

Validate an i9io archive's structure, (with --class) assert it carries a
specific asset class, and report whether its signing key resolves in this
build's embedded authority set, as this install's own producer key, or as
a peer install's producer key pinned with `i9 archive trust add`
(`trust=pinned-producer`). An archive that resolves to none of them is
reported as `signer not recognized`
with its kid (`trust=unknown` under `--verbose` and in `--json`), and is
still VALID: the structural checks are what decide the exit code. `--require-trusted` turns an unresolved signer into a refusal (EREFUSED,
exit 6), which is the strict question asked of one archive. `i9 run` and the VM-image boot path
ask it too, under the mode in force (`provenance.mode`): strict refuses an
unresolved signer, interactive asks you at a terminal, development lets it
through under a warning, for a file and a URL alike.

Every segment's payload is hashed, and every blob-span body (a VM image's
root filesystem) is hashed chunk by chunk against the chunk table its
signature commits to, so a single flipped byte anywhere fails the archive
(EVALIDATION, exit 4), naming the segment; `i9 archive info` reports the
same damage.

A snapshot keeps its memory and disk in the snapshot chunk store of the
home that saved it. When the archive references chunks this install's store
does not hold (a copy made without its store), the verdict line adds `not
restorable here: N of M referenced chunks are not in the snapshot chunk
store`, and `--json` carries it as `restorable_here` and the `chunk_store`
check. The bytes are still valid, so the exit status is unchanged; to move
such a snapshot, run `i9 snapshot export` on the machine that saved it.
Looking reads the store in place and creates nothing.

For checkpoint archives, runs three CPU-only integrity checks: the
per-window BLAKE3, the checkpoint manifest decode, and the config-tree
decode. Each is present-and-valid, present-and-broken, or absent (listed
under `--verbose` and in `--json`) — absence is the ordinary case for a non-checkpoint archive
(trace or build output) and is never a failure; a present-but-broken
one fails (exit 4) because a checkpoint that decodes today and fails
restore tomorrow is exactly what these checks exist to catch.

```
i9 archive validate <path> [--class <unspecified|checkpoint|bootable-aio|agent-vm>] [--verbose] [--expect-commit <string>] [--require-trusted]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--class` | enum: unspecified, checkpoint, bootable-aio, agent-vm |  | Expected asset class to validate the archive against |
| `--verbose` | boolean | False | Also list each check (window index, config tree, manifest) and the segment, verified and trust counts |
| `--expect-commit` | string |  | Refuse (EVALIDATION) unless the archive holds this commit (a commit_id, 64 hex digits; `archive info` prints it) and every frame it covers: a truncation to an earlier commit, a deleted, reordered or substituted frame, or another archive is refused |
| `--require-trusted` | boolean |  | Also refuse (EREFUSED, exit 6) when the signing key resolves to no pinned authority; without it the trust verdict is reported and a well-formed archive is valid |

**Examples:**

- Structure, and whose key signed it: `i9 archive validate ./run.i9io`
- Refuse an archive this build does not trust: `i9 archive validate ./run.i9io --require-trusted`

**Exit codes:**

- `0`: Archive valid; prints `valid: <path>`, and names the signer only when it resolves to no pinned key (`--verbose` adds the checks, counts and trust verdict; `--json` prints one object)
- `1`: `<path>` could not be mapped into memory
- `2`: Usage error, or unknown --class
- `3`: `<path>` cannot be opened
- `4`: `<path>` is empty or not a readable i9io archive; it is not a complete snapshot (INCOMPLETE: unsealed, a capture staging file the writer never sealed, or truncated, naming the missing seal, directory or segment; `vm rewind` refuses the same file with the same words). An open append log (catalog, traces) is not refused: its structure is validated, and an `open:` line says it is not sealed; segment composition violates the artifact grammar; or a segment failed verification (signature or payload hash), or a present checkpoint window/manifest/config_root failed its decode or hash check. The bytes are wrong: copy or export the archive again. Under --json the error envelope carries the damaged or missing segment as fields where known: `offset` (its first byte) and `segment` (its 0-based index)
- `6`: --require-trusted and the signing key resolves to no pinned authority (the kid is named on stderr). The bytes verified; trust the signer or re-create the archive on this install

#### `i9 archive trust`

List, pin and unpin the producer keys this install runs archives from

An archive runs here when its signer resolves to a key this install trusts:
an authority embedded in this build, this install's own producer key, or a
peer install's producer key pinned here. Pinning is how a VM image or
snapshot written on one host runs on another under strict provenance,
without relaxing `provenance.mode` and without copying a private key
between hosts.

On the install that wrote the archive, `i9 archive trust ls` prints its
producer key (`this-install`). On the install that will run it, `i9 archive
trust add <key>` pins that key. A pin is the whole 64-character public key,
never the 16-character kid a refusal names: the kid selects, the key
decides. A pin trusts that one producer, for booting its images and
restoring its states or for one of the two (`--for`), under every
provenance mode, and nothing else: unknown signers stay refused under
strict, and a pin never trusts a grant.

Pins live in `$I9_HOME/trusted-producers/<kid>.pub` (boot and restore),
`trusted-producers/boot/<kid>.pub` or `trusted-producers/restore/<kid>.pub`, one 32-byte public key
per file, owner-only. A pin file another user could write, or whose name is
not its key's kid, trusts nothing; `ls` lists it as rejected with the
reason. Every archive trust decision records `pins_loaded` and
`pins_rejected` on its `i9.archive.trust_check` span.

```
i9 archive trust
```

**Examples:**

- Print this install's producer key: `i9 archive trust ls`
- Pin a peer's key, then run its snapshot under strict: `i9 archive trust add 5b9437adeaffbe8f41b13d96ed49d2f51cd6c266cd8ecc284b0552ec4912b8dd`

##### `i9 archive trust ls`

List this install's producer key, the pinned peer keys, and the embedded authorities

One row per key this install runs archives from, with its source:
`this-install` (the key to hand to a peer; absent until this install
has written an archive), `pinned`, and `authority`. A pin file that
trusts nothing is listed as `rejected` with the reason.

```
i9 archive trust ls
```

**Examples:**

- Print this install's producer key to pin on a peer: `i9 archive trust ls`

**Exit codes:**

- `0`: Listed

##### `i9 archive trust add`

Pin a peer install's producer public key

Pins KEY, the 64-character hex public key `i9 archive trust ls` prints
on the install that wrote the archive. Pinning a key already pinned,
this install's own key, or an embedded authority's key writes nothing
and says which.

```
i9 archive trust add <key>
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--for` | enum: boot, restore, boot,restore |  | What the key may supply: images to boot, states to restore, or both (the default) |

**Examples:**

- Trust archives written by a peer install: `i9 archive trust add 5b9437adeaffbe8f41b13d96ed49d2f51cd6c266cd8ecc284b0552ec4912b8dd`

**Exit codes:**

- `0`: Pinned, or already trusted
- `2`: KEY is not a 64-character hex public key (a kid is not enough), or --for is not boot, restore or boot,restore
- `1`: The pin could not be written; the message names the path

##### `i9 archive trust rm`

Remove a pinned producer key

Removes the pin named by KID (or by its whole KEY). Archives that
producer wrote are refused again under strict from the next decision
on; a VM already running from one keeps running.

```
i9 archive trust rm <kid>
```

**Examples:**

- Stop trusting a peer install: `i9 archive trust rm 5b9437adeaffbe8f`

**Exit codes:**

- `0`: Removed
- `3`: No pin of that kid
- `2`: Not a kid or a key

#### `i9 archive rm`

Delete a checkpoint archive, refusing by default if layers descend from it

Deletes one or more checkpoint archives. Before deleting, scans the
archive's own directory for layers that name it as their base, and REFUSES
if any exist.

That check is the default rather than a separate command to remember,
because descent is recorded in the child: an archive cannot say on its own
whether anything depends on it, so "is this safe to delete?" is always a
question about other files. Deleting a base out from under a layer turns
that layer into permanent garbage: its delta has no base to apply over,
and nothing can recover one.

`--cascade` takes the dependent layers with it, deepest first, so an
interrupted run leaves a shorter valid chain rather than a set of orphans.
`--force` deletes anyway and NAMES the archives it orphaned, because the
cost of that choice is paid later by whoever tries to restore one and this
is the only moment we can say which files went bad.

Each deleted archive also releases its bytes in the home's snapshot chunk
store: the store drops the archive's root and frees every chunk no remaining
archive references, so the disk space comes back. The verdict reports the
bytes freed and the bytes other archives still hold. A store a running VM
holds is not waited for: the removal is recorded and the next removal frees
the chunks.
`--dry-run` deletes and releases nothing.

Exit code 3 is reserved for the refusal, so a script can branch on it
without parsing text.

```
i9 archive rm <path> [--cascade] [--force] [--dry-run]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--cascade` | boolean |  | Also delete every layer that descends from the target |
| `--force` | boolean |  | Delete despite dependents, leaving them orphaned and unrestorable |
| `--dry-run` | boolean |  | Report the plan without deleting anything |
| `--dependents-dir` | string |  | Scan this directory for dependents instead of the archive's own |

**Examples:**

- Delete a checkpoint, refusing if layers descend from it: `i9 archive rm ./run.i9io`
- See what a cascading delete would take, without deleting: `i9 archive rm ./base.i9io --cascade --dry-run`

**Exit codes:**

- `0`: Archives deleted (or plan reported under --dry-run)
- `1`: A target was missing or could not be deleted
- `2`: Usage error, including --cascade together with --force
- `3`: Refused: layers descend from the target

#### `i9 archive redact`

Redact segments from an archive

Mark a span's content bytes unreadable while keeping the archive
structurally valid. The redacted bytes stay at their chain position
until `i9 archive purge` writes a new archive without them, so
redaction alone is reversible — purge is the destructive step. A
reason (privacy_leak, user_request, other) is recorded
in the redaction record.

```
i9 archive redact <path> <span-id> <reason> [reason-text]
```

**Examples:**

- Redact one span, with a reason: `i9 archive redact ./run.i9io <SPAN_ID_HEX> privacy_leak`

**Exit codes:**

- `0`: Redaction applied
- `1`: I/O error: archive unreadable, or write failed
- `2`: Malformed invocation: argument count, a span id that is not 16 hex characters, or an unknown reason
- `3`: No archive at the path, or no span with that id in it
- `4`: The archive is signed by no key this install holds, or it refused the redaction

#### `i9 archive purge`

Purge redacted segments into a fresh archive

Drops the named chain positions (a `redact`'s target segment, typically)
from `<input>` and writes the result to `<output>` as a NEW artifact with a
fresh bundle_uuid — never in place, and `<output>` must differ
from `<input>`: the dropped bytes still exist at `<input>`'s original
chain position until `<output>` replaces it, so a purge that failed
halfway never leaves a half-purged archive under the name callers
still trust. `<output>` is re-signed with the key that authored `<input>`
(this install's producer identity, or the deterministic trace-signing
family for a trace-class archive).

```
i9 archive purge <input> <output> [positions]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--pack` | boolean | False | Also carry every window and disk region the snapshot keeps in this home's snapshot chunk store, so the output restores on another host |

**Examples:**

- Drop redacted chain positions into a fresh archive: `i9 archive purge ./run.i9io ./purged.i9io 3`

**Exit codes:**

- `0`: Purge complete
- `1`: I/O error, or `<input>` is not a readable/re-signable artifact
- `2`: Signing key mismatch (the archive's authorizing key matches neither this install's producer nor the trace-signing family) or purge operation failed
- `3`: Usage error: wrong arg count, `<output>` equals `<input>`, or `<positions>` is not a comma-separated list of unsigned integers

#### `i9 archive export-otel`

Export an i9io archive's spans as an OTLP trace protobuf

Reads a .i9io archive's span_batch segment(s), resolves each span's
attributes against its attr_key_pool/attr_value_pool, and writes an
OTLP ExportTraceServiceRequest-shaped protobuf file carrying every
span with its events, links, kind, status and typed attributes.
Spans are grouped into ResourceSpans/ScopeSpans by their
otel.resource.*/otel.scope.* attributes; a span with none is under
resource service.name "i9" (with the archive's session.id) and
scope "i9". Reading the output back into an archive returns the same
span set.

```
i9 archive export-otel <input> <output> [--omit-redacted]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--omit-redacted` | boolean | False | Skip redacted spans entirely instead of exporting them |

**Examples:**

- Export an archive's spans as an OTLP protobuf: `i9 archive export-otel ./run.i9io ./run.otlp.proto`

**Exit codes:**

- `0`: Exported; wrote `<output>`
- `1`: Could not read `<input>` or write `<output>`
- `3`: Usage error, or the archive could not be parsed

### `i9 vm`

Manage running VMs — list, attach, exec, save, stop, fork

A VM is a running machine: a live process you can exec into, copy
files into, attach to, forward ports to, save, fork, and stop.

`i9 run` creates a VM. `i9 vm ls` lists running VMs. Every other
verb takes the VM's control URL (also printed by `i9 vm ls`).

Saving a VM creates a snapshot. Stopping a VM saves first (unless
--discard is passed). Forking a VM branches its state into a
second, independent VM.

```
i9 vm
```

**Examples:**

- List running VMs: `i9 vm ls`
- Run a command in a VM: `i9 vm exec <URL> -- uname -a`
- Save a restore point: `i9 vm save <URL> --description 'before upgrade'`
- Stop with save (default): `i9 vm stop <URL>`
- Fork a VM from its current state: `i9 vm fork <URL> --name experiment`

**Exit codes:**

- `2`: Missing subcommand

#### `i9 vm ls`

List VMs running on this machine

Lists every VM currently live on this machine, discovered from the
local session registry. Each row is tab-separated: id, name (`-` when unset),
pid, age, control URL, state and kind. On a terminal a header row names
the columns and the age carries a unit (`42s`, `7m`, `3h`, `2d`); piped,
there is no header and the age is whole seconds. Crash-reconciled: a VM whose process died
without recording a stop event does not appear.

The state column is the VM's own server answering, the same verdict
`vm status` prints: `running`, `paused` (`vm resume` it), `parked`,
`unreachable` (a fork child whose parent was restored, or a server
that does not answer; `vm stop --discard` frees its slot) or
`stopped`. A VM in the middle of an exclusive save or restore stays
`running` and appends `(busy: <op>)`; `--json` carries it as `busyOp`.
A VM that is still booting or restoring is listed from the moment its
`i9 run` takes it, as `starting` with no control URL (`-`) yet; `vm
stop` ends it by name or id.

The text output ends with the number of VMs listed and how many vCPUs
count against the cap, the same count `i9 grant show` reports.
`i9 vm stop` frees a VM's vCPUs: it saves the VM and ends it
(`--discard` ends it without the save).

The cap is per user on this machine, not per home. A VM another home
started (`--home <dir>`) counts against it too, so it is listed after
this home's rows with its home, name when that home names it, pid,
vCPUs and control URL (the columns `HOME NAME PID VCPUS URL VERB` on a
terminal), so the VM holding the room can be found and stopped. `--json`
carries every row with a `home` field, and the other homes' rows add
`millivcpus` and `state: other-home`.

```
i9 vm ls [--show-token]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--show-token` | boolean |  | Print each VM's control URL with its bearer token, for a caller on another machine. Without it the URL is printed without the token on a terminal, a pipe and --json alike, and a vm verb given that URL takes the token from this machine's own registry |

**Examples:**

- What VMs are running on this machine: `i9 vm ls`

**Exit codes:**

- `0`: Operation complete (including zero live VMs)

#### `i9 vm attach`

Connect to a running VM's console

Dials the VM's control URL and streams its console PTY. With
`--command`, runs one command line, then exits the shell, prints the
output, and exits with the shell's status.
Without it, streams interactively until the shell exits, the server
closes or SIGINT/SIGTERM arrives. A terminal's keystrokes are forwarded.
A stdin that is not a terminal is not read, because it belongs to the
caller's script, with one exception: a stdin that is already at end of
input (`</dev/null`, an empty file) hands the shell end-of-input, as
`ssh host </dev/null` does, so the shell exits and the attach ends with its
status instead of waiting forever. The end-of-input is sent once the shell
shows it is reading a line (as bash and zsh do); a shell that never shows
that, such as plain `sh`, is left to `--timeout-ms`.

```
i9 vm attach [--url <string>] [--tab <string>] [--command <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--url` | string |  | VM name (its run --name) or control URL — attach to its console PTY |
| `--tab` | string |  | With --url: console tab id to attach to (default: control-shell) |
| `--command` | string |  | With --url: run one command line, print its output, and exit with the shell's status |
| `--token` | string |  | With --url: agent token |
| `--timeout-ms` | integer | 15000 | With --url: bound on the connect+ready wait, and always on --command runs |

**Examples:**

- Connect to a running VM's console: `i9 vm attach --url <URL>`

**Exit codes:**

- `0`: Operation complete
- `2`: Usage error
- `5`: Network error
- `7`: Server reported an error
- `3`: The target is a saved snapshot, not a running VM

#### `i9 vm exec`

Run a command in a VM's guest

Clean argv, stdout/stderr passed through, exit code is the remote
command's exit code. The scripting counterpart to `vm attach`. When i9
recognises the caller as an agent, a non-zero exit adds one line on
stderr after the command's own: `i9: exit <N>; see what it did: i9 trace
show <id> --session <pid> --internal; where its time went: i9 trace stats
--by slowest --where 'under(span_id = <id>)' --session <pid>`, with
` (timed out)` after the number when
`--timeout-ms` ended the command; any other caller gets the command's
stderr alone.

A refusal from i9 itself means the command never started: a `--secret`
that is not set (exit 3) or cannot be delivered (exit 6), a VM that is
paused, busy or gone. It prints `error: ...` and a `hint:` line on stderr;
with `--json` it prints `{"error": {"code", "exit", ...}}` on stderr and
nothing on stdout. A command that ran has no such line or object, whatever
its status; with `--json` its result is the object on stdout with
`exitCode`. Tell the two apart by that envelope, never by the number: 3 and
6 are also statuses a command can exit with.

`--shell` runs ONE script under `sh -c`: pass it as ONE quoted argument
after `--`. Several words after `--shell --` are refused (exit 2, "takes
the script as one argument") before the command starts.

Output is bytes, unchanged: NUL and non-UTF-8 bytes reach your stdout
and stderr exactly as the command wrote them. Arguments are text: each
must be UTF-8, and one that is not is refused by its position before the
command starts, never changed into a different value.

Standard input is forwarded as `ssh` forwards it. The command starts at
once, and this command's stdin is streamed to it while it runs, in chunks
with no size limit, then closed when it ends, so `printf x | i9 vm exec
<url> -- cat` prints `x`. A command that does not read its stdin does not
hold the stream: the exec returns when the command exits, whether or not
stdin is still open, so `sleep 1000 | i9 vm exec <url> -- true` returns
at once. A terminal stdin is not forwarded; the command's stdin is then
/dev/null. Inside a `while read` loop the exec reads the loop's input, as
`ssh` does: give it `< /dev/null`.

Output arrives as the command writes it, to a file or a pipe as to a
terminal, so `i9 vm exec <url> -- make > log 2>&1 &` can be followed with
`tail -f log`. What the command writes is what you get, when it writes it:
a program whose stdout is a pipe rather than a terminal may hold its own
output back (C programs buffer a pipe in blocks), exactly as under `ssh`
without `-t`. Ask that program for line buffering (`stdbuf -oL`,
`python3 -u`). A guest image built before output streaming returns the
output when the command exits instead.

A command killed by `--timeout-ms` exits 124 and says so on stderr:
"error: i9 vm exec: the command did not finish within N ms and was killed
(exit 124); raise --timeout-ms, or omit it to wait for the command to
exit". With `--json` the exit is still 124, `timedOut` is true, and
there is no stderr line.

When this command exits or is killed, the command it started in the VM
is ended with it: its process group gets SIGTERM, then SIGKILL after 2 s.
A process the command detached with `setsid` outlives it, and
`--timeout-ms` still bounds the command.

With `--json`, or from a guest image built before output streaming, one
exec returns at most 8 MiB of each of stdout and stderr (about 11 MiB for
both together); a command that writes more is cut there and the verb exits
6 naming the limit. For larger data write a file in the VM and copy it out
with `vm cp --from-guest`.

With `--json` the result is one object, reported when the command ends. A stream that is not clean text
(invalid UTF-8, or a NUL) is the base64 of its bytes, marked by
`stdoutEncoding` / `stderrEncoding` set to "base64"; a text stream has no
encoding field. `stdoutTruncated` / `stderrTruncated` are true when the
guest cut that stream at its limit.

```
i9 vm exec <server-url> <command> [--shell] [--cwd <string>] [--env <string>] [--secret <string>] [--secrets-profile <string>] [--timeout-ms <integer>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--shell` | boolean | False | Run the command through a shell; the script is ONE quoted argument after `--`, so `--shell -- 'cd /w && make'`, never `--shell -- cd /w && make` |
| `--cwd` | string |  | Working directory for the command |
| `--env` | string |  | Set an env var (KEY=VAL), repeatable |
| `--secret` | string |  | Give the command a stored secret by name (NAME or NAME,NAME), repeatable; values never appear on the command line |
| `--secrets-profile` | string |  | The secretspec.toml profile to admit (default: default). A secretspec.toml in the working directory is admitted before the VM is reached: every secret it grants is given as --secret. vm exec never changes the store: a declared secret the store does not hold yet is refused by name, and `i9 run` or `i9 secret set` on the host stores it; an exec it would refuse never reaches the VM. `i9 secret check` shows the plan |
| `--timeout-ms` | integer |  | Kill the command after this many milliseconds (default: none, it runs until it exits) |

**Examples:**

- Run one command in the guest: `i9 vm exec <URL> -- ls /workspace`
- Feed the command its stdin: `printf 'one\ntwo\n' | i9 vm exec <URL> -- sort -r`
- Run through a shell in a chosen directory (the whole script is ONE quoted argument): `i9 vm exec <URL> --shell --cwd /workspace -- 'make -j4 && ls build'`
- Give the command a stored secret as an environment variable: `i9 vm exec <URL> --secret OPENAI_API_KEY -- python3 agent.py`

**Exit codes:**

- `2`: Missing `<server-url>` or the command after --
- `8`: A --secret NAME is a reference whose backend tool (op) is missing or could not run
- `5`: Could not connect
- `7`: The session server reported an error
- `3`: A --secret names a secret that is not set; the command never started (`i9 secret ls` shows the names)
- `6`: A --secret could not be delivered (expired, no custodian, store unusable, too large for the VM's slot) and the command never started; or the command wrote more output than one exec returns (8 MiB per stream) and the output was cut at the limit
- `11`: The VM is paused; `vm resume` it
- `12`: The VM can never answer again (its VM process exited, its parent was restored or destroyed, or its backing object failed), but the snapshots it saved are intact: `i9 run <snapshot>` boots one and `vm stop --discard` frees its slot
- `13`: The VM is busy with a save, fork, stop or rewind; wait for it to finish, then run the command again
- `14`: A rewind replaced the VM while the command was running; it did not finish, so run it again on the restored VM only if what it had already done outside the VM (a push, a request) is safe to repeat
- `1`: The secret store could not be opened
- `*`: Any other status is the guest command's own exit status, passed through unchanged with no error envelope; a guest that itself exits with a number in this table looks like that error by status alone, so tell them apart by i9's `error:` line on stderr, or under --json by the error envelope against the result's `exitCode` and `timedOut`

#### `i9 vm cp`

Copy files into or out of a VM's guest

Copies a file or directory. Source first, destination second.
`cp <url> <local-src> <guest-dst>` copies in; add `--from-guest`
to reverse. Directories recurse automatically; a symlink inside one is
recreated as a symlink with the same text, never followed. The guest
path names the filesystem `vm exec` sees.

```
i9 vm cp <server-url> <src> <dst> [--from-guest] [--mode <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--from-guest` | boolean | False | Reverse direction: copy guest -> local |
| `--mode` | string |  | Octal mode set on every regular file copied into the guest, a single file or each file of a directory (refused with --from-guest) |

**Examples:**

- Copy a file into the guest: `i9 vm cp <URL> ./build.sh /workspace/build.sh`
- Copy a directory out: `i9 vm cp <URL> /workspace/out ./out --from-guest`

**Exit codes:**

- `2`: Missing `<server-url>`, `<src>`, or `<dst>`; or --mode given with --from-guest
- `5`: Could not connect or I/O error
- `3`: The path to copy out of the guest (--from-guest) does not exist there; nothing was copied
- `6`: A file copied into a VM whose image predates large copies in; nothing was written. Use a current image
- `11`: The VM is paused; `vm resume` it
- `12`: The VM can never answer again (its VM process exited, its parent was restored or destroyed, or its backing object failed), but the snapshots it saved are intact: `i9 run <snapshot>` boots one and `vm stop --discard` frees its slot
- `13`: The VM is busy with a save, fork, stop or rewind; wait for it to finish, then run the command again

#### `i9 vm ports`

Publish or unpublish a host-to-guest port on a running VM

Opens (or closes) a host-to-guest port forward on a VM that is
already running. No guest cooperation: the forward is entirely
host-side.

`--publish <host>:<guest>[/tcp|/udp]` binds the host port and
proxies to the guest. `--unpublish <host>[/tcp|/udp]` drops it.
Protocol defaults to tcp. Exactly one of the two is required: there is
no list form, so `i9 vm ports <url>` alone is a usage error (exit 2), and
neither `vm status` nor `vm ls` reports the forwards a VM has.

```
i9 vm ports <server-url> [--publish <string>] [--unpublish <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--publish` | string |  | Publish a forward: `<host-port>`:`<guest-port>`[/tcp|/udp] |
| `--unpublish` | string |  | Remove a forward: `<host-port>`[/tcp|/udp] |

**Examples:**

- Publish a guest port on the host: `i9 vm ports <URL> --publish 8080:80`
- Take it down: `i9 vm ports <URL> --unpublish 8080`

**Exit codes:**

- `2`: Missing `<server-url>`, neither or both of --publish/--unpublish, or an unparseable port spec
- `3`: The server answered the handshake with a refusal before readiness: the address names no live VM
- `4`: The VM host refused the publish: the host port is taken by another process, or already forwarded on this VM; the envelope's fix names the port to pick or the unpublish to run
- `5`: Nothing answered at `<server-url>`, or the connection failed after the handshake
- `6`: The server refused the change by policy; the envelope's hint is the server's own fix
- `7`: The session server opened the socket and never became ready, or refused the change for another reason (no live slirp pump, or no live forward on the host port an unpublish names)

#### `i9 vm egress`

Allow or block a host for egress on a running VM

Changes what a VM that is already running may reach OUT to, without a
stop and a re-run. The boot-time policy (`i9 run --egress`, `--allow`)
stays what the VM started with until this verb changes it. No guest
cooperation: the policy is entirely host-side, and the guest never learns
a rule changed.

`--allow <host>[:port]` grants the guest's outbound traffic to `<host>`,
scoped to one port when given, every port otherwise. `<host>` is an exact
name or one leading `*.` wildcard label, the same grammar as `run
--allow`. It returns once the rule is recorded, so the guest's next
connect to `<host>` is judged under it.

`--block <host>[:port]` revokes a grant and cuts any connection the
guest already has open to that host.

`--mode deny|warn|allow` switches the VM's whole egress mode live. `deny`
refuses everything no rule permits and cuts every open connection it now
refuses; `warn` permits and records what deny would refuse; `allow`
restricts nothing but the host's own networks. A VM that booted with no
policy gets one armed by the switch or by its first `--allow`. Given with
--allow or --block, the rule change lands first, then the mode.

Whatever the mode, the host's own networks (its LAN, VPN address,
loopback, link-local) are refused unless a literal-address rule names
them (`--allow 192.168.1.20:22`).

At most one of --allow / --block per invocation. With no flag at all,
this prints each destination the VM was recently denied, with a count
and the exact `--allow` command that would open it.

```
i9 vm egress <server-url> [--allow <string>] [--block <string>] [--mode <deny|warn|allow>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--allow` | string |  | Grant a host: `<host>`[:port] |
| `--block` | string |  | Revoke a grant: `<host>`[:port] |
| `--mode` | enum: deny, warn, allow |  | Switch the live egress mode; deny cuts every open connection no rule permits |

**Examples:**

- Let the VM reach one host: `i9 vm egress <URL> --allow api.example.com`
- Block it again: `i9 vm egress <URL> --block api.example.com`
- Lock the VM down to its grants now, cutting everything else: `i9 vm egress <URL> --allow api.example.com --mode deny`

**Exit codes:**

- `2`: Missing `<server-url>`, both --allow and --block given, an unknown --mode, or an unparseable host spec
- `3`: The server answered the handshake with a refusal before readiness: the address names no live VM
- `5`: Nothing answered at `<server-url>`, or the connection failed after the handshake
- `6`: The VM host refused the change by policy; the envelope's fix is the host's own
- `7`: The session server opened the socket and never became ready, or refused the change for another reason

#### `i9 vm save`

Capture the VM's state as a snapshot — the VM keeps running

Captures the VM's full state — memory, processes, devices — as a
content-addressed snapshot. The VM keeps running after the capture; a
VM that was paused stays paused, so `i9 vm resume` still thaws it.

The snapshot is a value: it can be restored later on this machine,
used as the base for new VMs, or rewound to. Restoring it does not
disturb the VM it came from.

A snapshot holds everything in the guest, including any credential or
token file copied in with `i9 vm cp`. Share a snapshot only with people
you would hand those secrets to.

```
i9 vm save <server-url> [--description <string>] [--out <string>] [--allow-live-secrets] [--consistency <crash|app>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--description` | string |  | A human-readable note stored with the snapshot |
| `--out` | string |  | Write the snapshot to PATH instead of under the i9 home; a PATH outside the home is refused while any secret is live in the VM |
| `--allow-live-secrets` | boolean |  | Write an --out snapshot outside the i9 home even though secrets are live in the VM; the override is recorded in the trace |
| `--consistency` | enum: crash, app |  | How consistent the capture is: crash (the default; the VM stops at one instant, as a power cut would leave its disk) or app (also every vCPU idle or in user code at that instant, as the host sees it; the guest is never asked). A capture whose instant was not quiescent is taken at crash and the reply names the vCPUs. Defaults to the capture.consistency config key |

**Examples:**

- Capture a VM's state: `i9 vm save <URL> --description 'before upgrade'`
- Write a snapshot to a file you will share: `i9 vm save <URL> --out ./handoff.i9io`
- Freeze the guest's workload for the capture: `i9 vm save <URL> --consistency app`

**Exit codes:**

- `0`: Snapshot captured
- `2`: Missing `<server-url>`
- `5`: Could not connect
- `6`: --out names a path outside the i9 home while secrets the VM was given are live (its guest may hold their values); the message names them
- `13`: Another state operation (save, rewind, fork, stop, pause or resume) is running on this VM; the message names it. Wait for it to finish, then run the command again
- `15`: The disk holding the i9 home is full, so nothing was saved and every earlier snapshot is intact; remove snapshots with `snapshot rm` or free space, then save again
- `7`: The save failed on the server's side, so nothing was saved; when files it was writing were removed while it ran, the hint says to run it again
- `3`: The target is a saved snapshot, not a running VM, or the VM refused the token this call presented

#### `i9 vm stop`

Save the VM's state and shut it down

By default saves the VM to a resumable archive, then tears down.
The archive path is printed so the VM can be resumed later with
`i9 run <archive>`.

`--discard` skips the save and destroys immediately. A failed save
leaves the VM running (exit 4) rather than destroying unsaved state.
A discard still leaves the run's trace archives (`sessions/` under the
i9 home) and the image page cache (`store/`), which later runs of the
same image reuse. `i9 store ls` lists the cache and `i9 store prune`
reclaims it; `i9 uninstall` removes both.

A VM whose i9 home was deleted while it ran keeps running, and `vm ls`
from any home lists it among the other homes' VMs by its pid, its home
marked `(deleted)`: its name and control URL were in that home. Stop it
by that pid with `--discard`, since there is nowhere left to save it
(`i9 vm stop <pid> --discard`); without `--discard` the stop refuses and
says so. A pid that is no such VM is refused and nothing is signalled.

A VM that is already stopped answers at exit 0 and says so: `VM was
already stopped`, with its snapshot path when one was saved, and
`alreadyDown: true` with its `state` under `--json`. Repeating a stop
is safe.

A VM that is still booting or restoring (`starting` in `vm ls`) stops
by its name or id too: its boot or restore is cancelled, the disk it
was provisioning is removed, and the stop answers once its process has
exited (`whileStarting: true` under `--json`). Nothing is saved, since
the VM never ran.

A save archives the one VM the URL names, so a stop that would also
end other forks refuses instead (exit 6) and stops nothing: a VM's
forks end with it, and a fork's own forks, at any depth, end with
that fork. The refusal names each fork by
its URL and, when a live fork is among them, prints the stop that
saves it: `i9 vm stop <fork-url>`. `--discard` is the consent: `i9 vm
stop <URL> --discard` ends the VM and every fork that would end with
it without saving, and names each one it ended (`--json`:
`endedForks`).

```
i9 vm stop <server-url> [--time <integer>] [--signal <string>] [--discard]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--time` | integer |  | Seconds to wait for graceful exit before SIGKILL (default: 10) |
| `--signal` | string |  | Signal to send instead of SIGTERM |
| `--discard` | boolean |  | Destroy without saving state (traces and the image page cache stay; i9 store prune reclaims the cache) |

**Examples:**

- Save and shut down (default): `i9 vm stop <URL>`
- Destroy without saving: `i9 vm stop <URL> --discard`

**Exit codes:**

- `0`: Operation complete, including a VM that was already stopped (alreadyDown: true)
- `2`: Missing `<server-url>`
- `3`: No VM recorded at that address
- `6`: Stopping this VM would end live forks no archive holds; stop each named fork with `i9 vm stop <fork-url>` first
- `5`: VM did not answer, orphaned, or save failed
- `7`: The session server reported an error
- `13`: Another state operation (save, rewind, fork, stop, pause or resume) is running on this VM; the message names it. Wait for it to finish, then run the command again

#### `i9 vm pause`

Freeze a VM in place

Pauses the VM's execution — all vCPUs stop. The connection stays
open and the VM is not torn down. `i9 vm resume` continues it
exactly where it stopped.

```
i9 vm pause <server-url>
```

**Examples:**

- Freeze the VM: `i9 vm pause <URL>`

**Exit codes:**

- `0`: VM paused, or already paused (nothing changed)
- `2`: Missing `<server-url>`
- `5`: Could not connect
- `7`: The session server reported an error
- `13`: Another state operation (save, rewind, fork, stop, pause or resume) is running on this VM; the message names it. Wait for it to finish, then run the command again
- `3`: The target is a saved snapshot, not a running VM, or the VM refused the token this call presented

#### `i9 vm resume`

Thaw a VM previously frozen by vm pause

Resumes the VM's execution from exactly where `i9 vm pause` left it.

```
i9 vm resume <server-url>
```

**Examples:**

- Thaw a paused VM: `i9 vm resume <URL>`

**Exit codes:**

- `0`: VM resumed, or it was not paused (nothing changed)
- `2`: Missing `<server-url>`
- `5`: Could not connect
- `7`: The session server reported an error
- `13`: Another state operation (save, rewind, fork, stop, pause or resume) is running on this VM; the message names it. Wait for it to finish, then run the command again
- `3`: The target is a saved snapshot, not a running VM, or the VM refused the token this call presented

#### `i9 vm revoke-secret`

Cut one VM off from a proxy secret without touching any other VM

Drops the VM's grant of the proxy-mode secret NAME. The VM's next request
carrying that secret's stand-in value is refused as unknown, and the VM
cannot ask for the secret again. Address a fork child by its own control URL to
revoke that child alone: its parent and siblings keep their grants, and the
stored secret is untouched. `i9 secret rm NAME` is the revoke for every VM
at once.

```
i9 vm revoke-secret <server-url> <name>
```

**Examples:**

- Cut one fork child off from OPENAI_API_KEY: `i9 vm revoke-secret <CHILD_URL> OPENAI_API_KEY`

**Exit codes:**

- `0`: The VM's grant of NAME was dropped
- `2`: Missing `<server-url>` or `<NAME>`
- `6`: The VM does not hold NAME, or NAME is not a proxy-mode secret; the VM's grants are unchanged
- `5`: Could not connect
- `7`: The session server reported an error
- `3`: The target is a saved snapshot, not a running VM, or the VM refused the token this call presented

#### `i9 vm fork`

Branch a running VM into two that diverge from the same state

Forks a VM. The child is a second, independent VM that begins at the
parent's exact current state and diverges from there.

The parent keeps running, unaffected, on Linux with KVM and on macOS
alike: each child runs in a process of its own.

This is a live branch, not a copy of a disk image. The child's
memory is demand-paged from a sealed copy-on-write view of the
parent.

Given a snapshot (the path `vm save` prints), the child starts at the
snapshot's instant instead. Fork it any number of times, now or
later: every child begins identical, and the snapshot is only read.
A snapshot fork starts a new VM of its own and leaves every running VM
as it was, on every host. It restores the saved state first, so it takes
longer than branching a running VM, which only pages memory in from its
parent. `vm ls --json` names the snapshot as that child's `parentId`; the
text listing has no such column, and a child forked from a running VM has
no `parentId`.

What a child shares with its parent: everything in memory and on disk
at the fork. That includes running processes, open files, and any
token, session or key a workload already holds. What differs: each
child has its own name and control URL, and its own hostname (its
name, or its VM id when it has none), machine id and SSH host keys,
set before anything can reach it; its guest kernel's random number
generator is reseeded through a fresh VM Generation ID, so two
children do not draw the same random bytes. A guest image whose agent
predates setting that identity keeps the parent's hostname, machine
id and keys, and the fork result says so.

A child's network addresses are its parent's: the guest address
(192.168.86.20/24), the MAC address and the gateway (192.168.86.1)
read the same in the parent and in every child. Each VM has its own
virtual network behind the host, so the identical addresses do not
conflict. To tell branches apart, use the name or control URL `vm ls`
prints, or `hostname` inside the guest.
A secret set with `--fork deny` (the default) is not delivered to the
child by i9: the child has no file at /run/i9/secrets/NAME. What the
parent's guest had already received travels with the fork in memory, so a
process that read the value keeps it in its environment. Re-issue the
credential when branches must not share it.

```
i9 vm fork <server-url> [--count <integer>] [--name <string>] [--secret <string>] [--secret-budget <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--count` | integer |  | How many children to fork, 1 (the default) to 64, all from the one state the parent is in; given a name, the children are `<name>`-0, `<name>`-1, ...; a running parent only; each child counts its vCPUs against the cap (`i9 grant show`), so the free tier fits one 2-vCPU child beside a 2-vCPU parent |
| `--name` | string |  | Name the child VM (with a count above 1, the prefix of each child's name) |
| `--secret` | string |  | Give the child a stored secret its parent holds under a deny fork policy (NAME or NAME,NAME), repeatable; a running parent only: from a snapshot, pass it to each i9 vm exec --secret |
| `--secret-budget` | string |  | Cap the requests this child may spend a proxy secret on: NAME=N, repeatable; NAME must also be given with --secret. The child counts its own requests from zero, never its parent's |

**Examples:**

- Branch a VM: `i9 vm fork <URL>`
- Name the branch: `i9 vm fork <URL> --name experiment-a`
- Start a child from a saved snapshot: `i9 vm fork <snapshot.i9io>`

**Exit codes:**

- `0`: Fork complete
- `2`: Missing `<server-url>`, or the child of a snapshot cannot detach: no i9 home, or a Windows build
- `5`: Could not connect to parent
- `6`: The concurrent VM limit is reached (the message gives the count and the cap), or this VM admits no more forks under it; stop a VM or install a grant, then fork again. A snapshot that needs a grant feature no grant turns on, or that a newer i9 wrote, is refused too, and the hint names the fix
- `13`: Another state operation (save, rewind, fork, stop, pause or resume) is running on this VM; the message names it. Wait for it to finish, then run the command again
- `1`: The secret store could not be opened
- `3`: The VM refused the token this call presented, or the snapshot file or the store that holds its memory and disk is gone
- `8`: The snapshot file cannot be read
- `4`: The snapshot file is not a complete i9 archive, or its bytes fail their recorded hash
- `7`: The child of a snapshot did not start: its restore, boot or guest agent failed, or the port the i9 config sets is in use

#### `i9 vm rewind`

Replace a VM's state from a snapshot

Rewinds the VM. With `<snapshot>`, restores that snapshot onto the
VM. Without it, walks the fork tree from the current VM up through
its ancestors to the nearest one that has a snapshot and restores
that VM's newest snapshot, naming it by the id `vm save` printed.

Both forms keep the VM's name, control URL and session, but the `vmId`
that `vm ls --json` reports changes (fvm-1 becomes fvm-2), so address a
VM by its name or URL, not its vmId. Both refuse while the VM has
live fork children: they are copy-on-write off the state being
replaced and would never answer again. The refusal names each child;
free it with `i9 vm stop <child-url> --discard`, then rewind. Take a snapshot before whatever
change you might want to undo.

Rewinding replaces the whole session's active VM, so a fork child
cannot be rewound on its own: given a child's name or URL it refuses
and names the session to run it on. To undo a child's changes, stop it
with `--discard` and fork again from a snapshot.

```
i9 vm rewind <server-url> [snapshot] [--from <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--from` | string |  | Walk from this vmId instead of the currently active one |

**Examples:**

- Rewind to a named snapshot: `i9 vm rewind <URL> before-upgrade`
- Rewind to nearest ancestor: `i9 vm rewind <URL>`

**Exit codes:**

- `0`: Rewind complete
- `2`: Missing `<server-url>`
- `6`: The VM has live fork children (stop each with `i9 vm stop <child-url> --discard` first), or `<server-url>` names a fork child, which cannot be rewound on its own (run the rewind on the session)
- `3`: No snapshot matches `<snapshot>` (the refusal lists the snapshots there are), no file is at its path, or no ancestor has a snapshot
- `4`: `<snapshot>` matches more than one snapshot (the refusal lists the candidates), or names a file that is not a restorable archive
- `5`: Could not connect
- `13`: Another state operation (save, rewind, fork, stop, pause or resume) is running on this VM; the message names it. Wait for it to finish, then run the command again
- `1`: The secret store could not be opened

#### `i9 vm status`

Status of a VM — live over its URL, or offline from its archive

With a control URL, reports each VM's live state: running/paused/stopped,
memory, boot phase, and whether it has a retained snapshot.

With a `.i9io` path, or the name of a VM parked on this machine, reads
the archive offline and answers as `i9 archive info` does: its size,
segment count, seal state and the archive it layers on.

```
i9 vm status <server-url> [--vm <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--vm` | string |  | Report just this vmId (default: every known VM) |

**Examples:**

- Status of a live VM: `i9 vm status <URL>`
- Status offline from an archive: `i9 vm status ./parked.i9io`

**Exit codes:**

- `0`: Operation complete
- `2`: Missing `<target>`
- `3`: Archive not found
- `5`: Could not connect or invalid archive

### `i9 agent`

Install i9 into AI coding harnesses

Per-harness MCP bootstrap. `i9 agent install` writes the i9 MCP server
config into every detected harness (Claude Code, Gemini, OpenCode, Pi,
Kiro auto-write JSON; Copilot CLI auto-writes JSON with its own
documented type/tools fields; Codex gets an `[mcp_servers.i9]` table
appended to its config.toml; Hermes gets a paste-ready YAML snippet).

```
i9 agent
```

**Examples:**

- Which harnesses are on this machine, and whether i9 is registered in each: `i9 agent list`
- Register i9's MCP server in every detected harness: `i9 agent install`
- One harness only, and show the change without writing it: `i9 agent install --harness claude-code --dry-run`
- Remove the registration everywhere: `i9 agent uninstall`

**Exit codes:**

- `2`: Missing subcommand

#### `i9 agent list`

Show which harnesses are on this machine and whether i9 is registered in each

One row per supported harness (claude-code, codex, gemini, opencode,
hermes, pi, copilot, kiro): detected — its binary is on PATH or its
config directory exists — and whether that harness's config carries
the i9 MCP server entry `agent install` writes. The two are separate
facts: a harness on the machine is not a harness that can reach i9.
A registered row also says STALE when the command the config launches
is not the i9 answering this call (another file after symlinks, or
none): that harness runs an older build until `agent install` is run
again. With `--json`, an array of `{harness, detected, binPath,
configDir, registered, command, stale}` where `registered` is
`registered`, `absent`, or `unreadable` (the config exists but does
not parse), `command` is the registered launch path when there is
one, and `stale` is true only for a registered row whose command is
not this binary.

```
i9 agent list
```

**Examples:**

- Which harnesses are here, and which can reach i9: `i9 agent list`
- The same, for a script to read: `i9 agent list --json`

**Exit codes:**

- `0`: Status printed

#### `i9 agent install`

Write the i9 MCP server config into detected harnesses

Scan for supported AI coding harnesses (Claude Code, Codex, Gemini,
OpenCode, Hermes, Pi, Copilot, Kiro) and write the entry that
launches `i9 mcp serve` into each one's config, under the path this
i9 was invoked as (a symlink or an in-place install path stays a
symlink, so a later build behind the same path is what the harness
launches). A harness named with
`--harness` is checked for presence first and refused if it is not on
this machine, so a checkmark always means a config a harness reads;
`--all` writes every supported config path regardless. Use `--dry-run`
to preview the changes. A harness reads its MCP config at startup, so
an install that changed one says to restart it. Besides each
harness's config and its next-steps skill file, it writes only what
every i9 command writes in its home: `versions.json` on the first run
in a fresh home, and its own trace under `state/traces`.

With `--json`, stdout is one document, written whether or not a
harness failed: `{harnesses, changed, failed, dryRun, restart,
outcomes, hints?}`. `changed` counts the harnesses whose MCP entry or
next-steps skill changed (would change, under `--dry-run`); `restart`
is true when a run changed one, install or uninstall: a running
harness reads its MCP config only at startup. Each outcome is `{harness, ok,
noop, summary, manualSnippet?, notice?, failure?, error?, path?}`; `failure` is
`not-detected`, `unreadable`, `unparsable`, `unterminated`,
`unwritable`, `skill-unwritable` or `readback`, and `manualSnippet`
is `{path, snippet}`
to paste by hand. `notice` is set when the install replaced a
registration that had `--write-tools` with one without it; stderr
carries the same line, naming the command that keeps them. When a harness failed, stderr also carries the
refusal envelope for the failure to fix first, and the exit is its
code.

```
i9 agent install [--harness <claude-code|codex|gemini|opencode|hermes|pi|copilot|kiro>] [--all] [--dry-run] [--write-tools]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--harness` | enum: claude-code, codex, gemini, opencode, hermes, pi, copilot, kiro |  | Target a single harness, refusing if it is not installed (default: all detected) |
| `--all` | boolean | False | Write into every supported harness config path, detected or not |
| `--dry-run` | boolean | False | Show what would change without writing |
| `--write-tools` | boolean | False | Register the write surface too, so the harness can boot a VM (i9_run) |

**Examples:**

- Register i9 with one harness: `i9 agent install --harness claude-code`
- Register with every supported harness, installed or not: `i9 agent install --all`
- Show what that would write, without writing: `i9 agent install --all --dry-run`

**Exit codes:**

- `0`: Installed (or nothing to do)
- `4`: A harness's config does not parse
- `8`: A harness's config could not be read or written
- `1`: A written config does not read back as expected
- `3`: A named harness is not installed on this machine
- `2`: Refused flag (--output or --source), or an unknown --harness

#### `i9 agent uninstall`

Remove the i9 MCP server config from detected harnesses

Remove the i9 MCP server entry from each detected harness's config.
The harness binary stays installed — only its ability to reach i9 is
revoked. With `--json`, stdout is the same document `agent install`
writes, and a failed harness adds the same refusal envelope on stderr.

```
i9 agent uninstall [--harness <claude-code|codex|gemini|opencode|hermes|pi|copilot|kiro>] [--all] [--dry-run]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--harness` | enum: claude-code, codex, gemini, opencode, hermes, pi, copilot, kiro |  | Target a single harness (default: all detected) |
| `--all` | boolean | False | Remove from every supported harness config path |
| `--dry-run` | boolean | False | Show what would change without writing |

**Examples:**

- Remove the i9 entry from one harness: `i9 agent uninstall --harness claude-code`
- Remove it everywhere: `i9 agent uninstall --all`

**Exit codes:**

- `0`: Uninstalled (or nothing to do)
- `4`: A harness's config does not parse
- `8`: A harness's config could not be read or written
- `1`: A written config does not read back as expected
- `2`: Refused flag (--output, --source or --write-tools), or an unknown --harness

### `i9 mcp`

Model Context Protocol server

Expose i9 verbs over stdio JSON-RPC so any MCP-aware agent harness
(Claude Code, Codex, Gemini, OpenCode, Hermes, Pi) can call i9 with
structured I/O. The tool table is GENERATED from the command schemas:
every command carrying an `mcp:` block is a tool, with its args and
flags as the tool input.

`write: true` is an OPT-IN GATE, not a read-only/write split. It marks
a tool that boots a new identity (i9_run), rewinds a session
(i9_vm_rewind), changes the secret store (i9_secret_set,
i9_secret_rm) or rewrites a durable archive; those appear only
with --write-tools. Every other tool is on by default, including the
whole session lifecycle (i9_vm_exec, i9_vm_ls, i9_vm_status,
i9_vm_fork, i9_vm_save, i9_vm_stop), which acts on the agent's own box, the
trace queries and i9_doctor. The served set is exactly what
`tools/list` returns; `i9 docs mcp-tools.md` prints the same table
for this binary, offline.

The server requests machine-readable output from the binary with the
global `--json` ahead of the verb (`i9 --json <verb> …`), never by
appending it: a trailing flag would be swallowed by
`i9 vm exec <url> -- cmd...`.

```
i9 mcp
```

**Examples:**

- Register i9 as an MCP server in every coding harness on this machine: `i9 agent install`
- What a harness runs for that registration: the tools on stdio: `i9 mcp serve`
- Also expose the write-gated tools (i9_run, i9_vm_rewind, …): `i9 mcp serve --write-tools`
- The tool table of this binary, offline: `i9 docs mcp-tools.md`

**Exit codes:**

- `2`: Missing subcommand

#### `i9 mcp serve`

Start the MCP server bound to stdio

Reads JSON-RPC requests on stdin, dispatches them to i9 verbs, and
writes results to stdout. This is the process `i9 agent install`
wires a harness to launch — running it by hand is for debugging
that wiring, not for normal use.

```
i9 mcp serve [--write-tools]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--write-tools` | boolean | False | Also expose the 12 tools the schema gates behind write: true — i9_archive_redact, i9_config_set, i9_config_unset, i9_grant_renew, i9_grant_request, i9_run, i9_secret_refresh, i9_secret_rm, i9_secret_set, i9_vm_egress, i9_vm_revoke_secret, i9_vm_rewind. The default set is not read-only: it carries the whole session lifecycle |

**Examples:**

- Serve the default tool set on stdio: `i9 mcp serve`
- Also expose the tools the schema gates behind a write: `i9 mcp serve --write-tools`

**Exit codes:**

- `0`: Server ran until stdin EOF / SIGTERM

### `i9 snapshot`

Export, remove and report on VM snapshots

Manage VM snapshots stored in i9io archives: copy one out for sharing, or
remove one.

To read an archive on disk without booting it use `i9 archive info`.

```
i9 snapshot
```

**Examples:**

- What does this archive hold?: `i9 archive info <FILE.i9io>`
- Copy a snapshot out for sharing: `i9 snapshot export <FILE.i9io> --out <DEST.i9io>`

**Exit codes:**

- `2`: Missing subcommand or not available in this build

#### `i9 snapshot export`

Write a snapshot as a standalone file for another host

Writes the snapshot to `--out <path>` as a standalone file. A saved
snapshot keeps its memory and disk in this machine's snapshot store
and holds only references to them; the export copies those bytes into
the file, so it restores on a host without this store. A snapshot of
a VM booted from the published image still names that image, so the
receiving host fetches it from a.i9.io. No projection or redaction:
the export carries everything the snapshot has, in plaintext, so a
key, `.env` or credential copied into the guest is readable by whoever
holds the file (`i9 archive redact` works on trace spans, not on guest
disk or memory), and the export says so when it writes. A snapshot whose
guest memory may hold a secret's value (a file or env value delivered to
the guest, or a proxy value an upstream's response carried back, which
the proxy records when it masks one) exports to a destination outside the
i9 home only with `--allow-live-secrets`; the refusal names each secret
and the evidence, and the override is traced. A proxy secret whose guest
only ever held its stand-in does not count: a stand-in works on no other
VM. A destination inside the i9 home exports without the flag and prints
the plaintext warning.

```
i9 snapshot export <bundle.i9io> [--out <string>] [--allow-live-secrets]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--out` | string |  | Destination path for the exported copy |
| `--allow-live-secrets` | boolean |  | Export to a path outside the i9 home even though the snapshot's guest memory may hold a secret's value; the override is recorded in the trace |

**Examples:**

- Export a snapshot for sharing: `i9 snapshot export ./checkpoint.i9io --out ./shared.i9io`

**Exit codes:**

- `0`: Exported successfully
- `2`: Missing source or --out
- `3`: Source not found
- `4`: Source is not a valid .i9io archive
- `6`: The snapshot's guest memory may hold a secret's value, the destination is outside the i9 home and --allow-live-secrets was not given
- `1`: The snapshot names chunks this machine's snapshot store cannot supply, so no standalone copy was written

#### `i9 snapshot rm`

Remove a snapshot and release the chunk-store bytes only it held

Removes a snapshot by its archive path, then releases every chunk in the
home's snapshot chunk store that no remaining snapshot references. It prints
the bytes it freed (the snapshot file plus the chunks released) and the
bytes still held by other snapshots that share chunks with it, so a removal
that returns little disk says why. A chunk another snapshot still names is
kept, and a snapshot saved before the chunk store kept a record of its
chunks keeps them. While a VM is restoring from the chunk store the chunks
are not released; the line says so and the next removal releases them.

```
i9 snapshot rm <path>
```

**Examples:**

- Remove a snapshot: `i9 snapshot rm ./old-checkpoint.i9io`

**Exit codes:**

- `0`: Removed
- `2`: Missing `<path>`
- `3`: Snapshot not found
- `1`: The snapshot file could not be deleted

### `i9 grant`

Manage grant tokens that raise the running-vCPU cap

A grant is a small signed bearer token that raises the free tier's
running-vCPU cap (default 16 vCPUs; each running VM counts as its vCPUs).
It is installed in this install's config, verified before it is stored,
and holds its own expiry: `show` prints the grant id, the cap in force,
what is running against it and when it expires; nothing running is
stopped when it does. `request` gets a free 7-day grant with no vCPU
limit and no account, `renew` renews it by its grant id any number of
times, and `install` installs a token you already hold.

```
i9 grant
```

**Examples:**

- Show the running vCPUs and the cap: `i9 grant show`
- Get a free 7-day grant with no vCPU limit: `i9 grant request`
- Renew the installed grant: `i9 grant renew`

**Exit codes:**

- `2`: Missing subcommand

#### `i9 grant show`

Show the installed grant (or the free-tier default)

Reads config key `grant`, verifies it against the embedded authority
set at the current time, and prints kid, tier, grant id, the vCPU cap,
renewals, expiry and validity — or the free-tier default (tier: free,
16.0 vCPUs) when no grant is installed. An invalid/expired/tampered
token is reported as `valid: false` with a reason, never a hard
failure — `show` is a read, not a gate. Every capped install also
prints the limit in force (vCPUs running at once per user on this
machine, each VM counting as its vCPUs) and how to lift it:
`i9 grant request` for a free 7-day grant with no vCPU limit, `i9 grant
renew` to extend it. `--json` carries the cap as
`max_millivcpus` and the vCPUs running now as `running_millivcpus`
(1000 = one vCPU), with the same limit and fix as `limits` and
`unlock`. `running_vms` lists each VM that count is made of (`pid`,
`verb`, `home`, `millivcpus`), whichever home started it; `i9 vm ls`
prints the same rows.

```
i9 grant show
```

**Examples:**

- Which grant this install is running under: `i9 grant show`

**Exit codes:**

- `0`: Grant info printed (including invalid/expired — validity is a field, not an exit code)
- `2`: Usage error (unexpected flag)
- `4`: A config layer failed to parse — the grant token may be present but unreadable

#### `i9 grant request`

Get a free 7-day grant with no vCPU limit and install it

Asks the issuer (https://i9.io/grant/request) for a free grant: no limit on
running vCPUs for 7 days, with a new grant id. The token is verified and installed
like `i9 grant install`, and the installed grant is printed. No payment
and no account. Renew it before or after it expires with `i9 grant renew`,
any number of times. A
machine that already holds a live grant is refused and told to renew it,
except with `--feature`, which adds the feature to that grant.
`--feature nested-virt` turns on `i9 run --nested-virt`.
The grant is a bearer token: it lives in this install's config, `i9 grant
show` prints its id, cap and expiry, and nothing running is stopped when
it expires.

```
i9 grant request [--feature <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--feature` | string |  | Also turn on this feature (an id `i9 grant show` lists, such as nested-virt): adds it to the grant this machine holds, or gets a free 7-day grant carrying it. The request is free, and i9.io records which feature was asked for |

**Examples:**

- Lift the vCPU cap for 7 days: `i9 grant request`

**Exit codes:**

- `0`: Grant obtained and installed
- `2`: The issuer asked for a contact address this run did not give
- `6`: This machine already holds a live grant (renew it), the issued token did not verify, the config could not take it, or i9.io is limiting this address
- `5`: i9.io could not be reached or answered unexpectedly

#### `i9 grant renew`

Renew a grant by its grant id for another 7 days

Submits the grant id to the issuer (https://i9.io/grant/renew) and
installs the renewed token: the same grant id, a fresh 7 days, and a
renewal count one higher. With no argument it renews the installed grant,
expired or not; with `<grant_id>` it renews that one. Renewal has no limit.

```
i9 grant renew [grant_id]
```

**Examples:**

- Renew the installed grant: `i9 grant renew`
- Renew a grant by its id: `i9 grant renew g-0123456789abcdef0123456789abcdef`

**Exit codes:**

- `0`: Grant renewed and installed
- `2`: No grant id given and none installed, or not a grant id
- `6`: The renewed token did not verify, or the config could not take it
- `3`: The issuer knows no grant with this id
- `4`: The issuer refused the grant id as malformed
- `5`: i9.io could not be reached or answered unexpectedly

#### `i9 grant install`

Verify and install a grant token

Verifies `<token>` against the embedded authority set (kid lookup +
Ed25519 signature + expiry) BEFORE touching config — a tampered or
otherwise invalid token leaves config.json byte-for-byte unchanged.
On success writes config key `grant` through the same config-write
path `i9 config set` uses, then
prints the same summary `i9 grant show` would.

The token is one argument, or the contents of `--from-file PATH` (`-` reads
stdin). A grant delivered into a guest with `--secret NAME` is at
`/run/i9/secrets/NAME`, so `i9 grant install --from-file /run/i9/secrets/NAME`
installs it without the token ever being on a command line.

```
i9 grant install [token] [--from-file <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--from-file` | string |  | Read the token from PATH (`-` for stdin) so it never appears in argv |

**Examples:**

- Verify and install a grant token: `i9 grant install <TOKEN>`
- Install a grant delivered into a guest by --secret OPS_GRANT: `i9 grant install --from-file /run/i9/secrets/OPS_GRANT`

**Exit codes:**

- `0`: Token verified and installed
- `2`: Missing/malformed argument, or the token failed verification (bad envelope, unknown kid, bad signature, or expired) — config unchanged

### `i9 secret`

Hold credentials for guests, kept out of argv, spans and traces; a snapshot of a guest that read one carries it

A secret set here is encrypted in one store under the i9 home, wrapped by
this host's custodian: the macOS Keychain or Windows DPAPI when the
session can reach it, otherwise (Linux, a locked keychain, a headless or
SSH session) an owner-only key file beside the store. It is handed to a
guest only through the enclave:
`--secret NAME` on `run` and `vm exec` places it at /run/i9/secrets/NAME
and as $NAME inside the guest. Read the file by its name: the directory
itself is not listable by the guest user. From that first delivery the
file stays for the VM's life: later commands in that VM can read it whether
or not they name `--secret`, and so can a fork that is given it (`--fork
allow`, or `vm fork --secret NAME`); a default-deny fork has no file. The
environment variable follows the same grant: it is in the environment of the
command that names the secret (and of the entrypoint of a VM started with
`i9 run --secret NAME`) and of every later command in that VM, whether or
not it names `--secret`. A proxy-mode secret's stand-in is delivered the same
way, and its hosts go through the enclave from the moment the VM starts; a VM
that cannot route them is refused by name, never started without. A fork or a rewind carries
every process as it was, so one that had already read a secret still holds
it. The value never enters argv, a span or a trace archive. A snapshot of a guest that has read it holds it
in guest memory: `vm save` names those secrets ("live secrets in guest
memory"), and that snapshot goes only to people you would give them to.

Values come in on stdin or from a file, never as an argument (an argument
sits in the process table), and never come out: `ls` shows names and
policies; there is no `get`.

What i9 does not do, and why. Secret managers such as secretspec offer
these; i9 leaves them out on purpose, each to keep an invariant:
- No `get` and no `export`: a value never comes back out of the store, so
  it is never somewhere a user, an agent or a log can copy it.
- A proxy-mode secret never reaches the guest: the guest holds a stand-in,
  swapped for the value on the way to its host, so a provider key stays out
  of the guest, its traces and its snapshots. One exception: a provider's own
  error can echo a redacted form of the real key (OpenAI's first 8 and last 4
  characters, for example), and that fragment reaches the guest; it is a
  fingerprint of the key, not the key.
- A `composed` value or a `default` is placed in file and env mode only; a
  value is never composed on the host, where it would be a second secret to
  scrub and expire.
- No `cache` of a backend's values outside the store: a reference is read
  again at each admission and by `i9 secret refresh`, never kept as a second
  plaintext copy.
- No retry with backoff: a refused read names its reason, and a value set
  later reaches a running VM when it is stored, never on a timer.
- A grant is an authorization boundary, not a scope label: each VM is given
  only the secrets named for it, under each record's fork policy, expiry and
  revocation.

```
i9 secret
```

**Examples:**

- Store an API key from a file: `i9 secret set OPENAI_API_KEY < ~/.openai`
- Store a value typed or piped on stdin: `i9 secret set DB_PASSWORD`
- List names and policies: `i9 secret ls`

**Exit codes:**

- `2`: Missing subcommand, missing name, or a value passed on the command line
- `6`: get or export: a stored value never comes back out of the store

#### `i9 secret set`

Store a secret under a name; the value comes from stdin or --from-file

Reads the value from stdin (or `--from-file PATH`), encrypts it into the
store under NAME, and prints nothing but a confirmation. A value on the
command line is refused: it would sit in the process table for the life
of the call.

Refuses a value under four bytes or containing `*`, because the trace
scrubber cannot arm such a value, and a stored secret is always one the
scrubber can remove from a span. A name that is already set is replaced in
place when the policy (modes, hosts, fork, kind) is the one it has: the new
value is a rotation, not a new grant, so a running VM that was given NAME
keeps its grant (a proxy-mode NAME keeps its stand-in token and substitutes
the new value from the next request; a file or env NAME is delivered the new
value at the next command that names it, and a process that already read
the old one keeps it), and `--expires` moves to the new time. A name already
set under another policy is refused: `i9 secret rm NAME` first, which is a
new grant. After a remove or a remove and set, a proxy-mode NAME's old
stand-in token is refused on that VM's next request. `--expires` works the
same way once its time passes (on this host's clock): a proxy-mode NAME is
refused on a running VM's next request, and a file or env NAME is refused
at the next command that names it, while a process that already read the
value keeps it and `secret ls` marks the record `expired`. A running VM
restored from a snapshot that held NAME, on this host before NAME was set
here (the restore named it among the secrets this machine does not hold),
receives NAME as soon as it is set, as the restore would have given it:
only with `--fork allow`, and only on a VM whose restore named it. Names beginning with `i9.` are i9's own
records (the grant, the control token) and cannot be set here.
A provider's key (OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY,
DASHSCOPE_API_KEY and the other provider keys), or any secret given `--proxy-host`, is
stored in proxy mode: the guest holds a stand-in token under the name, and
i9 puts the real value into the request as it leaves for one of the
record's hosts. The value never enters the guest. Clients trust i9's
proxy certificate through the system CA bundle and SSL_CERT_FILE,
REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE and NODE_EXTRA_CA_CERTS; a client that
reads only an NSS database (Firefox profiles, ~/.pki/nssdb), a Java
cacerts keystore, or a pinned certificate rejects it and the call fails,
with nothing sent. A WebSocket (HTTP Upgrade) to a proxy host is refused
(501), since its frames would bypass the response scrub. The proxy serves
HTTP/1.1 and HTTP/2 clients (it speaks HTTP/1.1 to the upstream) and puts
the value into request header values only, including an `Authorization:
Basic` credential built from the stand-in token: a stand-in token in a
request body, a trailer or the URL is refused (403) and never sent, so an
API that wants its key in a body needs `--mode env`. A response that
reflects the value (or its base64, hex or URL-encoded form) reaches the guest
with each occurrence replaced by eight asterisks whatever the value's
length, so the masked response shows that the value was reflected and where,
never how long it is; a response the scrub is armed for is sent chunked, since the mask
changes its length.

`--github-app APP_ID:INSTALLATION_ID` stores a GitHub App's private key
(the .pem GitHub downloads, from stdin or `--from-file`) instead of a
credential. The secret is proxy mode only: the guest holds a stand-in
token, and on a request that carries it the proxy mints an installation
token from the key, keeps it, and mints a new one before it expires, so
the request always carries a live token and no rotation job is needed.
The key never leaves the host. `--github-repo NAME` and
`--github-permission NAME=LEVEL` narrow every minted token to those
repositories and permissions. A fork child (with `--fork allow`) shares
its parent's token; `--secret-budget` and `vm revoke-secret` act on one
VM's stand-in as for any proxy secret. When a token cannot be minted, the
request is not sent and the guest gets a 502 naming the secret and the
reason (headers `X-I9-Secret` and `X-I9-Refused: mint-failed`), and the
`i9.secrets.mint` span records it. `i9.secrets.mint` records each mint with the
App, installation, scope and expiry, never a token. The hosts default to
github.com and api.github.com. A guest's git and gh read the stand-in
from /run/i9/secrets/NAME on each use (a token read before a fork or move
is dead). git sends it as the password of an `x-access-token` user.

```
i9 secret set <name> [--mode <file|env|both|proxy>] [--proxy-host <string>] [--fetch-host <string>] [--expires <string>] [--fork <allow|deny>] [--from-file <string>] [--profile <string>] [--ref <string>] [--github-app <string>] [--github-repo <string>] [--github-permission <string>] [--github-api-url <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--mode` | enum: file, env, both, proxy |  | How a guest receives it: file (/run/i9/secrets/NAME), env ($NAME), both, or proxy (a stand-in token; i9 substitutes the value in requests to its hosts). Default: proxy for a provider key or with --proxy-host, else both |
| `--proxy-host` | string |  | A host the value is sent to in proxy mode: host, host:port or *.domain; repeatable. A provider key defaults to its provider's hosts |
| `--fetch-host` | string |  | The HTTP host this credential authenticates: when i9 fetches a URL whose host matches, the value is sent as Authorization: Bearer. Mutually exclusive with --proxy-host |
| `--expires` | string |  | Stop delivering the secret after this: a duration (30m, 8h, 7d) or an RFC 3339 time (2026-12-01T00:00:00Z). Past it a proxy secret is refused on the VM's next request and a file or env secret is refused at delivery; `secret ls` marks it expired. Default: never |
| `--fork` | enum: allow, deny | deny | Whether a fork or a VM restored from a snapshot inherits it without --secret NAME: allow or deny |
| `--from-file` | string |  | Read the value from this file, every byte of it, instead of stdin (stdin drops one trailing line ending; a file keeps them) |
| `--profile` | string |  | The secretspec profile to store it under (lowercase letters, digits, - and _). One name holds a value per profile, so a dev and a prod OPENAI_API_KEY live side by side. Default: the `secrets.profile` config key, else default |
| `--ref` | string |  | Store where the value lives instead of the value: op://VAULT/ITEM/FIELD (1Password) or env://NAME (this host's environment, read-only). i9 reads it on the host when a VM is granted the secret and keeps every policy above; nothing is read from stdin, and `i9 secret refresh NAME` reads it again |
| `--github-app` | string |  | The value is this GitHub App's private key (APP_ID:INSTALLATION_ID); the proxy mints the App's installation token for each request, before the last one expires. Proxy mode only |
| `--github-repo` | string |  | With --github-app: narrow every minted token to this repository (its name, not owner/name); repeatable. Default: every repository the installation covers |
| `--github-permission` | string |  | With --github-app: narrow every minted token to this permission, NAME=read|write|admin (contents=write); repeatable. Default: every permission the App holds |
| `--github-api-url` | string |  | With --github-app: the App's API, https://HOST/api/v3 for GitHub Enterprise Server. Default: https://api.github.com |

**Examples:**

- Store an API key from a file the shell never echoes: `i9 secret set OPENAI_API_KEY < ~/.openai-key`
- Store a value piped in, available to guests as an env var only: `printf '%s' "$TOKEN" | i9 secret set GH_TOKEN --mode env`
- Store a key that stops working after eight hours: `i9 secret set GH_TOKEN --mode env --expires 8h < ~/.gh-token`
- Proxy a key for another API: the guest holds a stand-in token: `i9 secret set ACME_TOKEN --proxy-host api.acme.dev < ~/.acme`
- A GitHub App's installation token, minted at the proxy and narrowed to one repository: `i9 secret set GH_TOKEN --github-app 123456:7890123 --github-repo myrepo --github-permission contents=write --github-permission pull_requests=write --fork allow --from-file app.private-key.pem`

**Exit codes:**

- `2`: Missing name, the value was passed on the command line, or a flag value is refused: --mode is not file, env, both or proxy, --proxy-host is given without proxy mode, --expires is not a duration or time or is already past, a --github-* flag is malformed or given without --github-app, or a --github-app value is not an RSA private key
- `4`: The value is under four bytes or contains '*', a proxy-mode value holds a control byte, the name is already set under another policy (modes, hosts, fork or kind: `i9 secret rm NAME` first; a same-policy set is a rotation and exits 0), or the name is not one file name the guest can deliver (empty, over 255 bytes, '.', '..', containing '/', or .slot)
- `6`: No custodian on this host can unwrap the store; the message names the ones tried
- `1`: The secret store could not be opened

#### `i9 secret ls`

List stored secrets by name and policy; never a value

Prints one row per secret: PROFILE (the secretspec profile it is stored
under), NAME, KIND (`value`, or `github-app` for a
GitHub App key whose token is minted at the proxy), MODES, FORK, EXPIRES (the time it stops
being delivered, marked `expired` once past; empty for one that never
expires), and SYSTEM (`yes` for one of i9's own records). Needs no
custodian, so it works on a host that cannot unwrap the store (after a
move, or with a locked keychain) and tells you what you would have to
re-enter. Every profile is listed unless `--profile` names one. `--json`
prints the same rows as an array, each also carrying `created_ns`,
`expires_ns` (0 for none), `expired` and `kind`.

```
i9 secret ls [--profile <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--profile` | string |  | List only this secretspec profile's secrets; without it, every profile is listed |

**Examples:**

- List stored secrets by name and policy, never by value: `i9 secret ls`
- The same list as JSON rows for a script: `i9 secret ls --json`

**Exit codes:**

- `1`: The secret store could not be opened

#### `i9 secret rm`

Remove a secret by name

Appends a tombstone for NAME so `ls` and `--secret` no longer see it.
A running VM that already received it keeps its file at
/run/i9/secrets/NAME until that VM stops, and a process that read it
keeps it in its environment: removing a name does not reach into a
running guest. A proxy-mode secret is the exception, because the guest
only ever held a stand-in token: on that VM's next request the removed
record's token is refused (403), and a later `--secret NAME` is refused as
not set.
The store is an append-only i9io archive, so the encrypted bytes remain
in it until the store is compacted; they are unreadable without the data
key. i9's own records (`i9.` names) are changed through their verb, for
the grant `i9 grant`, not here.

```
i9 secret rm <name> [--profile <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--profile` | string |  | The secretspec profile to remove it from; the others keep theirs. Default: the `secrets.profile` config key, else default |

**Examples:**

- Remove a stored secret by name: `i9 secret rm OPENAI_API_KEY`

**Exit codes:**

- `3`: No secret of that name is set
- `6`: The name is one of i9's own records; the message names the verb that changes it
- `1`: The secret store could not be opened

#### `i9 secret refresh`

Read a reference secret's backend again and deliver the new value to running VMs

For a secret set with `--ref` (op:// or env://): reads its backend now,
so a backend that cannot serve it is named here, then rotates the record
in place. The record keeps its identity and policy, and every running VM
that holds it reads the backend again: a proxy-mode secret substitutes
the new value from the next request, and a file or env secret is
delivered it at the next command that names it. A process that already
read the old value keeps it. A backend does not tell i9 when a value
changes and i9 does not poll it, so run this after rotating the item.
A stored value (set from stdin or a file) has no backend; set it again
to replace it.

```
i9 secret refresh <name>
```

**Examples:**

- Pick up a rotated 1Password item in every running VM: `i9 secret refresh OPENAI_API_KEY`

**Exit codes:**

- `3`: No secret of that name is set, or its backend has no such item, field or variable
- `6`: The secret is a stored value, not a reference, or 1Password refused i9's sign-in
- `8`: The backend's tool (op) is missing or could not run
- `1`: The secret store could not be opened

#### `i9 secret check`

Judge a secretspec.toml against the secret store before any VM starts

Reads secretspec.toml (in the current directory, or at the path given:
the file or its directory), follows its `extends`, resolves the profile
(`--profile`, default `default`) and reports, per declared secret, what
a run would find in the store, what it would store first (a reference
to 1Password or the environment, or the file's own `default`), and
whether the secret is granted. Required secrets must resolve, an
optional one is granted only when it does, and an `at_least_one` or
`exactly_one` group is judged on what resolves. Nothing is written and
no value is printed. Exits non-zero, naming each problem and its fix,
when a run would be refused. A field i9 does not read (such as
`cache`), a backend it has no reader for, or a missing profile is
refused by name.

```
i9 secret check [path] [--profile <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--profile` | string | default | The secretspec profile to resolve |

**Examples:**

- Check this repository's secretspec.toml before a run: `i9 secret check`
- Check another profile, as JSON: `i9 secret check --profile production --json`

**Exit codes:**

- `6`: A run would be refused: a required secret is missing, a group is not met, a stored record conflicts with the declaration, or the file declares something i9 does not read
- `1`: The secret store could not be opened

#### `i9 secret login`

Store a 1Password service account token so op:// secrets read on headless hosts

`i9 secret login op` reads a 1Password service account token from stdin
(or `--from-file PATH`), checks it with `op whoami`, and stores it in the
secrets store as i9's own record, `i9.op.service_account`. From then on
every op:// reference on this host is read with it, which is what a host
with no 1Password app (a server, CI) needs. Without it, op:// references
are read with your 1Password session: the 1Password app with CLI
integration asks for Touch ID, Windows Hello or your password.
The token goes to `op` only in its environment, never on a command line,
and is never delivered to a guest. A token on the command line is refused.

```
i9 secret login <backend> [--from-file <string>]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--from-file` | string |  | Read the token from this file instead of stdin |

**Examples:**

- Sign i9 in to 1Password with a service account token: `i9 secret login op < token`

**Exit codes:**

- `6`: 1Password refused the token
- `8`: The 1Password CLI (op) is missing or could not run
- `1`: The secret store could not be opened

#### `i9 secret logout`

Remove the stored 1Password service account token

`i9 secret logout op` removes `i9.op.service_account`. op:// references
are then read with your 1Password session (the 1Password app with CLI
integration). Revoke the token in 1Password too: removing it here does
not revoke it there.

```
i9 secret logout <backend>
```

**Examples:**

- Go back to reading op:// secrets with your 1Password session: `i9 secret logout op`

**Exit codes:**

- `3`: No service account token is stored
- `1`: The secret store could not be opened

### `i9 store`

List and prune the image page cache under the i9 home

Every `i9 run` of an image it streams keeps the image pages its VM read
in a local cache, `store/` under the i9 home (`win-<n>-<id>.i9io` files),
so a later run of the same image, or of any image that shares pages with
it, reads them from disk instead of fetching them again. Each page is
checked against the image's recorded hash before it is used. The cache
outlives the VM: `i9 vm stop --discard` leaves it. By default it is capped
at the smaller of 4 GiB and a tenth of its own size plus the free space on
its disk, least recently used file first.

`ls` lists each cache file with the images it holds pages of, its size
and when a run last used it; `prune` reclaims the disk, by size, by age,
or all of it, and reports the bytes reclaimed. `prune` refuses while a
running VM holds the cache and names that VM; stop it first.

```
i9 store
```

**Examples:**

- List the image page cache: `i9 store ls`
- Empty the image page cache: `i9 store prune --all`

**Exit codes:**

- `2`: Missing or unknown subcommand

#### `i9 store ls`

List the image page cache: one row per file, with its images, size and last use

Lists every file of the image page cache (`store/` under the i9 home),
least recently used first: when a run last used it, its size, how many
page windows it holds, its file name and the images it holds pages of
(their URLs, without any query string). A file that names no image holds
pages of images another file names. The last line is the total and the
cap. An empty or missing cache lists no files and a total of 0 B.

```
i9 store ls
```

**Examples:**

- List the image page cache: `i9 store ls`
- Machine-readable listing: `i9 store ls --json`

**Exit codes:**

- `0`: Listed (an empty or missing cache lists no files)
- `2`: Usage error (unexpected argument)

#### `i9 store prune`

Reclaim image page cache disk: by size, by age, or all of it

Removes whole cache files, least recently used first, and reports the
bytes reclaimed. With no flag it enforces the default cap (the smaller of
4 GiB and a tenth of the cache's size plus the free space on its disk),
which every run also enforces on its own. A later run of an image whose
pages were removed fetches them again.

A running VM keeps the cache open for its whole life, so a prune while one
runs would reclaim nothing it reads: the prune refuses (exit 6), removes
nothing, and names the running VM's pid. Stop it (`i9 vm stop`), then
prune again.

```
i9 store prune [--max-bytes <integer>] [--older-than <string>] [--all]
```

**Flags:**

| Flag | Type | Default | Description |
|------|------|---------|-------------|
| `--max-bytes` | integer |  | Remove least recently used files until the cache is at most this many bytes |
| `--older-than` | string |  | Remove files no run has used for this long: a number with an s, m, h or d suffix (e.g. 7d) |
| `--all` | boolean | False | Remove every file (the next run of each image fetches its pages again) |

**Examples:**

- Keep at most 1 GiB: `i9 store prune --max-bytes 1073741824`
- Drop pages no run has used for a week: `i9 store prune --older-than 7d`
- Empty the cache: `i9 store prune --all`

**Exit codes:**

- `0`: Pruned (bytes reclaimed and what was kept printed)
- `2`: Usage error (bad --max-bytes or --older-than)
- `6`: A running VM holds the cache; the message names its pid. Stop it, then prune again

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ANTHROPIC_API_KEY` |  | Anthropic (Claude) API key |
| `OPENAI_API_KEY` |  | OpenAI API key |
| `OPENROUTER_API_KEY` |  | OpenRouter API key |
| `DASHSCOPE_API_KEY` |  | DashScope API key |
| `RUST_BACKTRACE` | 1 | Rust backtrace verbosity for the VM host process |
| `NO_COLOR` | False | Disable all ANSI color output (standard convention) |
| `I9_HOME` |  | Instance root — per-install state (config.json, run/, sessions/). Below `--home` in precedence, above the ~/.i9 default. Two installs sharing one data root is the case it exists for: without it every invocation would have to carry the flag. |
| `I9_DATA` |  | Shared data root — the trace store and anything safe to share between installs. Below `--data`, above the config file's `data` key, above I9_HOME. Resolution is --data > I9_DATA > config > instance root; a test or a second install isolating its store sets this. |
| `I9_AGENT_TOKEN` |  | Bearer token required on the session-server agent control API (/api/agent/*); unset disables the agent API |
| `I9_FORK_DEPTH` | 0 | Fork depth of THIS process, injected by the parent that forked it; the fork depth cap is evaluated against it |
| `I9_TRACE_DIR` |  | Override trace output directory |
| `TRACEPARENT` |  | W3C Trace Context carrier (00-`<trace id>`-`<parent span id>`-`<flags>`): the run a process joins and the span that spawned it |
| `I9_TRACE_SOCK` |  | The span intake a process writes its own spans to: a unix socket taking newline-delimited JSON span records (i9 docs spans) |
| `OTEL_EXPORTER_OTLP_ENDPOINT` |  | OTLP/HTTP endpoint `i9 trace tail --otlp-push` sends to when neither --otlp-endpoint nor the config key otel.endpoint names one (the standard OpenTelemetry variable; /v1/traces is appended) |
| `OTEL_EXPORTER_OTLP_HEADERS` |  | Request headers for that endpoint, as name=value,name2=value2 (the standard OpenTelemetry variable), when the config key otel.headers names none |
| `DO_NOT_TRACK` |  | Cross-tool convention: set to any non-empty value to opt out of telemetry |
| `I9_HINTS` |  | Set to 0 to turn every hint off for this invocation, a refusal's fix included |
| `I9_PROFILE` |  | Name the model-and-harness profile a hint renders for, ahead of the MCP client and the harness i9 detects |
| `I9_MCP_CLIENT` |  | The MCP client a CLI spawned by the MCP server renders hints for, and that `i9 feedback` names as the report's agent; set by the server, not by hand |
| `CLAUDECODE` |  | Set to 1 by Claude Code for the commands it runs; hints render the claude-code profile |
| `AI_AGENT` |  | Names the agent running the command; `claude-code_<version>_agent`, which Claude Code sets, renders hints for the claude-code profile |
| `PI_CODING_AGENT` |  | Set to true by pi for the commands it runs; hints render the pi profile |

