Manage Run

Manage Archon Runs

A focused skill for managing workflow runs through the archon CLI. It assumes Archon is already installed and you are working inside the project repo — the current directory scopes every command to that project automatically. For authoring workflows, setup, or config, use the broader `archon` skill instead.

Recent runs (live)

!archon workflow runs --limit 10 2>&1 || echo "Archon CLI not installed. (This skill needs the archon CLI on PATH.)"

How output works

• Add --json to any command for a single clean JSON object on stdout (logs are

suppressed automatically in --json mode). Prefer --json when you will parse the result.

• Without --json you get human-readable text. Diagnostics/warnings always go to stderr.
• The current directory (cwd) determines which project's runs you see. Run from the repo.

Verbs

There is no separate cancel verb — abandon cancels a non-terminal run by id.

Patterns

Monitor a run to completion

archon workflow runs --json                 # find the run id
archon workflow get <run-id> --json         # poll status: running | completed | failed | paused

A run is finished when status is completed, failed, or cancelled.

Start work without blocking

archon workflow run archon-assist "Investigate the flaky test" --detach
# returns immediately; the run then appears in `archon workflow runs`

--detach runs the workflow in a background child. The parent can't print the new run id (it's created in the child) — find it with archon workflow runs. If the run never appears, check the child log path printed by the command (or the logPath field in --detach --json).

Console UI note: a detached run appears in the web console's Workflow dock

(the dock lists runs by project) and updates live — even though it executes in a

separate process. A server-side poller tails the workflow-event table and replays new

rows to the console's live feed (on PostgreSQL a NOTIFY trigger pushes them within

the same second; on SQLite the poller picks them up on its short interval). No refresh

is needed.

Approve or reject a paused run (two steps)

--json approve/reject/resume record the decision (the run becomes resumable) but do not execute the workflow — execution streams output that would corrupt the JSON. So:

archon workflow approve <run-id> "ship it" --json   # records the approval (resumable: true)
archon workflow resume <run-id>                      # execute it — run this as a BACKGROUND task
archon workflow get <run-id> --json                  # poll until completed/failed

If you only need to record the decision (e.g. cancel via reject) and don't need to drive the run forward, the --json step alone is enough. To approve and continue in one blocking call, drop --json: archon workflow approve <run-id> "ship it" auto-resumes (run it as a background task).

Reference

For the full flag list and JSON shapes of each verb: read references/commands.md.

Manage-Run Command Reference

Every command runs through the archon CLI and is scoped to the current project by the working directory. Add --json for a single clean JSON object on stdout (logs are suppressed in --json mode); omit it for human-readable text. Diagnostics go to stderr either way.

---

Read

archon workflow runs [--all] [--status <s>] [--limit <n>] [--json]

Recent runs of all statuses for this project (complements status, which is active-only).

• --all — drop the project scope; list runs across every project.
• --status <s> — filter to one status: pending | running | completed | failed | cancelled | paused.
• --limit <n> — max rows (default 20).
• Unregistered cwd (or a codebase lookup failure): falls back to a global list and prints a (not a registered project — showing all runs) note (never a silent wrong scope). In --json this is the scopeFallback field — true means the result is global, not the project scope you asked for.

--json shape — the dashboard result:

{
  "runs": [
    { "id": "…", "workflow_name": "archon-assist", "status": "completed",
      "current_step_name": "review", "total_steps": 4, "started_at": "…",
      "codebase_name": "…", "working_path": "…" }
  ],
  "total": 87,
  "counts": { "all": 87, "running": 1, "completed": 70, "failed": 12,
              "cancelled": 3, "pending": 0, "paused": 1 },
  "scopeFallback": false
}

archon workflow get <run-id> [--verbose] [--json]

Detail for one run, any status.

• --verbose — also derive a per-node summary from the event log (and, in --json, attach the raw events array).
• --json emits the raw run object on success; on failure (not found, DB error) it emits one { "ok": false, "runId": "…", "error": "…" } line and never throws (error is "not_found" for a missing run).
• Exit code is non-zero when the run is not found (so archon workflow get <id> && … and CI checks react to a missing run); 0 on success.

{ "id": "…", "workflow_name": "archon-assist", "status": "failed",
  "working_path": "…", "started_at": "…", "completed_at": "…",
  "metadata": { "error": "Step failed: review" } }

With --verbose --json: { …run, "events": [ … ] }.

archon workflow status [--verbose] [--json]

Active runs only (running + paused). --json → { "runs": [ … ] }.

---

Start

archon workflow run <workflow> "<message>" --detach [--json]

Run a workflow in a detached background child; returns immediately.

• The parent pins a generated branch + conversation id on the child so exactly one

worktree/conversation is created. It cannot report the new run id (created in the child) — find it via archon workflow runs.

• Combine with the normal run flags (--branch, --no-worktree, --from, --resume).
• Child stdout/stderr are written to a per-conversation log file under

~/.archon/logs/; the path is printed (and is the logPath field in --json).

--detach --json shape:

{ "ok": true, "action": "run", "detached": true, "workflow": "archon-assist",
  "branch": "archon-assist-1780000000000", "conversationId": "cli-…",
  "logPath": "/Users/you/.archon/logs/detached-run-cli-….log" }

---

Control

These four accept --json. In `--json` mode they record/validate the decision and return — they do NOT execute the workflow inline (execution streams output that would corrupt the JSON). The error path always returns { "ok": false, "runId": …, "error": … } instead of throwing, so a parser always gets one JSON line.

archon workflow approve <run-id> [comment] [--json]

Approve a paused gate (approval node or interactive loop).

{ "ok": true, "runId": "…", "action": "approve",
  "type": "approval_gate", "workflowName": "…", "resumable": true }

Non---json: records the approval and auto-resumes (blocking — run as a background task).

archon workflow reject <run-id> [reason] [--json]

Reject a paused gate. cancelled: false means an on_reject rework pass is queued (run is resumable); cancelled: true ends the run.

{ "ok": true, "runId": "…", "action": "reject", "cancelled": false,
  "maxAttemptsReached": false, "workflowName": "…", "resumable": true }

archon workflow abandon <run-id> [--json]

Cancel a non-terminal run. (There is no separate cancel verb.)

{ "ok": true, "runId": "…", "action": "abandon", "status": "cancelled", "workflowName": "…" }

archon workflow resume <run-id> [--json]

Re-run a failed/paused run, skipping completed nodes.

• Without `--json`: executes (blocking — run as a background task), then poll with get.
• With `--json`: validates the run is resumable and returns executed: false **without

running** — to actually execute, use the blocking form (background) or run <name> --resume --detach.

{ "ok": true, "runId": "…", "action": "resume", "executed": false,
  "status": "failed", "workflowName": "…", "workingPath": "…" }

---

Continuation model (paused → done)

archon workflow approve <run-id> "ship it" --json   # 1. record decision (fast, parseable)
archon workflow resume  <run-id>                    # 2. execute — run as a BACKGROUND task
archon workflow get     <run-id> --json             # 3. poll until completed/failed/cancelled

Or, to approve and continue in one (blocking) call, drop --json from step 1 — it auto-resumes. A run is finished when status is completed, failed, or cancelled.