usage: cox chair [-h]
{run,service,ask,attach,answer,decisions,watchdog,freeze-lands} ...
The chair loop that runs the landing and launch ticks itself.
positional arguments:
{run,service,ask,attach,answer,decisions,watchdog,freeze-lands}
run beat, gather, plan, perform and report every tick
until interrupted
service write or show the systemd user unit that keeps `cox
chair run` alive
ask put a question with its options to the operator on the
courier bus
attach say whether a live chair loop holds the lease; exit 0
if so, 1 if not
answer answer an open decision with one of its options
decisions list decisions asked of the operator and their answers
watchdog one-shot loop check for a five-minute timer; reads
only the store
freeze-lands hold every land for a release cut, show the freeze, or
lift it
options:
-h, --help show this help message and exit
examples:
cox chair run --once --dry-run
cox chair run --interval 30
cox chair service --install
cox chair ask "ship it?" --option yes --option no
run
usage: cox chair run [-h] [--once] [--interval INTERVAL] [--dry-run]
[--max-overruns MAX_OVERRUNS] [--label LABEL]
[--profile PROFILE]
Each tick beats the chair lease, gathers facts, plans, performs and reports one status line.
It yields to `cox route chair take --steal`: actions planned under a lost lease are fenced.
It hard-stops at the profile's weekly_hard_stop_fraction of the weekly ceiling.
options:
-h, --help show this help message and exit
--once run one tick, release the lease, exit 1 if the tick
errored
--interval INTERVAL seconds between ticks (default: 60)
--dry-run plan and report each tick without taking the lease or
performing any action
--max-overruns MAX_OVERRUNS
exit 3 after this many facts-stage overruns in a row
(default: 3; 0 disables)
--label LABEL the chair's holder label (default: $COX_SESSION_LABEL,
else unlabeled)
--profile PROFILE the routing profile (default: ~/.config/agent-
tools/profile.yaml or $AGENT_TOOLS_PROFILE)
service
usage: cox chair service [-h] [--install] [--status] [--label LABEL]
[--interval INTERVAL]
[--environment-file ENVIRONMENT_FILE]
[--profile PROFILE] [--host HOST] [--apply]
--install writes ~/.config/systemd/user/coxswain-chair.service and prints the systemctl lines.
It does not run systemctl.
options:
-h, --help show this help message and exit
--install write the unit file and print the systemctl lines to
run; runs nothing itself
--status print the unit file, or say there is none
--label LABEL the chair's holder label (default: $COX_SESSION_LABEL,
else unlabeled)
--interval INTERVAL seconds between ticks (default: 60)
--environment-file ENVIRONMENT_FILE
env file the unit loads (default: ~/.config/agent-
tools/garage.env when it exists)
--profile PROFILE the routing profile naming workspace_dir, pinned in
the unit's ExecStart (default: ~/.config/agent-
tools/profile.yaml or $AGENT_TOOLS_PROFILE)
--host HOST a hosts-table name: install or report on that lane
host over ssh
--apply with --install --host, run the steps instead of
printing them
ask
usage: cox chair ask [-h] [--option OPTION] [--context CONTEXT]
[--label LABEL] [--profile PROFILE]
question
positional arguments:
question
options:
-h, --help show this help message and exit
--option OPTION an answer the operator may give; repeat for each, at
least two
--context CONTEXT text or a URL that helps the operator decide
--label LABEL the chair's label (default: $COX_SESSION_LABEL, else
unlabeled)
--profile PROFILE
attach
usage: cox chair attach [-h] [--profile PROFILE]
Reads the chair lease and the loop's last tick.
It never takes, steals, releases or writes the lease.
options:
-h, --help show this help message and exit
--profile PROFILE the routing profile (default: ~/.config/agent-
tools/profile.yaml or $AGENT_TOOLS_PROFILE)
answer
usage: cox chair answer [-h] [--profile PROFILE] id option
positional arguments:
id
option
options:
-h, --help show this help message and exit
--profile PROFILE
decisions
usage: cox chair decisions [-h] [--open | --answered] [--json]
[--profile PROFILE]
options:
-h, --help show this help message and exit
--open only decisions without an answer
--answered only decisions with an answer
--json
--profile PROFILE
watchdog
usage: cox chair watchdog [-h] [--idle-minutes IDLE_MINUTES]
[--stale-minutes STALE_MINUTES] [--dry-run]
[--profile PROFILE] [--install | --uninstall]
[--interval-minutes INTERVAL_MINUTES]
A one-shot check meant for a five-minute timer.
It reads only the store and exits 0 whether or not it pushed.
It exits 1 only when the store cannot be read.
--install and --uninstall only write or remove files: no check runs and no launchd or systemd tool does.
options:
-h, --help show this help message and exit
--idle-minutes IDLE_MINUTES
minutes of idle status lines before an alert (default:
30)
--stale-minutes STALE_MINUTES
minutes without a lease beat before the loop is down
(default: 10)
--dry-run print each alert and push nothing
--profile PROFILE the routing profile (default: ~/.config/agent-
tools/profile.yaml or $AGENT_TOOLS_PROFILE)
--install write the timer files and print the lines that
activate them; runs nothing itself
--uninstall remove the timer files this platform's install wrote
--interval-minutes INTERVAL_MINUTES
minutes between checks in the installed timer
(default: 5)
freeze-lands
usage: cox chair freeze-lands [-h] [--for MINUTES] [--reason TEXT] [--off]
[--profile PROFILE]
With --for and --reason, freeze lands until the minutes pass.
With --off, lift the freeze.
With neither, show whether lands are frozen.
A freeze that outlives its minutes lifts itself.
options:
-h, --help show this help message and exit
--for MINUTES minutes the freeze lasts; needs --reason
--reason TEXT why lands are frozen; needs --for
--off lift the freeze now; not with --for or --reason
--profile PROFILE the routing profile (default: ~/.config/agent-
tools/profile.yaml or $AGENT_TOOLS_PROFILE)