CLI reference

Every command that reads or changes runtime state calls the v1 API at /v1/rpc or /v1/ws. The one exception is swarm verify, which validates contract files on disk and needs no running runtime.

Global flags

Flag	Purpose
`--api-server <url>`	API base URL. Also `connection.api_server` in config; default `http://127.0.0.1:8081`.
`--api-token-file <path>`	Bearer token file. Also `connection.api_token_file` in config.
`--context <name>`	Named connection context descriptor.
`--contracts <path>`	Contract bundle root. Also `paths.contracts_path` in config.
`--config <path>`	Explicit `swarm.yaml` config; overrides discovered layers.
`--json`	Machine-readable output (one JSON document, or NDJSON when streaming).
`--quiet`	Print only the primary value (for scripts) — no labels or formatting. Mutually exclusive with `--json`.
`--no-color`	Disable color. Also `NO_COLOR`.
`--log-level <debug\|info\|warn\|error>`	Diagnostic verbosity (default `info`).

Resolution precedence, highest first:

Command-line flag
Explicit --config file
./.swarm/swarm.yaml
./swarm.yaml
User-global $XDG_CONFIG_HOME/swarm/swarm.yaml
Built-in default

(The Configuration page lists the same layers.) Environment variables are not an accepted configuration source — retired SWARM_* variables fail with a teaching error naming the flag or config key. See Configuration.

Runtime

Command	Targets	Purpose
`swarm serve`	local	Start the runtime, API, health, and MCP listener.
`swarm run start`	RPC + local	Start (or reattach to) a run and stream its trace. Requires `--data` (or `workspace.data_source`) when booting in-process.
`swarm verify`	local	Validate a contract bundle on disk.
`swarm test [scenario...]`	RPC	Run deterministic scenario tests (see Testing).
`swarm doctor`	local	Check prerequisites and diagnose setup problems (config layers, backends, credentials).
`swarm context`	local	Show which runtime and directories this CLI targets.
`swarm describe`	local	Render the expanded authoring view of a contract bundle.
`swarm secrets`	local	Manage local secrets used by tools and providers.
`swarm connections`	local	Manage managed credential connections (OAuth and friends).
`swarm workspace`	local	Manage local workspace setup (image build, doctor).
`swarm migrate-producer-routing` / `swarm migrate-connect-delivery-one`	local	Rewrite contracts that still use removed routing fields (`target:`/`broadcast:` on emits, `connect.delivery: one`); run these if `swarm verify` reports `RETIRED-EMIT-ROUTING`.
`swarm version [--server]`	local / `health.check`	Print binary version; `--server` adds runtime identity.
`swarm completion <shell>`	local	Generate shell completion.

swarm run start without --connect boots a runtime in-process; with --connect <url> it drives a running one. It takes --event <name>, --payload <file>, and --data <dir>.

Runs

Command	Method	Purpose
`swarm run list`	`run.list`	List runs.
`swarm run status [run-id]`	`run.diagnose`	Diagnose one run (why it is not progressing).
`swarm run trace [run-id]`	`run.trace` / `run.subscribe_trace`	Print or follow (`-f`) a run’s causal trace.
`swarm run fork <source-run-id>`	`run.fork`	Fork a run from an event point. Flags: `--at-event <event-id>`, `--bundle-hash <hash>` (same-bundle only), `--idempotency-key <key>`.

Events and entities

Command	Method	Purpose
`swarm event list`	`event.list`	Query the event store (folds in dead-letter inspection).
`swarm event follow`	`event.subscribe`	Stream events live.
`swarm event view <id>`	`event.get`	One event with delivery detail.
`swarm event replay <id>`	`event.replay`	Redeliver an event to its subscribers.
`swarm event publish <event>`	`event.publish`	Publish one event (`--payload-json`); allocates a run if none given.
`swarm entity list`	`entity.list`	List entities.
`swarm entity view <id>`	`entity.get`	One entity with fields, gates, accumulator.
`swarm entity aggregate`	`entity.aggregate`	Counts grouped by a field.

Agents and conversations

