Skip to main content
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
ArgumentDescription
<file>Path to a RunSubmitSpec JSON file.
Flags
FlagDefaultDescription
--kickofffalseMove 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
ArgumentDescription
<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
ArgumentDescription
<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
ArgumentDescription
<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
ArgumentDescription
<run_id>The run ID to stream events for.
Flags
FlagDefaultDescription
--limit50Maximum 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
ArgumentDescription
<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
ArgumentDescription
<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
FlagDefaultDescription
--concurrency8Maximum number of run steps to execute concurrently.
--pg-urlenv WATTSWARM_PG_URLPostgreSQL connection string.
Additional worker flags
FlagDefaultDescription
--worker-idauto UUIDStable worker identifier for lease ownership.
--poll-ms250Milliseconds between queue poll cycles.
--lease-ms30000Step lease duration in milliseconds. Steps whose leases expire are reclaimed by other workers.
--oncefalseProcess 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:postgres@db.example.com:5432/wattswarm