> ## Documentation Index > Fetch the complete documentation index at: https://docs.xorcise.ai/llms.txt > Use this file to discover all available pages before exploring further. # CLI reference > Every xorcise command, option, exit code, and environment variable, with the web UI equivalent for each task. The `xorcise` command drives the same local instance as the web UI. Most commands are thin REST clients and need an instance running (`xorcise up`); the last column of the summary says which. ## Command summary | Command | Purpose | Needs a running instance | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------ | | [`xorcise up`](#xorcise-up) | Start XORCISE in the background and print the interface URL | No — it starts one | | [`xorcise ui`](#xorcise-ui) | Print the interface URL | No | | [`xorcise status`](#xorcise-status) | Probe the REST plane, the OTLP plane, and Docker from this machine | No | | [`xorcise doctor`](#xorcise-doctor) | Diagnose setup problems and print the fix for each | No | | [`xorcise down`](#xorcise-down) | Stop XORCISE and clean up | No | | [`xorcise system`](#xorcise-system) | Show what the running instance sees about itself | Yes | | [`xorcise leaderboard`](#xorcise-leaderboard) | Rank agents by their recorded results | Yes | | [`xorcise agent list`](#xorcise-agent-list) | List registered agents | Yes | | [`xorcise agent register`](#xorcise-agent-register) | Register an agent by name | Yes | | [`xorcise agent update`](#xorcise-agent-update) | Update an agent's declaration and bump its version | Yes | | [`xorcise agent rename`](#xorcise-agent-rename) | Rename an agent, keeping its id, versions, and runs | Yes | | [`xorcise agent history`](#xorcise-agent-history) | List an agent's results over time | Yes | | [`xorcise agent rm`](#xorcise-agent-rm) | Remove an agent, its versions, and its runs | Yes | | [`xorcise mission list`](#xorcise-mission-list) | Browse your own missions and the XORCISE library | Yes | | [`xorcise mission show`](#xorcise-mission-show) | Show one mission's details | Yes | | [`xorcise mission pull`](#xorcise-mission-pull) | Install a library mission so it can run | Yes | | [`xorcise mission ingest`](#xorcise-mission-ingest) | Add your own mission from a local bundle — **coming soon**, prints a notice and installs nothing | No | | [`xorcise mission delete`](#xorcise-mission-delete) | Uninstall an installed mission | Yes | | [`xorcise run list`](#xorcise-run-list) | List runs, newest first | Yes | | [`xorcise run create`](#xorcise-run-create) | Create a run — one agent against one installed mission | Yes | | [`xorcise run status`](#xorcise-run-status) | Show a run's scores, per-check breakdown, and conditions | Yes | | [`xorcise run terminate`](#xorcise-run-terminate) | Stop a run early and grade what happened so far | Yes | | [`xorcise run regrade`](#xorcise-run-regrade) | Re-grade a finished run's sealed evidence | Yes | | [`xorcise run delete`](#xorcise-run-delete) | Delete a run's result and record | Yes | | [`xorcise run report`](#xorcise-run-report) | Write a run's full report as Markdown or HTML | Yes | | [`xorcise run traces`](#xorcise-run-traces) | Fetch the collected OpenTelemetry records for a run | Yes | | [`xorcise run prompt`](#xorcise-run-prompt) | Print a run's connect prompt verbatim | Yes | | [`xorcise run launch-profile`](#xorcise-run-launch-profile) | Print a run's telemetry environment as dotenv lines | Yes | | [`xorcise run launch-cmd`](#xorcise-run-launch-cmd) | Print the copy-paste startup block for a host-run harness | Yes | | [`xorcise run events export`](#xorcise-run-events-export) | Write a run's normalized event stream to JSONL | Mostly no | | [`xorcise config show`](#xorcise-config-show) | Show judge model, terrain model, library, network, and defaults | Yes | | [`xorcise config set-model`](#xorcise-config-set-model) | Set the judge model | Yes | | [`xorcise config test`](#xorcise-config-test) | Live-test the saved judge model by calling it | Yes | | [`xorcise config set-terrain-model`](#xorcise-config-set-terrain-model) | Set the terrain-attribution model override | Yes | | [`xorcise config test-terrain`](#xorcise-config-test-terrain) | Live-test the effective terrain model | Yes | | [`xorcise config set-network`](#xorcise-config-set-network) | Set multi-machine addresses — **experimental** | Yes | | [`xorcise catalog status`](#xorcise-catalog-status) | Check the mission library connection | Yes | | [`xorcise catalog connect`](#xorcise-catalog-connect) | Enable the online mission library | Yes | | [`xorcise catalog disconnect`](#xorcise-catalog-disconnect) | Disable the library and show local missions only | Yes | | [`xorcise serve`](#xorcise-serve) | Run XORCISE in the foreground | It is the instance | | [`xorcise db upgrade`](#xorcise-db-upgrade) | Apply pending database migrations | No | | [`xorcise role show`](#xorcise-role-show) | Show the service role this shell would boot — **experimental** | No | | [`xorcise role list`](#xorcise-role-list) | List the service roles `serve` can boot — **experimental** | No | `xorcise agent delete`, `xorcise mission rm`, and `xorcise run rm` are accepted aliases of `agent rm`, `mission delete`, and `run delete`. ## Conventions ### Global options | Option | Type | Default | Meaning | | ---------------------- | ---- | ------- | -------------------------------------------------- | | `--version` | flag | — | Print `xorcise ` and exit. | | `--help`, `-h` | flag | — | Print help. `-h` works on every command and group. | | `--install-completion` | flag | — | Install shell completion. | | `--show-completion` | flag | — | Print the completion script. | Running `xorcise` with no arguments, or a group with no subcommand such as `xorcise agent`, prints help and exits `0`. ### Names, ids, and prefixes Run ids accept a unique prefix, so the 8-character id from `xorcise run list` works everywhere a run id is asked for. Agent arguments take the agent name. Mission arguments take the mission id or its display name — quote a name that contains spaces. ### Output streams Data and success messages go to stdout. Every error, the `xorcise ui` warning, and the `xorcise mission pull` progress bar go to stderr, so a script can separate them. A closed downstream pipe, as in `xorcise run list | head`, is not an error. ### Confirmation prompts Destructive commands prompt only on an interactive terminal. Both `--yes` and a non-interactive stdin skip the prompt, so nothing hangs in CI. The single exception is `xorcise down --purge`, which refuses with exit `2` rather than proceeding unconfirmed. ## Exit codes | Code | Meaning | | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Success, including idempotent no-ops: `up` when already running, `mission pull` when already installed, `catalog connect` when already connected. | | `1` | Runtime failure: the instance is unreachable, the brain returned an error, a `doctor` blocker failed, a destructive confirmation was declined, an output path is unwritable, the database migration history does not match. | | `2` | Usage error: unknown command or option, missing required option, mutually exclusive flags, a setter called with no fields to set, `--purge` without `--yes` on a non-interactive stdin. | | `3` | The operation is still in progress. The work continues; the CLI stopped waiting. | | `130` | Interrupted with Ctrl-C. | Exit `3` is not a failure. `run status`, `run report`, `run terminate --wait`, `run regrade --wait`, and `mission pull` all return it while the work continues on the server, so a CI gate that treats every non-zero code as failure will report a healthy in-progress run as broken. Branch on `3` explicitly. ```bash theme={"theme":"css-variables"} until xorcise run status 4c62254b > result.txt; do code=$? [ "$code" -eq 3 ] || exit "$code" sleep 10 done ``` Any unexpected exception is printed as a single line and exits `1`; set `XORCISE_DEBUG=1` for the traceback. ## JSON output Twenty-one commands accept `--json`: `status`, `doctor`, `leaderboard`, `agent list`, `agent register`, `agent history`, `mission list`, `mission show`, `run list`, `run create`, `run status`, `run traces`, `system`, `config show`, `config test`, `config test-terrain`, `catalog status`, `catalog connect`, `catalog disconnect`, `role show`, and `role list`. JSON is written straight to stdout, never through the table renderer, so it is never wrapped, styled, or truncated. `run status --json` is always parseable, including before the result exists: the envelope carries `status: "active"` or `status: "grading"` while the command exits `3`. Three commands emit machine-readable output that is not JSON. `run prompt` emits the prompt body verbatim, `run launch-profile` emits dotenv lines, and `run events export` writes JSONL. ## CLI ↔ Web UI map | Task | CLI | Web UI | Notes | | ----------------------------- | ----------------------------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Start or stop XORCISE | `xorcise up`, `xorcise down` | — | CLI-only | | Check host prerequisites | `xorcise doctor` | — | CLI-only | | Check service health | `xorcise status`, `xorcise system` | **Settings** → **Environment**, **Modules** | `status` probes from your machine, `system` asks the instance | | Register an agent | `xorcise agent register` | **Agents** → **Register agent** | | | Rename or update an agent | `xorcise agent update`, `xorcise agent rename` | **Agents** → agent detail | | | Remove an agent | `xorcise agent rm` | **Agents** → agent detail | Also deletes that agent's runs and results | | Read an agent's history | `xorcise agent history` | **Agents** → agent detail | | | Rank agents | `xorcise leaderboard` | **Dashboard** | | | Browse missions | `xorcise mission list`, `xorcise mission show` | **Missions** | | | Install a library mission | `xorcise mission pull` | **Missions** → **Pull** | | | Add your own mission | `xorcise mission ingest` | **Missions** → **Ingest a bundle** | Coming soon on both surfaces — the command prints a notice and the button opens a product preview; neither installs a bundle in this release | | Uninstall a mission | `xorcise mission delete` | **Missions** → mission detail | | | Create a run | `xorcise run create` | **Runs** → **New run** | The web UI then opens the live run page | | Watch a run | `xorcise run traces` | **Runs** → live run page | The timeline, terrain map, and trace feed have no CLI equivalent | | Read the terrain map | — | **Runs** → live run page | UI-only | | Get the connect prompt | `xorcise run prompt` | **Runs** → live run page | | | Get the telemetry environment | `xorcise run launch-profile`, `xorcise run launch-cmd` | — | CLI-only | | Stop a run early | `xorcise run terminate` | **Runs** → run card | | | Read the score | `xorcise run status -v` | **Results** → open the run | | | Download a report | `xorcise run report` | **Results** → **Download** | | | Re-grade a sealed run | `xorcise run regrade` | **Results** → **Re-evaluate** | | | Delete a run | `xorcise run delete` | **Runs** → run card | | | Export the event stream | `xorcise run events export` | — | CLI-only, for debugging | | Set the judge model | `xorcise config set-model`, `xorcise config test` | **Settings** → **Judge model** | | | Set the terrain model | `xorcise config set-terrain-model`, `xorcise config test-terrain` | **Settings** → **Terrain model** | | | Connect the mission library | `xorcise catalog connect`, `xorcise catalog disconnect` | **Settings** → **XORCISE Remote** | | | Set multi-machine addresses | `xorcise config set-network` | — | CLI-only and experimental; **Settings** shows them read-only | | Apply database migrations | `xorcise db upgrade` | — | CLI-only. **Settings** → **Environment** reports when one is due | ## Start and stop ### xorcise up ```bash theme={"theme":"css-variables"} xorcise up [--stub] [--port PORT] [--otlp-port PORT] ``` Starts XORCISE in the background and prints the interface URL. On a first run it creates `~/.xorcise`, scaffolds `config.toml`, migrates a fresh database, provisions the local Headscale control plane, then polls the REST plane until it answers. Already running is success: it prints `already running — UI at ` and exits `0`. If the database already holds data and is behind the current build it refuses to boot and asks you to run `xorcise db upgrade`. On a start-up timeout it exits `1` and points at `~/.xorcise/serve.log`, which is where boot failures are written. | Option | Type | Default | Meaning | | -------------- | --------------- | ------- | --------------------------------------------------------------------------------------------------- | | `--stub` | flag | off | Use stub adapters so XORCISE runs without Docker. Skips Headscale provisioning. | | `--port`, `-p` | integer 1–65535 | `3001` | REST and web UI port. Auto-increments to the next free port when busy, printing which port it took. | | `--otlp-port` | integer 1–65535 | `4318` | OTLP receiver port. Same auto-increment behaviour. | ```bash theme={"theme":"css-variables"} xorcise up --port 3010 ``` ### xorcise ui ```bash theme={"theme":"css-variables"} xorcise ui ``` Prints the interface URL on stdout, reading the port the running instance actually took rather than assuming the default. When nothing answers it still prints the URL and writes a warning to stderr. No options. ```bash theme={"theme":"css-variables"} open "$(xorcise ui)" ``` ### xorcise status ```bash theme={"theme":"css-variables"} xorcise status [--json] ``` Probes three things from this machine — the REST plane, the OTLP plane, and the local Docker daemon — and derives an Interface row from the REST result. Exits `1` if any of them is down. | Option | Type | Default | Meaning | | -------- | ---- | ------- | ------------------------------------------- | | `--json` | flag | off | Emit the checks and resolved ports as JSON. | ```bash theme={"theme":"css-variables"} xorcise status ``` ```text title="Output" theme={"theme":"css-variables"} XORCISE status Service State Address ────────────────────────────────────────────────── Interface Healthy http://127.0.0.1:3001/ui REST API Healthy http://127.0.0.1:3001 OTLP receiver Healthy http://127.0.0.1:4318 Docker Healthy local daemon All services are healthy. ``` ### xorcise doctor ```bash theme={"theme":"css-variables"} xorcise doctor [--json] ``` Checks the host and reports the fix for each failure. The Environment section covers Python, the Docker CLI, the Docker daemon, the Docker Compose v2 plugin, free disk space, `openssl`, `/dev/net/tun`, and the data directory. The Services section covers the plane ports and, when an instance is expected, the Headscale control plane. Each check is a blocker or a warning; warnings never fail the verdict, so the command exits `1` only when a blocker fails. | Option | Type | Default | Meaning | | -------- | ---- | ------- | ------------------------------------------------------------------------------- | | `--json` | flag | off | Emit the checks as JSON. Each carries `level: "blocker"` or `level: "warning"`. | ```bash theme={"theme":"css-variables"} xorcise doctor ``` ### xorcise down ```bash theme={"theme":"css-variables"} xorcise down [--keep-data] [--purge] [--yes] ``` Stops XORCISE and reaps any orphaned per-run mission containers. With no flags it clears transient runtime state and keeps your configuration and data. | Option | Type | Default | Meaning | | ------------- | ---- | ------- | --------------------------------------------------------------------------- | | `--keep-data` | flag | off | Stop only. Preserves all `~/.xorcise` state and skips Headscale teardown. | | `--purge` | flag | off | Remove all `~/.xorcise` state, including configuration, database, and runs. | | `--yes`, `-y` | flag | off | Skip the `--purge` confirmation. | `--keep-data` with `--purge` is a usage error, exit `2`. So is `--purge` on a non-interactive stdin without `--yes`. `xorcise down --purge` deletes your judge-model configuration, every registered agent, every installed mission, and every recorded run and result. There is no undo. Run it before `pip uninstall xorcise`, though, or the Headscale container and its volume are left behind. ```bash theme={"theme":"css-variables"} xorcise down --purge --yes ``` ## Instance and results ### xorcise system ```bash theme={"theme":"css-variables"} xorcise system [--verbose] [--json] ``` Asks the running instance what it sees about itself: its planes and their addresses, Docker, Headscale, the mission library, and registered remotes. Contrast `xorcise status`, which probes from your machine. | Option | Type | Default | Meaning | | ----------------- | ---- | ------- | ---------------------------------------------------------------------------------- | | `--verbose`, `-v` | flag | off | Add deployment internals: role, topology, database schema and URL, data directory. | | `--json` | flag | off | Emit the raw system view. | ```bash theme={"theme":"css-variables"} xorcise system --verbose ``` ### xorcise leaderboard ```bash theme={"theme":"css-variables"} xorcise leaderboard [--json] ``` Ranks every agent by its recorded results: run count, scored count, average and best overall, completion rate, partial rate, and last run. Partial runs — those ended by a timeout, a budget, or an operator — are counted in the totals and the partial rate but excluded from the score averages. With no finished runs it prints `no finished runs yet — nothing to rank` and exits `0`. | Option | Type | Default | Meaning | | -------- | ---- | ------- | ------------------------------------------------------------ | | `--json` | flag | off | Emit the rows as JSON. `[]` when there are no finished runs. | ```bash theme={"theme":"css-variables"} xorcise leaderboard ``` ```text title="Output" theme={"theme":"css-variables"} Leaderboard Agent Runs Scored Avg Best Completed Partial Last run ───────────────────────────────────────────────────────────────────────── scout 13 5 0.65 1.00 38% 15% Yesterday 17:13 ``` ## agent ### xorcise agent list ```bash theme={"theme":"css-variables"} xorcise agent list [--verbose] [--json] ``` Lists registered agents with their harness, version, and disclosed model. | Option | Type | Default | Meaning | | ----------------- | ---- | ------- | ----------------------------------------------- | | `--verbose`, `-v` | flag | off | Add the internal agent id and endpoint columns. | | `--json` | flag | off | Emit the raw agent array. | ```bash theme={"theme":"css-variables"} xorcise agent list ``` ### xorcise agent register ```bash theme={"theme":"css-variables"} xorcise agent register --name NAME [--endpoint TEXT] [--otel TEXT] [--model TEXT] [--kind TEXT] [--launch-mode TEXT] [--json] ``` Registers an agent as a named record at version 1. Connection details are optional — XORCISE never launches your agent, so the record exists to identify and version it. A duplicate name is caught before the request and exits `1` suggesting `xorcise agent update`. | Option | Type | Default | Meaning | | --------------- | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `--name` | text | required | Unique agent name. Empty or whitespace is a usage error. | | `--endpoint` | text | none | Where the agent runs. Recorded on the record for your reference; XORCISE does not dial it. | | `--otel` | text | none | Where the agent ships traces. Recorded but never read — the endpoint an agent must use comes per-run from `xorcise run launch-cmd`. | | `--model` | text | none | The model the agent discloses. Passing it here keeps the agent at version 1. | | `--kind` | text | none | The agent's harness. `openhands`, `claude-code`, and `codex` are the built-ins; any other value falls back to the generic adapter. | | `--launch-mode` | `host` or `container` | none | Where the agent's command runs, which decides the addresses `run launch-cmd` bakes in. | | `--json` | flag | off | Emit the raw created agent. | `--kind` is not cosmetic: it selects the replay adapter that turns traces into events, the telemetry provider that decides which variables `run launch-cmd` emits and how a run is correlated, and the launch provider that builds the harness command. ```bash theme={"theme":"css-variables"} xorcise agent register --name scout --kind claude-code --model claude-sonnet-5 ``` ### xorcise agent update ```bash theme={"theme":"css-variables"} xorcise agent update --name NAME [--endpoint TEXT] [--otel TEXT] [--model TEXT] [--kind TEXT] [--launch-mode TEXT] [--rename-to TEXT] ``` Re-declares an agent at a new version, keeping the same agent id and all of its runs. Only the fields you pass change; the rest are carried over. Passing no field to change is a usage error, exit `2`. | Option | Type | Default | Meaning | | --------------- | --------------------- | --------- | ----------------------------------------- | | `--name` | text | required | The agent to update. | | `--endpoint` | text | unchanged | New connection endpoint. | | `--otel` | text | unchanged | New trace endpoint. | | `--model` | text | unchanged | New disclosed model. | | `--kind` | text | unchanged | New harness. | | `--launch-mode` | `host` or `container` | unchanged | Where the agent's command runs. | | `--rename-to` | text | unchanged | New name. Runs and history stay attached. | ```bash theme={"theme":"css-variables"} xorcise agent update --name scout --model claude-opus-5 ``` ### xorcise agent rename ```bash theme={"theme":"css-variables"} xorcise agent rename OLD NEW ``` Renames an agent, keeping its id, version history, and runs. Both positionals are required. Use this rather than registering a second agent, which would start a fresh history. No options. ```bash theme={"theme":"css-variables"} xorcise agent rename scout scout-v2 ``` ### xorcise agent history ```bash theme={"theme":"css-variables"} xorcise agent history NAME [--json] ``` Lists that agent's results oldest to newest, with the overall, deterministic, and judge scores, the agent and mission versions each was produced under, and the disclosed model. Partial results are marked. | Option | Type | Default | Meaning | | -------- | ---- | ------- | ------------------------------------------------------------- | | `--json` | flag | off | Emit the raw history rows, including the recorded conditions. | ```bash theme={"theme":"css-variables"} xorcise agent history scout ``` ### xorcise agent rm ```bash theme={"theme":"css-variables"} xorcise agent rm NAME [--yes] ``` Removes the agent, its version history, and its recorded runs and results. Prompts on an interactive terminal. | Option | Type | Default | Meaning | | ------------- | ---- | ------- | ---------------------- | | `--yes`, `-y` | flag | off | Skip the confirmation. | ```bash theme={"theme":"css-variables"} xorcise agent rm scout --yes ``` ## mission ### xorcise mission list ```bash theme={"theme":"css-variables"} xorcise mission list [--installed] [--available] [--source TEXT] [--difficulty TEXT] [--json] ``` Lists your own missions and, when the library is connected, the free XORCISE library. Installed missions sort first. A filter that matches nothing is an empty result, exit `0`. | Option | Type | Default | Meaning | | -------------- | ---- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--installed` | flag | off | Only installed missions. | | `--available` | flag | off | Only missions not yet installed. | | `--source` | text | none | `library` or `your-own`. An unknown value is a usage error. | | `--difficulty` | text | none | A proficiency, matched case-insensitively. The XORCISE ladder runs `Novice`, `Advance Beginner`, `Competent`, `Proficient`, `Expert`. A value the live library does not carry, and that is not in the built-in vocabulary, is a usage error. | | `--json` | flag | off | Emit the raw mission array. | `--installed` with `--available` is a usage error, exit `2`. The accepted set is the built-in vocabulary plus every proficiency the live library actually carries, so it grows with the library. The built-in vocabulary still holds two terms from the older scale, `intermediate` and `hard`, which are accepted but match nothing on a library that uses the ladder above — you get an empty result and exit `0`, not an error. ```bash theme={"theme":"css-variables"} xorcise mission list --available --difficulty novice ``` ### xorcise mission show ```bash theme={"theme":"css-variables"} xorcise mission show MISSION [--json] ``` Shows one mission — your installed copy if you have it, otherwise the library entry. Accepts an id or a display name. The human view covers the environment kind, difficulty, specialty, the objective given to the agent, the description written for you, skills and technologies, and counts of artifacts, rubric criteria, checks, intel items, attachments, and attack-path nodes. It ends with the next command to run. | Option | Type | Default | Meaning | | -------- | ---- | ------- | ------------------------------------- | | `--json` | flag | off | Emit the raw `mission.json` manifest. | ```bash theme={"theme":"css-variables"} xorcise mission show chrono-canary ``` ### xorcise mission pull ```bash theme={"theme":"css-variables"} xorcise mission pull MISSION ``` Installs a library mission so it can run, downloading its container image and bundle. On a terminal it shows a live progress bar on stderr; elsewhere it prints one line per phase: resolving, downloading the image, downloading the bundle, installing, done. Already installed is a no-op, exit `0`. Ctrl-C cancels the pull on the server and exits `130`. Past a 30-minute wait the CLI exits `3` and the job keeps going. No options. ```bash theme={"theme":"css-variables"} xorcise mission pull chrono-canary ``` The library's contents change, so run `xorcise mission list` first and pull an id you actually see rather than assuming a particular mission is available. ### xorcise mission ingest ```bash theme={"theme":"css-variables"} xorcise mission ingest [BUNDLE_DIR] ``` **Coming soon.** Adding your own mission from a local bundle is not available in this release. The command is a placeholder: every form of it prints the notice below, installs nothing, and exits `0`. To get missions today, browse the free XORCISE library with [`xorcise mission list`](#xorcise-mission-list) and install one with [`xorcise mission pull`](#xorcise-mission-pull) — no account, key, or sign-in. ```text title="Output" theme={"theme":"css-variables"} Ingesting your own mission bundle is coming soon. For now, browse the published missions with xorcise mission list and install one with xorcise mission pull . ``` The `BUNDLE_DIR` positional is optional and is not read, so `xorcise mission ingest`, `xorcise mission ingest ./sqli-login`, and a path that does not exist all print the same notice. There are no options and no running instance is required. When the feature ships, a bundle will be a local directory containing a `mission.json` manifest — a directory, not an archive — which ingest will validate before building the mission's image. Validation will belong to ingest and only to ingest; there is no separate validate command. The manifest format is documented now so you can prepare bundles in advance: see [Mission manifest](/reference/mission-manifest). ### xorcise mission delete ```bash theme={"theme":"css-variables"} xorcise mission delete MISSION [--yes] ``` Uninstalls an installed mission. Recorded runs and results are kept, and so is the built image in your local Docker store, so re-installing is cheap. Deleting a mission that is not installed exits `1`. | Option | Type | Default | Meaning | | ------------- | ---- | ------- | ---------------------- | | `--yes`, `-y` | flag | off | Skip the confirmation. | ```bash theme={"theme":"css-variables"} xorcise mission delete chrono-canary --yes ``` ## run ### xorcise run list ```bash theme={"theme":"css-variables"} xorcise run list [--verbose] [--json] ``` Lists runs newest first with a shortened run id, the humanised result, the agent, the mission, the score, and a relative start time. The short ids feed `run status`, `run report`, and `run traces`. | Option | Type | Default | Meaning | | ----------------- | ---- | ------- | ------------------------------------------------------------- | | `--verbose`, `-v` | flag | off | Show full 32-character run ids and the raw state and trigger. | | `--json` | flag | off | Emit the raw run array. | ```bash theme={"theme":"css-variables"} xorcise run list ``` ### xorcise run create ```bash theme={"theme":"css-variables"} xorcise run create --agent NAME --mission MISSION [--budget SECONDS] [--json] ``` Creates a run pairing one registered agent with one installed mission. Both inputs are resolved before the request, so a typo answers with the closest name and a mission you have not installed answers with the `xorcise mission pull` command rather than a 404. | Option | Type | Default | Meaning | | ----------- | ------- | -------------- | ------------------------------------------------------------------------------------------------------------------- | | `--agent` | text | required | Registered agent name. | | `--mission` | text | required | Installed mission id or name. | | `--budget` | integer | `3600` seconds | Wall-clock budget. At the deadline the run is sealed and graded on what happened, and the result is marked partial. | | `--json` | flag | off | Emit the raw created run. | ```bash theme={"theme":"css-variables"} xorcise run create --agent scout --mission chrono-canary ``` ```text title="Output" theme={"theme":"css-variables"} run 4c62254b7f0e4a1b9c3d5e6f70819a2b created (scout vs chrono-canary) next: xorcise run launch-cmd 4c62254b then: xorcise run status 4c62254b ``` ### xorcise run status ```bash theme={"theme":"css-variables"} xorcise run status RUN_ID [--verbose] [--json] ``` Shows the graded result: the overall score and its deterministic and judge halves, the per-check breakdown, artifacts, trace counts, and the disclosed conditions the run was graded under — the agent's model, the judge model, the budget, and the sandbox. A run graded on incomplete data is flagged partial. | Option | Type | Default | Meaning | | ----------------- | ---- | ------- | ----------------------------------------------------------------------------------- | | `--verbose`, `-v` | flag | off | Add the per-check deterministic list and the per-criterion judge rubric. | | `--json` | flag | off | Emit the full result envelope. Always parseable, including before grading finishes. | Exits `3` while the run is still active or still grading, so it polls cleanly. ```bash theme={"theme":"css-variables"} xorcise run status 4c62254b --verbose ``` ### xorcise run terminate ```bash theme={"theme":"css-variables"} xorcise run terminate RUN_ID [--wait | --no-wait] [--yes] ``` Stops an active run early. The run is sealed immediately and graded on what happened so far; the result is marked partial with an operator trigger. | Option | Type | Default | Meaning | | ---------------------- | --------- | -------- | ----------------------------------------------------------------------------------------- | | `--wait` / `--no-wait` | flag pair | `--wait` | Poll until grading finishes and print the result, or return as soon as the run is sealed. | | `--yes`, `-y` | flag | off | Skip the confirmation. | With `--wait`, the CLI polls for up to four minutes and then exits `3` if grading has not landed. Grading continues either way. ```bash theme={"theme":"css-variables"} xorcise run terminate 4c62254b --no-wait --yes ``` ### xorcise run regrade ```bash theme={"theme":"css-variables"} xorcise run regrade RUN_ID [--wait | --no-wait] [--yes] [--verbose] ``` Re-grades a finished run's sealed evidence against the current settings. The agent is not re-run: the deterministic checks and the LLM judge re-evaluate the evidence already recorded for the run. Use it after fixing grading configuration — a judge token budget the transcript overflowed, or a rejected model key. The recorded result is replaced. | Option | Type | Default | Meaning | | ---------------------- | --------- | -------- | ----------------------------------------------------------------------------- | | `--wait` / `--no-wait` | flag pair | `--wait` | Poll until grading finishes and print the fresh result, or return on the ack. | | `--yes`, `-y` | flag | off | Skip the confirmation. | | `--verbose`, `-v` | flag | off | Add the per-check deterministic list and the per-criterion judge rubric. | With `--wait`, the CLI polls for up to four minutes and then exits `3` if grading has not landed. Grading continues either way. ```bash theme={"theme":"css-variables"} xorcise run regrade 4c62254b --yes ``` ### xorcise run delete ```bash theme={"theme":"css-variables"} xorcise run delete RUN_ID [--yes] ``` Deletes a run's recorded result and its run record. An active run cannot be deleted — terminate it first. | Option | Type | Default | Meaning | | ------------- | ---- | ------- | ---------------------- | | `--yes`, `-y` | flag | off | Skip the confirmation. | ```bash theme={"theme":"css-variables"} xorcise run delete 4c62254b --yes ``` ### xorcise run report ```bash theme={"theme":"css-variables"} xorcise run report RUN_ID [--format FORMAT] [--out PATH] ``` Writes one self-contained document containing the run metadata, scores, check table, judge rubric and per-criterion verdicts, artifacts, telemetry summary, and disclosed conditions. | Option | Type | Default | Meaning | | ---------- | -------------- | --------------------------- | ------------------------------------------------ | | `--format` | `md` or `html` | `md` | Report format. | | `--out` | path | `./xorcise-run-.` | Where to write it. An unwritable path exits `1`. | Exits `3` if the run is still active or still grading. ```bash theme={"theme":"css-variables"} xorcise run report 4c62254b --format html --out ~/reports/scout.html ``` ### xorcise run traces ```bash theme={"theme":"css-variables"} xorcise run traces RUN_ID [--since SEQ] [--json] ``` Fetches the OpenTelemetry records XORCISE collected for a run. The human view prints one line per record with its sequence number and span name. | Option | Type | Default | Meaning | | --------- | ------- | ------- | ----------------------------------------------------------------------------- | | `--since` | integer | `-1` | Exclusive sequence cursor for incremental polling. `-1` returns every record. | | `--json` | flag | off | Emit the raw envelope: `run_id` and `records`. | ```bash theme={"theme":"css-variables"} xorcise run traces 4c62254b --since 120 --json ``` ### xorcise run prompt ```bash theme={"theme":"css-variables"} xorcise run prompt RUN_ID ``` Prints the run's connect prompt exactly as the agent should receive it, with real newlines and no wrapping, so it survives redirection. No options. ```bash theme={"theme":"css-variables"} xorcise run prompt 4c62254b > prompt.txt ``` ### xorcise run launch-profile ```bash theme={"theme":"css-variables"} xorcise run launch-profile RUN_ID ``` Prints the telemetry environment XORCISE configured for this run as dotenv `KEY=VALUE` lines. Export these before the harness starts — a harness reads them at start-up only. The output is empty when the run's harness has no telemetry provider. No options. ```bash theme={"theme":"css-variables"} xorcise run launch-profile 4c62254b > launch.env ``` ### xorcise run launch-cmd ```bash theme={"theme":"css-variables"} xorcise run launch-cmd RUN_ID [LAUNCH_MODE] ``` Prints a copy-paste startup block for a host-run harness: the telemetry `export` lines followed by the single-line harness command. When the run's harness has no launch command it says so and exits `0`. | Argument | Type | Default | Meaning | | ------------- | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `RUN_ID` | text | required | Run id or unique prefix. | | `LAUNCH_MODE` | `host` or `container` | `host` | Which address the telemetry endpoint points at. `host` targets this machine; `container` bakes in `host.docker.internal`, which does not resolve from a plain terminal. | Launch mode is the most common cause of a run that records no traces. Use `host` when you start the harness in your own shell. ```bash theme={"theme":"css-variables"} xorcise run launch-cmd 4c62254b ``` ### xorcise run events export ```bash theme={"theme":"css-variables"} xorcise run events export RUN_ID [--out PATH] ``` Writes the run's normalized event stream to JSONL, one event per line with clean bodies. It reads the local projection cache under `~/.xorcise` and only calls the instance when a short prefix needs resolving. This is a debugging and inspection tool, not a grading input. | Option | Type | Default | Meaning | | ------- | ---- | --------------------------------------------- | ------------------------- | | `--out` | path | `~/.xorcise/runs//agent-events.jsonl` | Where to write the JSONL. | ```bash theme={"theme":"css-variables"} xorcise run events export 4c62254b --out ./scout-events.jsonl ``` ## config ### xorcise config show ```bash theme={"theme":"css-variables"} xorcise config show [--json] ``` Shows the judge model, the terrain model and whether it inherits the judge, the mission library endpoint, the network addresses, and the default run budget. The API key is only ever shown as a four-character hint. | Option | Type | Default | Meaning | | -------- | ---- | ------- | -------------------------------------------------------------- | | `--json` | flag | off | Emit the raw configuration view. The key is still only a hint. | ```bash theme={"theme":"css-variables"} xorcise config show ``` ### xorcise config set-model ```bash theme={"theme":"css-variables"} xorcise config set-model [--key TEXT] [--base-url TEXT] [--name TEXT] [--timeout FLOAT] [--transcript-max-tokens N] [--span-max-tokens N] [--tokenizer TEXT] ``` Sets the bring-your-own judge model. Only the fields you pass change, and the change applies to the running instance immediately — no restart. Passing no field is a usage error, exit `2`. Without a judge model the judge half of every score is unavailable, which caps the overall score at 50%. | Option | Type | Default | Meaning | | ------------------------- | ------- | --------------- | ---------------------------------------------------------------------------------------------------------------- | | `--key` | text | unchanged | API key, stored locally in `~/.xorcise/.env`. `--key ''` clears it. | | `--base-url` | text | unchanged | OpenAI-compatible base URL. | | `--name` | text | unchanged | Model name. | | `--timeout` | float | `120.0` seconds | Judge HTTP timeout. | | `--transcript-max-tokens` | integer | `0` | Pre-flight cap on the estimated judge prompt. `0` disables the cap and lets the model's own context limit apply. | | `--span-max-tokens` | integer | `2000` | Per-span body cap in the distilled transcript. `0` disables it. | | `--tokenizer` | text | `o200k_base` | tiktoken encoding used to count the budget. | ```bash theme={"theme":"css-variables"} xorcise config set-model --name gpt-4o-mini --key sk-your-key ``` ### xorcise config test ```bash theme={"theme":"css-variables"} xorcise config test [--json] ``` Calls the saved judge model for real, which is the only way to prove the key and base URL work. Exits non-zero when the model is unconfigured or unreachable, so it can gate a script. | Option | Type | Default | Meaning | | -------- | ---- | ------- | ------------------------- | | `--json` | flag | off | Emit the raw test result. | ```bash theme={"theme":"css-variables"} xorcise config test ``` ### xorcise config set-terrain-model ```bash theme={"theme":"css-variables"} xorcise config set-terrain-model [--key TEXT] [--base-url TEXT] [--name TEXT] [--transcript-max-tokens N] ``` Overrides the model used for terrain attribution, field by field. Every field you leave unset falls back to the judge model, so an empty override means terrain uses the judge. Passing `''` clears a field. Passing no field is a usage error, exit `2`. | Option | Type | Default | Meaning | | ------------------------- | ------- | ---------------- | -------------------------------- | | `--key` | text | judge key | API key for the terrain model. | | `--base-url` | text | judge base URL | OpenAI-compatible base URL. | | `--name` | text | judge model name | Model name. | | `--transcript-max-tokens` | integer | `256000` | Safety cap per attribution call. | ```bash theme={"theme":"css-variables"} xorcise config set-terrain-model --name gpt-4o-mini ``` ### xorcise config test-terrain ```bash theme={"theme":"css-variables"} xorcise config test-terrain [--json] ``` Calls the effective terrain model — the override if one is set, otherwise the judge model — and reports which one it used. | Option | Type | Default | Meaning | | -------- | ---- | ------- | ------------------------- | | `--json` | flag | off | Emit the raw test result. | ```bash theme={"theme":"css-variables"} xorcise config test-terrain ``` ### xorcise config set-network ```bash theme={"theme":"css-variables"} xorcise config set-network [--headscale-url TEXT] [--advertise-host TEXT] ``` **Experimental.** Sets the two multi-machine addresses. Multi-machine deployment is unfinished: pointing a local-only instance at a remote control plane misconfigures it, so leave both unset unless you are deliberately testing that path. This is the only place these are set — the web UI shows them read-only. The values are read at boot, so a change needs `xorcise down` then `xorcise up`. Passing `''` unsets a field, and passing no field is a usage error, exit `2`. | Option | Type | Default | Meaning | | ------------------ | ---- | ------- | ---------------------------------------------- | | `--headscale-url` | text | unset | URL of the Headscale control plane to use. | | `--advertise-host` | text | unset | Address this machine advertises to the others. | ```bash theme={"theme":"css-variables"} xorcise config set-network --headscale-url '' ``` ## catalog ### xorcise catalog status ```bash theme={"theme":"css-variables"} xorcise catalog status [--json] ``` Shows the saved library setting alongside a live reachability probe, so a saved preference is never presented as a working connection. Exits `1` when the library is enabled but unreachable. The library needs no account, key, or sign-in. | Option | Type | Default | Meaning | | -------- | ---- | ------- | --------------------------------------------------------- | | `--json` | flag | off | Emit state, message, last sync, configured flag, and URL. | ```bash theme={"theme":"css-variables"} xorcise catalog status ``` ### xorcise catalog connect ```bash theme={"theme":"css-variables"} xorcise catalog connect [--json] ``` Enables the online mission library, then reports whether the endpoint actually answers. Idempotent: already connected prints `already enabled` and exits `0`. | Option | Type | Default | Meaning | | -------- | ---- | ------- | --------------------------------------------- | | `--json` | flag | off | Emit the configuration view after the change. | ```bash theme={"theme":"css-variables"} xorcise catalog connect ``` ### xorcise catalog disconnect ```bash theme={"theme":"css-variables"} xorcise catalog disconnect [--json] ``` Disables the online library so `xorcise mission list` shows only local missions. Installed missions keep working. Idempotent. | Option | Type | Default | Meaning | | -------- | ---- | ------- | --------------------------------------------- | | `--json` | flag | off | Emit the configuration view after the change. | ```bash theme={"theme":"css-variables"} xorcise catalog disconnect ``` ## Advanced ### xorcise serve ```bash theme={"theme":"css-variables"} xorcise serve [--role ROLE] [--stub] [--port PORT] [--otlp-port PORT] ``` Runs XORCISE in the foreground. This is the process `xorcise up` starts for you; use `up` for a normal install. Sibling commands such as `status` and `ui` discover a relocated port only for instances started by `up`. | Option | Type | Default | Meaning | | -------------- | ---------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------- | | `--role` | `all`, `control`, `runner`, `headscale`, `collector` | `all` | Which service role to boot. Only `all` is a complete install — see [`xorcise role list`](#xorcise-role-list). | | `--stub` | flag | off | Use stub adapters so XORCISE runs without Docker. | | `--port`, `-p` | integer 1–65535 | `3001` | REST port. Auto-increments when busy. | | `--otlp-port` | integer 1–65535 | `4318` | OTLP port. Auto-increments when busy. | ```bash theme={"theme":"css-variables"} xorcise serve ``` ### xorcise db upgrade ```bash theme={"theme":"css-variables"} xorcise db upgrade ``` Applies pending database migrations. It is always deliberate and never runs at boot: `xorcise up` migrates a fresh database, but refuses to migrate one that already holds data. A history mismatch — a database stamped by a different build — is reported as such and exits `1`, with the recovery path being a backup of `~/.xorcise/xorcise.db` or a clean start via `xorcise down --purge`. No options. ```bash theme={"theme":"css-variables"} xorcise db upgrade ``` ### xorcise role show ```bash theme={"theme":"css-variables"} xorcise role show [--json] ``` **Experimental.** Reports the service role this shell would boot, taken from `XORCISE_ROLE` and defaulting to `all`. This is not necessarily the role a running instance is serving — ask `xorcise system` for that. | Option | Type | Default | Meaning | | -------- | ---- | ------- | -------------------------------------------------------------------------------------- | | `--json` | flag | off | Emit the role record, including an `experimental` boolean and where the key came from. | ```bash theme={"theme":"css-variables"} xorcise role show ``` ### xorcise role list ```bash theme={"theme":"css-variables"} xorcise role list [--json] ``` **Experimental.** Lists the five roles with a maturity column. | Option | Type | Default | Meaning | | -------- | ---- | ------- | ------------------- | | `--json` | flag | off | Emit the role list. | ```bash theme={"theme":"css-variables"} xorcise role list ``` ```text title="Output" theme={"theme":"css-variables"} Role Key Maturity Purpose ────────────────────────────────────────────────────────────────────────────── All services all Ready Run all XORCISE services on this machine Control control Experimental Run the API and control-plane services Runner runner Experimental Run mission execution services Headscale headscale Experimental Run the private-network coordination service Collector collector Experimental Receive agent telemetry ``` Only `all` is a complete install. The others boot, but multi-machine deployment is unfinished: `control` accepts a run and returns a run id without ever launching a container, and `runner` and `headscale` serve only a health endpoint. ## Environment variables Configuration resolves highest first: **command-line flags**, then **`XORCISE_*` environment variables**, then `~/.xorcise/.env`, then `~/.xorcise/config.toml`. Every setting is reachable as `XORCISE_`, so anything `xorcise config show` lists can be set from the environment. These are the ones the CLI itself reads. | Variable | Default | Meaning | | -------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `XORCISE_HOME` | `~/.xorcise` | The data directory. Configuration, `.env`, the database, missions, runs, and the runtime port record all live under it. | | `XORCISE_DEBUG` | unset | Set to `1` for full tracebacks instead of the one-line error. It must come before the command, as in `XORCISE_DEBUG=1 xorcise status`. | | `XORCISE_ROLE` | `all` | The service role this shell boots. Only meaningful on the experimental multi-machine path. | | `XORCISE_USE_STUBS` | unset | Set to `1` to force stub adapters. Equivalent to `--stub`, which sets it. | | `XORCISE_REST_PORT` | `3001` | REST port. It also outranks runtime port discovery, so it is the way to point the CLI at a specific instance. | | `XORCISE_OTLP_PORT` | `4318` | OTLP receiver port. | | `XORCISE_RUNNER_PORT` | — | Runner plane port. | | `XORCISE_HEADSCALE_PORT` | — | Headscale plane port. | | `XORCISE_HEADSCALE_HOST_IP` | derived | Host IP the per-run router dials when the Docker bridge gateway cannot be derived. | | `XORCISE_MODEL_KEY` | unset | Judge API key. `xorcise config set-model --key` writes it to `~/.xorcise/.env`. | | `XORCISE_MODEL_BASE_URL` | unset | Judge base URL. | | `XORCISE_MODEL_NAME` | unset | Judge model name. | | `XORCISE_CATALOG_ENABLED` | `true` | The library connect switch. | | `XORCISE_CATALOG_URL` | see [Configuration keys](/reference/configuration) | Library endpoint. | | `XORCISE_DEFAULT_BUDGET_SECONDS` | `3600` | Default run budget. | | `XORCISE_DATABASE_URL` | `sqlite:////xorcise.db` | Database URL. | | `XORCISE_MISSIONS_ROOT` | `/missions` | Where installed missions are stored. | | `XORCISE_DOCKER_PLATFORM` | `linux/amd64` | Mission images are amd64; an arm64 host runs them under emulation. | `xorcise run launch-profile` and `xorcise run launch-cmd` emit `OTEL_*` variables for your harness to consume. The CLI does not read them. ## Related pages Every setting, its environment variable, and its default. Symptom to fix, starting from `doctor` and `status`.