Command	Method	Purpose
`swarm agent list`	`agent.list`	List agents and status.
`swarm agent view <id>`	`agent.get`	One agent’s status and session refs.
`swarm agent restart <id>`	`agent.restart`	Restart an agent session.
`swarm agent replay <id> --event-id <id>`	`agent.replay`	Redeliver one event to an agent.
`swarm agent replay-backlog <id>`	`agent.replay_backlog`	Redeliver an agent’s pending backlog.
`swarm agent directive <id> "<msg>"`	`agent.send_directive`	Send a directive to a running agent.
`swarm agent deliveries <id>`	`agent.deliveries`	One agent’s event delivery history.
`swarm agent diagnose <id>`	`agent.diagnose`	Why an agent is stuck: its pending-delivery queue in detail (`--queue-limit`, `--queue-cursor`).
`swarm conversation list`	`conversation.list`	List conversation summaries.
`swarm conversation view <session-id>`	`conversation.get`	Full session with all turns.
`swarm conversation turn <session-id> <n>`	`conversation.get_turn`	One turn in depth.
`swarm forkchat new <session-id>`	`conversation.fork`	Fork one conversation into a sandbox to iterate on it, optionally at a turn or event with an injected `--message`.
`swarm forkchat resume <fork-id>`	`conversation.fork_chat`	Send a sandboxed message into a forked conversation.
`swarm forkchat list \| view \| delete <fork-id>`	`conversation.fork_*`	List, inspect, or delete forked conversations.

Control and diagnostics

Command	Method	Purpose
`swarm control pause <run-id> \| --all`	`run.pause` / `runtime.pause`	Halt a run, or runtime ingress.
`swarm control continue <run-id> \| --all`	`run.continue` / `runtime.resume`	Resume a run, or ingress.
`swarm control stop <run-id> \| --all`	`run.stop`	Stop a run (or all, with confirmation).
`swarm control nuke`	`runtime.nuke`	Destructive runtime reset (`--dry-run` previews).
`swarm health`	`health.check`	Authenticated operator health summary.
`swarm mailbox list`	`mailbox.list`	List mailbox items.
`swarm mailbox view <id>`	`mailbox.get`	One item with its decision sheet.
`swarm mailbox approve\|reject\|defer <id>`	`mailbox.*`	Decide a pending item.
`swarm logs [--follow]`	`runtime.logs` / `runtime.subscribe_logs`	Query or follow runtime logs.
`swarm incidents`	`runtime.incidents`	Aggregated incidents by error code and component.

Bundles

Persisted contract bundles in the runtime store, identified by canonical bundle hash (a content hash of the bundle’s files).

Command	Method	Purpose
`swarm bundle list`	`bundle.list`	List persisted bundles.
`swarm bundle show <bundle-hash>`	`bundle.get`	One bundle’s catalog entry.
`swarm bundle agents <bundle-hash>`	`bundle.agents`	Agent definitions in a bundle.
`swarm bundle register <envelope-yaml>`	`bundle.register`	Register a bundle from a registration envelope, or from a contracts directory with `--contracts <dir>`.
`swarm bundle delete <bundle-hash>`	`bundle.delete`	Delete a persisted bundle by hash.

Exit codes

Code	Meaning
`0`	Success
`2`	CLI validation or misuse
`3`	Runtime or transport error
`4`	Auth or missing token
`5`	Resource not found
`6`	Resource state or idempotency conflict
`7`	Run terminal failed or cancelled
`130`	Interrupted or detached

Three replay surfaces, at different granularities:

Run. swarm run fork re-executes a whole run from an event point via run.fork.
Conversation. swarm forkchat (above) forks one agent conversation into a sandbox via conversation.fork.
Single event. swarm event replay and swarm agent replay redeliver an event to its subscribers.

Cross-bundle run forks (--bundle-hash differing from the source’s bundle) are gated separately and currently rejected. See Fork and replay.

Contract reference

Language reference

Operations reference

Global flags

Runtime

Runs

Events and entities

Agents and conversations

Control and diagnostics

Bundles

Exit codes

​Global flags

​Runtime

​Runs

​Events and entities

​Agents and conversations

​Control and diagnostics

​Bundles

​Exit codes

Global flags

Runtime

Runs

Events and entities

Agents and conversations

Control and diagnostics

Bundles

Exit codes