Complete reference for all swarm CLI commands and flags.
swarm <COMMAND>
Initialize swarm configuration for a project. Creates ~/.swarm/settings.json with a template entry if it doesn't exist.
| Flag | Type | Default | Description |
|---|
--path | PathBuf | . | Path to the project directory |
Start a swarm session. Executes the 13-step orchestrator start flow.
| Flag | Type | Default | Description |
|---|
--stash | bool | false | Auto-stash uncommitted changes before starting |
--init | bool | false | Initialize git repo if not already initialized |
--no-tui | bool | false | Run in headless mode (no terminal UI) |
Stop a running swarm session. Sends SIGTERM to the orchestrator and waits for graceful shutdown.
| Flag | Type | Default | Description |
|---|
--merge | bool | false | Merge agent branches into base (default if no flag set) |
--squash | bool | false | Squash-merge agent branches |
--discard | bool | false | Discard agent branches without merging |
The --merge, --squash, and --discard flags are mutually exclusive. If none are specified, merge is the default behavior.
Show session status including agent states, uptime, and beads summary.
| Flag | Type | Default | Description |
|---|
--json | bool | false | Output in JSON format |
View agent logs.
| Argument | Type | Required | Description |
|---|
agent | String | Yes | Agent name |
| Flag | Type | Default | Description |
|---|
--follow | bool | false | Tail the log (like tail -f) |
--session | u32 | null | View archived session log instead of current |
Send a message to a specific agent.
| Argument | Type | Required | Description |
|---|
agent | String | Yes | Recipient agent name |
message | String | Yes | Message body |
| Flag | Type | Default | Description |
|---|
--urgent | bool | false | Mark as urgent (triggers interrupt) |
Send a message to all agents.
| Argument | Type | Required | Description |
|---|
message | String | Yes | Message body |
| Flag | Type | Default | Description |
|---|
--urgent | bool | false | Mark as urgent |
Show the resolved configuration for the current project.
| Flag | Type | Default | Description |
|---|
--json | bool | false | Output raw JSON instead of formatted |
Clean stale swarm artifacts (worktrees, branches, session files).
| Flag | Type | Default | Description |
|---|
--force | bool | false | Remove artifacts without confirmation |
Manage workflow definitions and runs. This is a subcommand group:
List available workflow definitions.
Start a workflow run.
| Argument | Type | Required | Description |
|---|
name | String | Yes | Workflow name |
| Flag | Type | Default | Description |
|---|
--input | KEY=VALUE | [] | Input key=value pairs (repeatable) |
Show status of running/completed workflows.
| Argument | Type | Required | Description |
|---|
run_id | String | No | Specific run ID (omit to list all) |
| Flag | Type | Default | Description |
|---|
--json | bool | false | Output in JSON format |
Approve a human-approval gate.
| Argument | Type | Required | Description |
|---|
run_id | String | Yes | Workflow run ID |
stage | String | Yes | Stage name |
Reject a gate with optional feedback.
| Argument | Type | Required | Description |
|---|
run_id | String | Yes | Workflow run ID |
stage | String | Yes | Stage name |
| Flag | Type | Default | Description |
|---|
--feedback | String | null | Feedback message |
Manually retry a failed stage.
| Argument | Type | Required | Description |
|---|
run_id | String | Yes | Workflow run ID |
stage | String | Yes | Stage name |
Cancel a running workflow.
| Argument | Type | Required | Description |
|---|
run_id | String | Yes | Workflow run ID |
Show detailed run info including outputs.
| Argument | Type | Required | Description |
|---|
run_id | String | Yes | Workflow run ID |
Validate a workflow definition.
| Argument | Type | Required | Description |
|---|
name | String | Yes | Workflow name |
Run an iteration loop from a configuration file.
| Flag | Type | Default | Description |
|---|
--config | String | null | Iteration config name (looked up in .swarm/iterations/<name>.yml) |
--config-file | PathBuf | null | Path to iteration config YAML file |
--resume | String | null | Resume a previous iteration run |
--max-iterations | u32 | null | Override max_iterations from config |
--dry-run | bool | false | Validate config and show plan without executing |
--no-tui | bool | false | Run without TUI |
--json | bool | false | Output progress as JSON lines |
The --config and --config-file flags are mutually exclusive.