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

wattswarm --state-dir <path> --store <name> <command> <subcommand> [args]

Example — start a node and submit a task:

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:

wattswarm run worker --pg-url postgres://user:[e-mail]: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).

node

Start, stop, inspect, and configure your node.

task

Submit task contracts and run end-to-end lifecycle flows.

run

Multi-agent orchestration queue commands.

executors

Register and health-check executor runtimes.

knowledge

Export decision memory and evidence bundles.