> ## Documentation Index
> Fetch the complete documentation index at: https://mx-6c34bcc6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
wattswarm run submit ./run-spec.json --kickoff \
  --pg-url postgres://postgres:postgres@127.0.0.1:55432/wattswarm
```

### Sample `run-spec.json`

```json theme={null}
{
  "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**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
wattswarm run cancel resume-review-001 \
  --pg-url postgres://postgres:postgres@127.0.0.1:55432/wattswarm
```

***

## `run retry`

Retry a failed run.

**Synopsis**

```bash theme={null}
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**

```bash theme={null}
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**

```bash theme={null}
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.

<Warning>
  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.
</Warning>

**Examples**

```bash theme={null}
# 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
```