usage: cox runs [-h]
{usage,trace,clean,land,fetch,review,recover,series,wait,events,top,bar,notify,detail,stranded,cause,stop,pause,resume,move,triage} ...
What a harness run recorded, and cleaning up after it.
positional arguments:
{usage,trace,clean,land,fetch,review,recover,series,wait,events,top,bar,notify,detail,stranded,cause,stop,pause,resume,move,triage}
usage usage stats and cost for one run
trace the tool-call trace for one run
clean delete a run's worktree and branches locally
land merge a run's branch into the target repo
fetch pull an ended remote lane's run directory, log and
branches to this machine
review review a contributor PR with the review graph and post
the verdict
recover merge an approved task's commit into its phase branch
after an escalated merge
series per-run summary rows across a runs directory
wait block until a busy lane's run exits, then print its
outcome lines
events poll a run's log for structured events
top live table of busy lanes (runs in flight); --once
prints it and exits
bar one Waybar JSON line: busy lanes, cost, class
idle|running|attention
notify desktop notifications for exits, quarantines, budget
stops and cost
detail one run's timeline, objection and last tool calls
stranded every approved task record whose work item is not
done, with its remedy
cause record why one run's attempt at a task was quarantined
stop stop a run's process, local or remote, and wait for it
to exit
pause mark a run paused in the store
resume mark a paused run resumed in the store
move stop a run at its node boundary and relaunch it on
another host
triage print a quarantined task's facts; reads the store and
git only, makes no model call
options:
-h, --help show this help message and exit
examples:
cox runs fetch <run>
cox runs land <run> --repo PATH --apply
cox runs recover <run> <task> --repo PATH
cox runs usage <run> --json
cox runs detail <run> --json
usage
usage: cox runs usage [-h] [--runs-dir RUNS_DIR] [--json] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--runs-dir RUNS_DIR
--json
trace
usage: cox runs trace [-h] [--runs-dir RUNS_DIR] [--role ROLE] [-v] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--runs-dir RUNS_DIR
--role ROLE
-v, --verbose
clean
usage: cox runs clean [-h] --repo REPO [--worktree-root WORKTREE_ROOT]
[--runs-dir RUNS_DIR] [--profile PROFILE] [--apply]
[--force]
run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--repo REPO
--worktree-root WORKTREE_ROOT
--runs-dir RUNS_DIR override: resolve task records here instead of the
profile's workspace_dir
--profile PROFILE
--apply
--force delete every branch regardless of whether its task is
on main
land
usage: cox runs land [-h] --repo REPO [--task TASK] [--phase PHASE]
[--label LABEL] [--force] [--no-claim]
[--worktree-root WORKTREE_ROOT] [--apply] [--no-merge]
[--runs-dir RUNS_DIR] [--profile PROFILE]
[--gate {ticket,phase,epic,full}]
run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--repo REPO
--task TASK
--phase PHASE land the whole phase off its own epic branch instead
of one task
--label LABEL
--force land despite a foreign live leader
--no-claim land without taking an unheld or stale loop
--worktree-root WORKTREE_ROOT
--apply
--no-merge
--runs-dir RUNS_DIR override: resolve task records here instead of the
profile's workspace_dir
--profile PROFILE
--gate {ticket,phase,epic,full}
override the resolved gate level for this invocation
fetch
usage: cox runs fetch [-h] [--runs-dir RUNS_DIR] [--profile PROFILE] [--all]
[run_id]
positional arguments:
run_id
options:
-h, --help show this help message and exit
--runs-dir RUNS_DIR override: resolve the run's records here instead of the
profile's workspace_dir
--profile PROFILE
--all fetch every remote run with no local tasks directory
yet; a live run is skipped
review
usage: cox runs review [-h] --pr PR [--profile PROFILE]
options:
-h, --help show this help message and exit
--pr PR https://github.com/<owner>/<repo>/pull/<n>
--profile PROFILE
recover
usage: cox runs recover [-h] --repo REPO [--runs-dir RUNS_DIR]
[--profile PROFILE] [--dry-run]
run_id task_id
positional arguments:
run_id
task_id
options:
-h, --help show this help message and exit
--repo REPO
--runs-dir RUNS_DIR override: resolve task records here instead of the
profile's workspace_dir
--profile PROFILE
--dry-run print the merge that would be made and exit without
touching anything
series
usage: cox runs series [-h] [--runs-dir RUNS_DIR] [--json] [--append APPEND]
options:
-h, --help show this help message and exit
--runs-dir RUNS_DIR
--json
--append APPEND
wait
usage: cox runs wait [-h] [--runs-dir RUNS_DIR] [--max-seconds MAX_SECONDS]
[--interval INTERVAL] [--json]
options:
-h, --help show this help message and exit
--runs-dir RUNS_DIR
--max-seconds MAX_SECONDS
--interval INTERVAL
--json
events
usage: cox runs events [-h] [--runs-dir RUNS_DIR] [--follow] [--json]
options:
-h, --help show this help message and exit
--runs-dir RUNS_DIR
--follow
--json
top
usage: cox runs top [-h] [--runs-dir RUNS_DIR] [--interval INTERVAL] [--once]
options:
-h, --help show this help message and exit
--runs-dir RUNS_DIR
--interval INTERVAL
--once
bar
usage: cox runs bar [-h] [--runs-dir RUNS_DIR]
options:
-h, --help show this help message and exit
--runs-dir RUNS_DIR
notify
usage: cox runs notify [-h] [--runs-dir RUNS_DIR] [--once]
[--interval INTERVAL] [--replay]
options:
-h, --help show this help message and exit
--runs-dir RUNS_DIR
--once
--interval INTERVAL
--replay emit history on first start; default is silent for
existing runs when no state file is present
detail
usage: cox runs detail [-h] [--runs-dir RUNS_DIR] [--json] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--runs-dir RUNS_DIR
--json
stranded
usage: cox runs stranded [-h] [--runs-dir RUNS_DIR] [--profile PROFILE]
[--json]
options:
-h, --help show this help message and exit
--runs-dir RUNS_DIR override: resolve task records here instead of the
profile's workspace_dir
--profile PROFILE
--json
cause
usage: cox runs cause [-h] [--note NOTE] [--runs-dir RUNS_DIR]
[--profile PROFILE]
run_id task_id {ticket,code,harness,unknown}
positional arguments:
run_id
task_id
{ticket,code,harness,unknown}
options:
-h, --help show this help message and exit
--note NOTE free text kept beside the cause
--runs-dir RUNS_DIR override: resolve task records here instead of the
profile's workspace_dir
--profile PROFILE
stop
usage: cox runs stop [-h] [--runs-dir RUNS_DIR] [--profile PROFILE] [--json]
run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--runs-dir RUNS_DIR
--profile PROFILE
--json
pause
usage: cox runs pause [-h] [--reason REASON] [--runs-dir RUNS_DIR] [--json]
run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--reason REASON
--runs-dir RUNS_DIR
--json
resume
usage: cox runs resume [-h] [--runs-dir RUNS_DIR] [--json] run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--runs-dir RUNS_DIR
--json
move
usage: cox runs move [-h] --to TO [--reason REASON] [--runs-dir RUNS_DIR]
[--profile PROFILE] [--json]
run_id
positional arguments:
run_id
options:
-h, --help show this help message and exit
--to TO
--reason REASON
--runs-dir RUNS_DIR
--profile PROFILE
--json
triage
usage: cox runs triage [-h] [--json] [--profile PROFILE] [--repo PATH] task_id
positional arguments:
task_id
options:
-h, --help show this help message and exit
--json
--profile PROFILE the routing profile (default: ~/.config/agent-
tools/profile.yaml or $AGENT_TOOLS_PROFILE)
--repo PATH the task's git repository (default: the current
directory)