Operational Commands

`swamp run`

Track and diagnose in-flight model method and workflow runs. The run tracker records every execution in a local SQLite database with heartbeat-based liveness detection. For conceptual background, see The Run Tracker.

`swamp run history`

List active and recent runs (model methods and workflows). Defaults to runs from the last 24 hours.

swamp run history

Flag	Description
`--active`	Show only currently running executions (mutually exclusive with `--all`)
`--all`	Show all tracked runs, not just recent (mutually exclusive with `--active`)
`--server <url>`	Run through a `swamp serve` server (`ws://` or `http://`) instead of locally (env: `SWAMP_SERVE_URL`)
`--token <token>`	Server token in `<name>.<secret>` format; only applies with `--server` (env: `SWAMP_SERVER_TOKEN`)
`--repo-dir <dir>`	Repository directory (env: `SWAMP_REPO_DIR`)

Text output:

STATUS     KIND    NAME                   ID        AGE  PID    HOST             INITIATED BY
running    method  command/shell/execute  cc665a58  3s   18669  Mac.localdomain  user:stack72
completed  method  command/shell/execute  3760deda  25s  18783  Mac.localdomain  user:stack72
cancelled  method  command/shell/execute  cc665a58  39s  18669  Mac.localdomain  ghost

When no runs are tracked, the output is:

No tracked runs.

JSON output (--json):

{
  "runs": [
    {
      "id": "6a7290fa-5cbb-4d24-b043-1cfc6127bbce",
      "runKind": "model_method",
      "modelType": "command/shell",
      "methodName": "execute",
      "workflowName": null,
      "pid": 18920,
      "hostname": "Mac.localdomain",
      "status": "running",
      "startedAt": "2026-07-02T00:13:06.113Z",
      "heartbeatAt": "2026-07-02T00:13:06.113Z",
      "stale": false,
      "initiatedBy": "user:stack72"
    }
  ]
}

Each run object includes:

Field	Type	Description
`id`	string	Unique run identifier
`runKind`	string	`model_method` or `workflow`
`modelType`	string or null	Model type (e.g., `command/shell`), null for workflows
`methodName`	string or null	Method name, null for workflows
`workflowName`	string or null	Workflow name, null for model methods
`pid`	number	OS process ID of the executing process
`hostname`	string	Machine hostname where the run is executing
`status`	string	`running`, `completed`, `failed`, or `cancelled`
`startedAt`	string	ISO 8601 timestamp
`heartbeatAt`	string	ISO 8601 timestamp of the last heartbeat
`stale`	boolean	`true` if the heartbeat has expired and the process is dead
`initiatedBy`	string or null	Principal who started the run (e.g. `user:stack72`, `ghost`). Absent on runs created before this field was added

Examples:

swamp run history                        # recent runs (last 24h)
swamp run history --active               # what's running now
swamp run history --all                  # full history (7-day retention)
swamp run history --server ws://host:9090 # query a remote server

`swamp run doctor`

Diagnose stale or orphaned runs in the run tracker. A run is stale when its heartbeat has stopped and the originating process is no longer alive.

swamp run doctor

Flag	Description
`--fix`	Automatically reap stale runs instead of just reporting them
`--server <url>`	Run through a `swamp serve` server (`ws://` or `http://`) instead of locally (env: `SWAMP_SERVE_URL`)
`--token <token>`	Server token in `<name>.<secret>` format; only applies with `--server` (env: `SWAMP_SERVER_TOKEN`)
`--repo-dir <dir>`	Repository directory (env: `SWAMP_REPO_DIR`)

When stale runs are detected:

1 stale run(s) detected:
KIND    NAME                   ID        HEARTBEAT AGE  PID    HOST
method  command/shell/execute  58bb2b7f  2m            31822  Mac.localdomain

Run with --fix to automatically reap stale runs.

With --fix, stale runs are reaped (transitioned to failed):

1 stale run(s) detected:
KIND    NAME                   ID        HEARTBEAT AGE  PID    HOST
method  command/shell/execute  58bb2b7f  2m            31822  Mac.localdomain

Reaped 1 stale run(s).

When no active or stale runs exist:

No active or stale runs.

For a task-oriented walkthrough, see Clear Stuck Runs.

Examples:

swamp run doctor                           # report stale runs
swamp run doctor --fix                     # reap stale runs automatically
swamp run doctor --server ws://host:9090   # diagnose on a remote server

`swamp run gc`

Garbage-collect old workflow runs and model method outputs. Cleans .swamp/workflow-runs/ and .swamp/outputs/, which swamp data gc does not cover.

swamp run gc

Running and suspended workflow runs are never deleted regardless of age. Pending and running model method outputs are never deleted.

