> ## 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 CLI Reference — Commands and Global Flags

> A complete map of every WattSwarm CLI command group, global flags, and invocation patterns for operating your node from the terminal.

The `wattswarm` binary is the primary interface for operating a WattSwarm node from the terminal. You use it to bring a node online, manage executor runtimes, submit tasks, run multi-agent orchestration queues, inspect the event log, export decision knowledge, and launch the kernel console UI — all from a single unified command surface.

## Global flags

These flags apply to every command and must be passed before the subcommand name:

| Flag          | Default           | Description                                                                                                                              |
| ------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `--state-dir` | `.wattswarm`      | Path to the node state directory. Holds `node_seed.hex`, `node_state.json`, `startup_config.json`, and executor registry state.          |
| `--store`     | `wattswarm.state` | Logical local store identifier. Resolved relative to `--state-dir` unless an absolute path is given. Does not change PostgreSQL routing. |

## Command groups

| Command     | Description                                                                                                                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `node`      | Bring the node online or offline, show status, export contact strings, and manage network bootstrap contacts and signed network params.                                                          |
| `peers`     | List peers discovered by this node.                                                                                                                                                              |
| `log`       | Inspect the append-only event log: read the head sequence, replay the log to rebuild projections, or verify log integrity.                                                                       |
| `executors` | Register executor runtimes, list registered executors, and health-check them against their `/health` endpoint.                                                                                   |
| `task`      | Submit a `TaskContract` JSON file, watch a task until it reaches a terminal state, fetch the finalized decision, or run a complete real-flow lifecycle end-to-end.                               |
| `run`       | Initialize the PostgreSQL run queue schema, submit multi-agent run specs, kick off runs, watch progress, fetch results, stream events, cancel, retry, and start the long-running worker process. |
| `knowledge` | Export decision knowledge bundles by task type or task ID for inspection and reuse analysis.                                                                                                     |
| `ui`        | Launch the kernel console web UI server.                                                                                                                                                         |

## Invocation pattern

```bash theme={null}
wattswarm --state-dir <path> --store <name> <command> <subcommand> [args]
```

**Example — start a node and submit a task:**

```bash theme={null}
wattswarm --state-dir ./.ws-dev --store wattswarm.state node up
wattswarm --state-dir ./.ws-dev --store wattswarm.state executors add rt http://127.0.0.1:8787
wattswarm --state-dir ./.ws-dev --store wattswarm.state task submit ./task.json
wattswarm --state-dir ./.ws-dev --store wattswarm.state task run-real --executor rt --profile default --task-id task-1
wattswarm --state-dir ./.ws-dev --store wattswarm.state task decision task-1
```

## PostgreSQL override

`run` commands accept an optional `--pg-url` flag to override the PostgreSQL connection string for that invocation:

```bash theme={null}
wattswarm run worker --pg-url postgres://user:pass@db.example.com:5432/wattswarm
```

You can also set the connection permanently with the `WATTSWARM_PG_URL` environment variable. Override the schema name with `WATTSWARM_PG_SCHEMA=<schema>` (default: `public`).

<CardGroup cols={2}>
  <Card title="node" icon="server" href="/cli/node">
    Start, stop, inspect, and configure your node.
  </Card>

  <Card title="task" icon="bolt" href="/cli/task">
    Submit task contracts and run end-to-end lifecycle flows.
  </Card>

  <Card title="run" icon="list-check" href="/cli/run">
    Multi-agent orchestration queue commands.
  </Card>

  <Card title="executors" icon="plug" href="/cli/executors">
    Register and health-check executor runtimes.
  </Card>

  <Card title="knowledge" icon="brain" href="/cli/knowledge">
    Export decision memory and evidence bundles.
  </Card>
</CardGroup>