wattswarm run — Multi-Agent Run Queue CLI Commands

Reference for all wattswarm run subcommands: initialize the PostgreSQL queue, submit run specs, control run state, and operate the worker process.

The run command group manages the WattSwarm multi-agent orchestration queue. Unlike task run-real, which drives a single task synchronously, the run queue lets you define a set of agents as a RunSubmitSpec, submit the spec to PostgreSQL, and have a long-running worker process execute each step concurrently. Runs are durable: they survive restarts and support cancel, retry, and result queries at any point.

All run subcommands accept a --pg-url flag to override the PostgreSQL connection string. You can also set the connection permanently via the WATTSWARM_PG_URL environment variable.

---

run init

Initialise the run queue schema in PostgreSQL.

Synopsis

wattswarm [--state-dir <path>] [--store <name>] run init [--pg-url <url>]

Description

Creates the runs, run_steps, and run_events tables (and supporting indexes) in the target PostgreSQL database if they do not already exist. Call this once before submitting your first run. The Docker Compose setup runs run init automatically on container startup.

Example

wattswarm run init --pg-url postgres://postgres:postgres@127.0.0.1:55432/wattswarm

---

run submit

Submit a RunSubmitSpec JSON file to the run queue.

Synopsis

wattswarm [--state-dir <path>] [--store <name>] run submit <file> \
  [--kickoff] \
  [--pg-url <url>]

Arguments

Argument	Description
<file>	Path to a RunSubmitSpec JSON file.

Flags

Flag	Default	Description
--kickoff	false	Move the run and all its steps to QUEUED immediately after submission. Without this flag, the run stays in PENDING until you call run kickoff.

Description

Parses the spec file, creates a run record and one run_step row per agent, and prints the resulting run record as JSON. The shared_inputs object in the spec is merged into each agent’s TaskContract.inputs before the step is stored.

Example

wattswarm run submit ./run-spec.json --kickoff \
  --pg-url postgres://postgres:postgres@127.0.0.1:55432/wattswarm

Sample run-spec.json

{
  "run_id": "resume-review-001",
  "shared_inputs": {
    "job_title": "Senior Software Engineer",
    "requirements": "5+ years Rust, distributed systems experience preferred",
    "resume_text": "Jane Doe — 7 years Rust, co-authored raft-rs..."
  },
  "aggregation": {
    "quorum": 2,
    "tie_policy": {
      "enabled_on": ["TIE"],
      "chain": ["CONFIDENCE_WEIGHTED", "STOCHASTIC"]
    },
    "null_policy": {
      "enabled_on": ["EMPTY", "QUORUM_NULL"],
      "chain": ["REEXPLORE", "FINALIZE_NULL"]
    }
  },
  "agents": [
    {
      "agent_id": "screener",
      "executor": "rt",
      "profile": "default",
      "task_type": "swarm",
      "inputs": {
        "prompt": "Screen this resume against the job requirements and return a pass/fail verdict with reasoning."
      }
    },
    {
      "agent_id": "technical-reviewer",
      "executor": "rt",
      "profile": "default",
      "task_type": "swarm",
      "inputs": {
        "prompt": "Evaluate the technical depth of the resume and rate the candidate from 1–10."
      }
    },
    {
      "agent_id": "culture-fit",
      "executor": "rt",
      "profile": "default",
      "task_type": "swarm",
      "inputs": {
        "prompt": "Assess potential culture fit based on the resume language and experience patterns."
      }
    }
  ]
}

---

run kickoff

Move a run and all its steps to QUEUED so the worker can pick them up.

Synopsis

wattswarm [--state-dir <path>] [--store <name>] run kickoff <run_id> [--pg-url <url>]

Arguments

Argument	Description
<run_id>	The run ID to kick off (must match the run_id in the submitted spec).

Description

Transitions the run from PENDING to QUEUED and updates all run_steps accordingly. The worker loop picks up queued steps on its next poll interval. Use --kickoff on run submit to combine submission and kickoff in a single command.

Example

wattswarm run kickoff resume-review-001 \
  --pg-url postgres://postgres:postgres@127.0.0.1:55432/wattswarm

---

run watch

Poll a run until it reaches a terminal state.

Synopsis

wattswarm [--state-dir <path>] [--store <name>] run watch <run_id> [--pg-url <url>]

Arguments

Argument	Description
<run_id>	The run ID to observe.

