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 tracked run is stale when either:

its heartbeat is older than the 90-second TTL, or
it was started on this host and its process is no longer alive. Such a run is stale straight away, without waiting for the TTL.

A workflow run is orphaned when its run record is still running but its owning process is gone.

swamp run doctor

Flag	Description
`--fix`	Reap stale runs and settle orphaned workflow 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:

2 stale run(s) detected:
KIND      NAME                   ID        HEARTBEAT AGE  PID    HOST
method    command/shell/execute  3fc80c74  13s            41285  Mac.localdomain
workflow  slow                   faebb8ba  13s            41285  Mac.localdomain

Run with --fix to automatically reap stale runs.

1 orphaned workflow run(s) whose owner is gone:
Run with --fix to automatically reap orphaned workflow runs.

With --fix, stale tracker rows are reaped and become interrupted. Each orphaned workflow run record is settled too: the run becomes interrupted with interrupt_reason: owner_process_dead, and its in-flight steps become unknown.

2 stale run(s) detected:
KIND      NAME                   ID        HEARTBEAT AGE  PID    HOST
method    command/shell/execute  519a69c9  7s             41581  Mac.localdomain
workflow  slow                   0009e429  7s             41581  Mac.localdomain

Reaped 2 stale run(s).

1 orphaned workflow run(s) whose owner is gone:
Reaped 1 orphaned workflow run(s).

JSON output (--json):

{
  "totalTracked": 2,
  "active": 0,
  "stale": 2,
  "reaped": 0,
  "orphanedWorkflowRuns": 1,
  "orphanedReaped": 0,
  "activeRuns": [],
  "staleRuns": [
    {
      "id": "faebb8ba-cb7b-43a2-90d7-d39b1dfd2db5",
      "runKind": "workflow",
      "modelType": null,
      "methodName": null,
      "workflowName": "slow",
      "pid": 41285,
      "hostname": "Mac.localdomain",
      "status": "running",
      "startedAt": "2026-10-02T01:26:08.889Z",
      "heartbeatAt": "2026-10-02T01:26:08.889Z",
      "stale": true
    }
  ]
}

orphanedWorkflowRuns counts workflow run records left running by a dead owner; orphanedReaped counts those --fix settled. --server reports the same fields.

To settle one stuck workflow run without running the doctor, use swamp workflow recover <workflow> --run <id> — see Checkpoint recovery.

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

Each collected run's evaluated-workflow snapshot (.swamp/workflows-evaluated/runs/<run-id>/) is deleted with it. A snapshot with no run record is swept once it is older than both the workflow-run retention and one hour, so a run that is just starting keeps its snapshot.

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

Repository defaults: .swamp.yaml can set per-category retention via garbageCollection.outputs and garbageCollection.workflowRuns. When --older-than is not passed, run gc uses these values (defaulting to 30d when omitted).

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 — overrides the `.swamp.yaml` defaults for this invocation. 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,
  "evaluatedSnapshotsDeleted": 0,
  "evaluatedSnapshotBytesReclaimed": 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
`evaluatedSnapshotsDeleted`	number	Number of per-run evaluated-workflow snapshots removed
`evaluatedSnapshotBytesReclaimed`	number	Bytes freed from those snapshots
`totalBytesReclaimed`	number	Total bytes freed (workflow runs + outputs + snapshots)
`dryRun`	boolean	`true` when `--dry-run` was passed; the counts are what would be removed

Log output:

Run GC complete: deleted 3 workflow run(s) ("12.0 KB"), 5 output(s) ("1.2 MB"), 3 run snapshot(s) ("4.5 KB"), total: 11 items ("1.2 MB")

With --dry-run the line starts Run GC dry run: would delete. Without --dry-run or --yes, a Run GC preview: line with the same counts is shown before the confirmation prompt.

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

With --server on a server with authentication, the caller needs admin on access:audit; a read grant on models is not enough.

`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 usage telemetry spool and does not require a repository. For what each entry contains, see Usage Telemetry Events.

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`