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

Goal	Command
List recent runs (all statuses, this project)	`archon workflow runs --json`
List across all projects	`archon workflow runs --all --json`
Filter by status / cap rows	`archon workflow runs --status running --limit 50 --json`
Show one run (status, error)	`archon workflow get <run-id> --json`
One run with per-node detail	`archon workflow get <run-id> --verbose --json`
Active runs only (running/paused)	`archon workflow status --json`
Start a run, non-blocking	`archon workflow run <workflow> "<message>" --detach`
Approve a paused gate	`archon workflow approve <run-id> "looks good" --json`
Accept & complete a loop gate with a completed condition	`archon workflow approve <run-id> --json` (NO comment)
Reject a paused gate	`archon workflow reject <run-id> "fix X first" --json`
Actively stop a running CLI `--detach` run	`archon workflow cancel <run-id> --json`
Mark a paused or verified-orphan run cancelled without stopping host work	`archon workflow abandon <run-id> --json`

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 a gate decision and don't need to drive the resulting cancel-or-rework path 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).

Interactive-loop gates: no comment = accept & complete

When a paused interactive loop gate met any declared completion condition (archon workflow get <run-id> --json → .metadata.approval.completionSignaled is true), approving with no comment accepts the completion — on resume the node finalizes from the already-computed output with no re-run. Approving with a comment runs another iteration using it as feedback. Read the gate state first, then choose deliberately:

archon workflow get <run-id> --json | jq .metadata.approval.completionSignaled
archon workflow approve <run-id> --json          # accept & complete (finalize, no re-run)
archon workflow approve <run-id> "redo X" --json # run another iteration with feedback

(In project-scoped chat, the manage_run tool's approve action mirrors this: no message — or accept: true — finalizes; a message iterates.)

Reference

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