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.

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

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

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

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

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

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