Skip to main content

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 How Swamp Works.

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
running    method  command/shell/execute  cc665a58  3s   18669  Mac.localdomain
completed  method  command/shell/execute  3760deda  25s  18783  Mac.localdomain
cancelled  method  command/shell/execute  cc665a58  39s  18669  Mac.localdomain

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
    }
  ]
}

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

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 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.

swamp telemetry stats
Flag Default Description
--repo-dir <dir> . Repository directory (env: SWAMP_REPO_DIR)
--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.

← PreviousWebhooksNext →Issue Commands