Skip to main content
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.

​
Find a command

Every command is also listed in full below, in the order the CLI groups them.

​
Command summary

xorcise agent delete, xorcise mission rm, and xorcise run rm are accepted aliases of agent rm, mission delete, and run delete.

​
Conventions

​
Global options

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

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.
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

​
Start and stop

​
xorcise up

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 <url> 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.

​
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.

​
xorcise status

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.
Output

​
xorcise doctor

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, the data directory, the mission base, the host platform, and nested containers. 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. Three of those checks decide whether missions can run at all: The nested-containers probe boots a throwaway privileged container, and pulls its image on a cold host, so it can take a minute with no output. doctor prints a line saying so before it starts — wait rather than interrupting it. It runs only under doctor, never under xorcise up, because a host that cannot nest can still serve the UI and run static missions. A probe that fails to run at all is reported as undetermined and is a warning, not a blocker: “the probe broke” is a different claim from “this host cannot nest”.

​
xorcise down

Stops XORCISE and reaps any orphaned per-run mission containers. With no flags it clears transient runtime state and keeps your configuration and data. --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.

​
Instance and results

​
xorcise system

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.

​
xorcise leaderboard

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.
Output

​
agent

​
xorcise agent list

Lists registered agents with their harness, version, and disclosed model.

​
xorcise agent register

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. --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.

​
xorcise agent update

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.

​
xorcise agent rename

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.

​
xorcise agent history

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.

​
xorcise agent rm

Removes the agent, its version history, and its recorded runs and results. Prompts on an interactive terminal.

​
mission

​
xorcise mission list

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. The columns are Source, Id, Name, Difficulty, State, and Size. State is one of three values. Available means not installed. Installed means installed and current. Update available means installed, but the library now serves a different artifact for that mission — either the creator shipped a new mission version or the fleet was re-fused onto a newer base. xorcise mission update is the one action that clears it. Size is what the pull will download, and only ever for a mission you have not installed. It is a ceiling rather than a prediction: missions share base layers, so a pull that reuses layers already on disk transfers less. An installed row reads as a dash, because its bytes are already on disk, and a mission whose size the library does not carry reads as unknown rather than 0 B. --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.

​
xorcise mission show

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. A mission you have not installed also shows a Download line — the same ceiling mission list quotes, with the image and attachment split beside it when the total genuinely decomposes into both. An installed mission shows no size at all.

​
xorcise mission pull

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.
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.

​
Which architecture gets pulled

The pull chooses the mission’s execution platform before any byte moves, so a mission this host cannot run is refused up front rather than after a multi-gigabyte download. In order:
  1. XORCISE_DOCKER_PLATFORM, if you set it. An explicit override wins unconditionally and pins every pull and run to it.
  2. Your host’s own platform, when the mission published and validated an image for it. An Apple Silicon or other ARM64 host runs a native linux/arm64 image.
  3. linux/amd64 under your host’s emulation layer, when the mission has no native image for you. The CLI says so: Native ARM64 image unavailable for this mission. Running the AMD64 mission using compatibility/emulation mode.
  4. Otherwise the pull is refused, naming what the mission does support: this mission supports <platforms>, and this host (<yours>) has no way to execute any of them.
The platform that actually landed is verified after the pull, recorded in the install, and carried into the run’s evidence and its report. xorcise doctor reports your host’s platform under the host platform check. A mission served by a library that predates this contract publishes no platform list. It behaves exactly as it did before, with Docker picking the platform.

​
xorcise mission update

Updates an installed library mission to the release the catalog currently serves, re-pulling it in place. Accepts an id or a display name. No options. Use it when xorcise mission list shows Update available for a mission. That one command covers both reasons the artifact can move — the creator shipping a new mission version, and the fleet being re-fused onto a newer base — because the user-facing operation is the same re-pull either way. The update is atomic: the install is replaced only once the new artifact is in place, so an interrupted update leaves the mission you already had. Layers shared with the previous release are already on disk, so an update usually moves far fewer bytes than the first pull. An install that already matches the catalog is an untouched no-op:
Output
Updating a mission that is not installed exits 1 and points at xorcise mission pull.
This replaces the delete-then-pull workaround. Do not xorcise mission delete a mission in order to get a newer copy of it — mission update does it in one step and without a window where the mission is not installed.