Description

Reads the current run view from PostgreSQL and prints the run state, step statuses, and aggregation progress as pretty-printed JSON. The command returns immediately with the current snapshot — it does not block in a continuous poll loop. Run it repeatedly or in a shell loop to track progress.

Example

wattswarm run watch resume-review-001 \
  --pg-url postgres://postgres:postgres@127.0.0.1:55432/wattswarm

---

run result

Fetch the final decision and per-step conclusions for a completed run.

Synopsis

wattswarm [--state-dir <path>] [--store <name>] run result <run_id> [--pg-url <url>]

Arguments

Argument	Description
<run_id>	The run ID to retrieve the result for.

Description

Returns the runs.result_json payload as pretty-printed JSON. The result includes final_decision, final_answer, and per-step conclusion records. The result is available once the run reaches the FINALIZED state.

Example

wattswarm run result resume-review-001 \
  --pg-url postgres://postgres:postgres@127.0.0.1:55432/wattswarm

---

run events

Stream events for a run.

Synopsis

wattswarm [--state-dir <path>] [--store <name>] run events <run_id> \
  [--limit 50] \
  [--pg-url <url>]

Arguments

Argument	Description
<run_id>	The run ID to stream events for.

Flags

Flag	Default	Description
--limit	50	Maximum number of events to return.

Description

Returns the most recent run_events rows for the run as pretty-printed JSON, ordered by creation time. Use this to diagnose step failures, observe aggregation policy decisions, and trace re-explore triggers.

Example

wattswarm run events resume-review-001 --limit 20 \
  --pg-url postgres://postgres:postgres@127.0.0.1:55432/wattswarm

---

run cancel

Cancel an active run.

Synopsis

wattswarm [--state-dir <path>] [--store <name>] run cancel <run_id> [--pg-url <url>]

Arguments

Argument	Description
<run_id>	The run ID to cancel.

Description

Requests cancellation of the run. In-flight steps finish their current execution attempt; no new steps are claimed after the cancellation is applied. The run transitions to CANCELLED.

Example

wattswarm run cancel resume-review-001 \
  --pg-url postgres://postgres:postgres@127.0.0.1:55432/wattswarm

---

run retry

Retry a failed run.

Synopsis

wattswarm [--state-dir <path>] [--store <name>] run retry <run_id> [--pg-url <url>]

Arguments

Argument	Description
<run_id>	The run ID to retry.

Description

Resets failed steps to QUEUED and moves the run back to an active state so the worker can re-execute them. Retry uses exponential backoff via RETRY_WAIT → QUEUED transitions.

Example

wattswarm run retry resume-review-001 \
  --pg-url postgres://postgres:postgres@127.0.0.1:55432/wattswarm

---

run worker

Start the long-running run queue worker process.

Synopsis

wattswarm [--state-dir <path>] [--store <name>] run worker \
  [--concurrency 8] \
  [--pg-url <url>]

Flags

Flag	Default	Description
--concurrency	8	Maximum number of run steps to execute concurrently.
--pg-url	env WATTSWARM_PG_URL	PostgreSQL connection string.

Additional worker flags

Flag	Default	Description
--worker-id	auto UUID	Stable worker identifier for lease ownership.
--poll-ms	250	Milliseconds between queue poll cycles.
--lease-ms	30000	Step lease duration in milliseconds. Steps whose leases expire are reclaimed by other workers.
--once	false	Process one batch and exit. Useful for CI and scripted runs.

Description

run worker is a long-running process that continuously claims run_steps in QUEUED or RETRY_WAIT state, executes them by driving the full WattSwarm task lifecycle against the registered executor, and updates step and run status until each step reaches a terminal state (FINALIZED, FAILED, or CANCELLED).

You must run at least one worker process for any run to make progress. The Docker Compose setup starts a dedicated worker container automatically.

Writing rows directly into the runs table is not sufficient for execution. Runs require valid run_steps rows and at least one active worker process claiming them.

Examples

# Start a worker with default concurrency
wattswarm run worker \
  --pg-url postgres://postgres:postgres@127.0.0.1:55432/wattswarm

# Start a high-concurrency worker for production
wattswarm run worker \
  --concurrency 32 \
  --poll-ms 100 \
  --lease-ms 60000 \
  --pg-url postgres://postgres:[e-mail]:5432/wattswarm