Flag	Description
`--dry-run`	Show what would be deleted without deleting
`-y, --yes`	Skip confirmation prompt (`--force` / `-f` also accepted)
`--older-than <duration>`	Retention period. Units: `m`=minutes, `h`=hours, `d`=days, `w`=weeks, `mo`=months, `y`=years (default: `30d`)
`--json`	Output in JSON format (non-interactive)
`--repo-dir <dir>`	Repository directory (env: `SWAMP_REPO_DIR`)
`--server`	Run against a remote `swamp serve` instance (env: `SWAMP_SERVE_URL`)
`--token`	Server token in `<name>.<secret>` format; only with `--server` (overrides stored credentials and SWAMP_SERVER_TOKEN)

JSON output (--json):

{
  "workflowRunsDeleted": 0,
  "workflowRunBytesReclaimed": 0,
  "outputsDeleted": 0,
  "outputBytesReclaimed": 0,
  "totalBytesReclaimed": 0,
  "dryRun": true
}

Each field:

Field	Type	Description
`workflowRunsDeleted`	number	Number of workflow run directories removed
`workflowRunBytesReclaimed`	number	Bytes freed from workflow runs
`outputsDeleted`	number	Number of model method output directories removed
`outputBytesReclaimed`	number	Bytes freed from model method outputs
`totalBytesReclaimed`	number	Total bytes freed (workflow runs + outputs)
`dryRun`	boolean	`true` when `--dry-run` was passed

Examples:

swamp run gc --dry-run                   # preview what would be collected
swamp run gc --yes                       # run with default 30-day retention
swamp run gc --older-than 7d             # delete runs older than 7 days
swamp run gc --json --older-than 14d     # non-interactive, structured output

`swamp datastore lock`

Inspect and force-release datastore locks. Model method runs acquire a per-model file lock to serialize concurrent access (see Per-Model Method Locking). These commands are the breakglass for stuck locks.

`swamp datastore lock status`

Show who holds the datastore lock — the model, PID, hostname, and acquisition time.

swamp datastore lock status

Flag	Description
`--repo-dir <dir>`	Repository directory (env: `SWAMP_REPO_DIR`)

Examples:

swamp datastore lock status                  # check if any lock is held

`swamp datastore lock release`

Force-release a stuck datastore lock. Requires --force to confirm.

swamp datastore lock release --force

Flag	Description
`--force`	Required to confirm force release
`--model <model>`	Release a specific model's lock (`type/name` format, e.g. `aws-ec2/my-server`)
`--repo-dir <dir>`	Repository directory (env: `SWAMP_REPO_DIR`)

Without --model, releases the global datastore lock. With --model, releases only the named model's lock.

Examples:

swamp datastore lock release --force                              # release global lock
swamp datastore lock release --force --model aws-ec2/my-server    # release a model lock

`swamp audit`

View an audit timeline of Swamp vs direct CLI commands.

swamp audit

Flag	Default	Description
`--repo-dir <dir>`	`.`	Repository directory (env: `SWAMP_REPO_DIR`)
`--hours <n>`	`24`	Number of hours to look back
`--all`		Show all commands including noise
`--session <id>`		Filter by session ID
`--include-diagnostic`		Include rows written by `swamp doctor audit` smoke test
`--server`		Run against a remote `swamp serve` instance
`--token`		Server token in `<name>.<secret>` format

`swamp summarise`

Show a high-level overview of repository activity — method executions, workflows, and data. Also available as swamp summarize.

swamp summarise

Flag	Default	Description
`--repo-dir <dir>`	`.`	Repository directory (env: `SWAMP_REPO_DIR`)
`--since <dur>`	`7d`	Look-back window (e.g., `1h`, `1d`, `7d`, `1w`)
`--limit <n>`		Cap per-group run details
`--server`		Run against a remote `swamp serve` instance
`--token`		Server token in `<name>.<secret>` format

`swamp telemetry stats`

View telemetry usage statistics. Reads the user-global telemetry spool (~/.config/swamp/telemetry/, XDG-aware) and does not require a repository.

swamp telemetry stats

Flag	Default	Description
`--days <n>`	`2`	Number of days to report

`swamp source`

Manage the local copy of Swamp source code used for troubleshooting.

`swamp source fetch`

Download Swamp source code from GitHub.

swamp source fetch

Flag	Description
`--version <version>`	Version to fetch (tag or `main`). Default: latest.

`swamp source path`

Show the Swamp source location and installed version.

swamp source path

No flags.

`swamp source clean`

Remove downloaded Swamp source.

swamp source clean

No flags.

swamp run

swamp run history

swamp run doctor

swamp run gc

swamp datastore lock

swamp datastore lock status

swamp datastore lock release

swamp audit

swamp summarise

swamp telemetry stats

swamp source

swamp source fetch

swamp source path

swamp source clean

`swamp run`

`swamp run history`

`swamp run doctor`

`swamp run gc`

`swamp datastore lock`

`swamp datastore lock status`

`swamp datastore lock release`

`swamp audit`

`swamp summarise`

`swamp telemetry stats`

`swamp source`

`swamp source fetch`

`swamp source path`

`swamp source clean`