​
xorcise mission ingest

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 and install one with xorcise mission pull — no account, key, or sign-in.
Output
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.

​
xorcise mission delete

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.

​
run

​
xorcise run list

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.

​
xorcise run create

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.
Output

​
xorcise run status

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. Exits 3 while the run is still active or still grading, so it polls cleanly.

​
xorcise run terminate

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. With --wait, the CLI polls for up to four minutes and then exits 3 if grading has not landed. Grading continues either way.

​
xorcise run regrade

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. With --wait, the CLI polls for up to four minutes and then exits 3 if grading has not landed. Grading continues either way.

​
xorcise run delete

Deletes a run’s recorded result and its run record. An active run cannot be deleted — terminate it first.

​
xorcise run report

Writes one self-contained document containing the run metadata, scores, check table, judge rubric and per-criterion verdicts, artifacts, telemetry summary, and disclosed conditions. Exits 3 if the run is still active or still grading.

​
xorcise run traces

Fetches the OpenTelemetry records XORCISE collected for a run. The human view prints one line per record with its sequence number and span name.

​
Exporting the raw OTLP stream

--export writes the run’s whole raw OpenTelemetry stream — spans first, then logs, one OTLP/JSON envelope per line. The file carries no XORCISE framing: it is the Collector’s own otlpjson format, so it feeds straight into an OpenTelemetry Collector and on to Jaeger, Tempo, or anything else that reads OTLP.
Output
Export works mid-run. The evidence stores are append-only with whole-batch commits, so a partial export is always a valid prefix of the final stream, never a torn one. A run that is still active is labelled as such:
Output
The check happens before the download, so a run that seals mid-flight can only be over-labelled partial. A snapshot is never under-labelled complete. Two combinations are usage errors, exit 2: --export with --json, because one writes a file and the other prints an envelope; and --export with --since, because an export always takes a whole-run snapshot. For the normalized per-event stream instead, see xorcise run events export.

​
xorcise run prompt

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.

​
xorcise run launch-profile

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.

​
xorcise run launch-cmd

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. 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.

​
xorcise run events export

Writes the run’s normalized event stream to JSONL: a header line carrying the event count, then one event per line with clean bodies. It reads the running instance over GET /api/runs/{run_id}/events.jsonl, matching run report and run traces --export. This is a debugging and inspection tool, not a grading input. Works mid-run as a partial snapshot. The server still writes its own copy under ~/.xorcise/runs/<run_id>/ when a run seals; that copy is unrelated to where this command writes. For the raw, unnormalized OTLP stream instead, see xorcise run traces --export.

​
config

​
xorcise config show

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.

​
xorcise config set-model

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%.

​
xorcise config test

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.

​
xorcise config set-terrain-model

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.

​
xorcise config test-terrain

Calls the effective terrain model — the override if one is set, otherwise the judge model — and reports which one it used.

​
xorcise config set-network

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.

​
catalog

​
xorcise catalog status

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.

​
xorcise catalog connect

Enables the online mission library, then reports whether the endpoint actually answers. Idempotent: already connected prints already enabled and exits 0.

​
xorcise catalog disconnect

Disables the online library so xorcise mission list shows only local missions. Installed missions keep working. Idempotent.

​
Advanced

​
xorcise serve

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.

​
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.

​
xorcise role show

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.

​
xorcise role list

Experimental. Lists the five roles with a maturity column.
Output
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_<FIELD>, so anything xorcise config show lists can be set from the environment. These are the ones the CLI itself reads. xorcise run launch-profile and xorcise run launch-cmd emit OTEL_* variables for your harness to consume. The CLI does not read them.

Configuration keys

Every setting, its environment variable, and its default.

Troubleshooting

Symptom to fix, starting from doctor and status.