CLI reference

simian is a single binary with cobra subcommands. This page is generated from simian <cmd> --help output. There is a second binary, simian-eval, covered at the end: it drives a scenario pack against a subject and is deliberately not part of the operator binary.

To get the most up-to-date reference for any single command, run it with --help:

simian --help
simian serve --help
simian chaos --help
simian sut deploy --help

Subcommand index

Common flag patterns

Eligibility

--eligible-namespace <ns> (repeatable, simian serve) overrides the default annotation-based lookup. Without it, the controller treats any namespace with simian.chaos/eligible="true" as eligible.

LLM provider

--llm-provider gemini|stub (default gemini); --llm-model <id> overrides the default gemini-2.5-pro. Vertex/ADC and API-key auth are both supported (Vertex preferred for production via Workload Identity).

Executor safety policy

Set on simian serve:

Autonomous mode

Set on simian serve together:

Web UI

Set on simian serve:

Standalone web UI: simian web

The same page with no controller behind it, for one page that fronts several Simians. It serves /ui/, /healthz and GET /api/controllers; every other /api/ path is 404, so the page asks which Simian to watch.

simian web --addr :8080 \
    --controllers simian-1=https://simian.example.com \
    --controllers simian-2=https://simian-2.example.com

Envoy SUT injection

See Known limitations for why these default off.

Submitting a fault

simian chaos accepts three input shapes:

# 1. LLM-translated path
simian chaos --intent "kill one paymentservice pod for 30 seconds" --namespace boutique-1

# 2. Deterministic-control path with engine + kind + spec
simian chaos --engine chaos-mesh --kind PodChaos \
             --api-version chaos-mesh.org/v1alpha1 \
             --namespace boutique-1 --workload paymentservice \
             --duration 30s \
             --spec '{"action":"pod-kill","mode":"one","selector":{"labelSelectors":{"app":"paymentservice"}}}'

# 3. Submit a fully-formed manifest
simian chaos --manifest examples/network-latency-manifest.json

Plus the inspection / management subcommands:

simian chaos --list-active     # all leased faults
simian chaos --list-catalog    # catalog the LLM sees (all engines)
simian chaos --clear f-<UID>   # clear before lease expiry

--spec, --spec-file, and --stdin-spec are mutually exclusive — set at most one. The CLI rejects overlapping inputs upfront rather than silently picking one.

Scoring a run

--pack takes a built-in pack name (parity, lookout) or a directory of scenario files.

simian evaluate --pack parity --audit run.log --report agent.json
simian evaluate --pack ./packs/custom --audit - --report agent.json --format json

Two artifacts, joined on the scenario ID the audit sink stamps onto every event: the audit log says which faults landed and when, the report says what the subject found and when. Nothing is executed and no kubeconfig is read, so the same artifacts produce the same scorecard on any machine, any time later.

A scenario whose fault has no passing efficacy record prints as NOT SCORED rather than as a miss — the cluster was never broken, so a zero would mean “nothing to find” while reading as “the agent missed it”. Below --min-efficacy (default 0.8) the scorecard is still printed, then the command exits non-zero: the numbers measure the harness, not the subject. Pass --min-efficacy 0 to report anyway; the warning stays either way.

Exporting the audit trail

simian audit export --since 24h audit.jsonl.1 audit.jsonl
kubectl -n simian-system logs deploy/simian-controller | simian audit export --format json
kubectl -n simian-system exec deploy/simian-controller -- simian audit export /var/lib/simian/audit.jsonl

The controller image is distroless (no shell, no cat), so read the audit file in the pod by running simian audit export there, as in the last line.

One row per fault UID, folded from its events: source, kind, targets, the spec as it reached the cluster (after the safety stage narrowed it), whether the engine confirmed injection and the efficacy verdict, how it ended — refused, driver-failed, cleared, expired, or open if nothing ended it — and, for a Chaos Mesh fault that ran to its deadline, whether its target pods were Ready again within five minutes (RECOVERED; the JSON adds the pods still down and why). A fault can end on time and leave its workload broken; no there is the place to look first. --since takes a duration back from now or an RFC 3339 time and keeps faults first seen after it. --format json writes one object per line with the full spec; the table truncates it. Lines that are not audit events are skipped, so a controller’s whole log can be piped in.

--cycles folds the same records by autonomous-mode cycle instead: one row per cycle and namespace with its outcome (completed, skipped, unfinished when the controller restarted mid-cycle), the skip reason and what the gate, the LLM or the validator said (health-gate: workload Deployment/adservice: 0/1 pods ready), the hypothesis, the plan’s steps, and how many steps were applied and refused. --format json adds each step’s rationale and duration rationale. This is the answer to “what is autonomous mode doing, and why” without reading the controller log.

simian watch --namespace <arena> shows the same live: the latest plan in full and a line per recent cycle above the active and recent faults. It reads the controller’s get_recent_cycles MCP tool, which any MCP client can call too; the controller rebuilds recent cycles from its audit file at start-up.

simian serve --audit-file PATH writes the file (--audit-file-max-bytes, default 100 MiB, sets the rotation point). At start-up it adopts the faults a previous process left running and closes the ones it left open; the chart turns it on by default — see Helm values.

Tearing down

simian sut destroy --namespace boutique-1                # SUT only
simian sut destroy --namespace boutique-1 --with-arena   # both layers

destroy --with-arena refuses if simian-managed faults are still leased; pass --force to override (after clearing them with simian chaos --clear).

simian-eval — running a pack against a subject

A second binary. Cluster lifecycle, subject processes and scoring have no business linking into the operator binary that runs in-cluster with chaos RBAC.

simian-eval --pack parity --subject exec:./bin/lookout --out runs/
simian-eval --pack parity,lookout --subject exec:./bin/agent --concurrency 4
simian-eval --pack ./packs/custom --subject noop: --cluster kind --out runs/floor
simian-eval --pack parity --subject exec:./bin/agent --only parity-crash-loop

Per scenario: provision an arena namespace, inject the faults through the normal executor path — same validation, same safety stages, same leases, same efficacy gates — hand the subject the prompt, collect its report, then clear the chaos and put the namespace back. Two files land in --out: audit.log is Simian’s side, run.json is the subject’s, and they join on the scenario ID. A subject that keeps its own evidence leaves it there too. The scorecard printed at the end comes from reading those two files back, so simian evaluate reproduces it exactly, with or without the cluster.

Namespaces the run creates are annotated with simian.chaos/eval-run=<run id> and destroyed at the end. A namespace that already existed is annotated and left standing — a rig that deletes namespaces it merely found is one bad scenario file away from deleting something that mattered.

Each scenario’s eval.scenario_started audit line records the pack, the subject and the cluster (the kubeconfig context, or the kind cluster’s name), so a run directory says what it measured and where.

simian-eval report — combining runs into a scorecard

simian-eval report --run runs/dataplane-lookout --run runs/dataplane-agent --out scorecard.json

Reads run directories, scores each exactly as its own scorecard did, and writes one self-describing JSON document — scenarios by subjects, with each scenario’s fault, ground truth and every subject’s report — that the web UI’s Scorecard mode renders with no server. See Reading an evaluation: the scorecard.

An arena that could not be destroyed is a suite-level failure: simian-eval prints the whole scorecard, then exits non-zero naming the scenarios and the namespaces. The scores themselves are untouched, because a namespace that would not go away says nothing about what the subject answered — but what is left behind carries simian.chaos/eligible, which is a standing permission to inject there, so it is not something to find out about from the next run. The fact is written to the audit log as eval.arena_leaked, so simian evaluate re-scoring the artifacts later reports it too.