Commands#

A command is one word, or two for the arena and category lifecycle: create, edit and remove. preferences --help prints every command, and preferences <command> --help prints one. Every command accepts --json and prints JSON to stdout with it. A removal is irreversible — it takes every category, item, pair, choice and ranking under it — so without --yes the service names what it would delete and removes nothing, and running a removal twice refuses the second time with not found. The site offers the same lifecycle through the same routes: /arenas creates an arena and /arenas/<id> edits it, adds, renames and removes its categories, and removes it after showing the counts the service answered with. The service decides who may: the operator bearer for everything, and a signed-in owner or admin of a private arena's organization for that arena; a public arena is the operator's alone.

An arena edit changes only the supplied fields at the database mutation. A concurrent rename cannot restore an older visibility or organization. Edits and confirmed removals return the row actually changed or deleted. If another request already removed it, the losing request receives not_found rather than a success receipt from an earlier read. The CLI and management screens share these responses. An unconfirmed removal changes nothing; its counts describe the state when that preview was requested.

Commands, as preferences --help lists them
Command	What it does
`onboarding [--reset]`	the first-run walkthrough, replayed on demand
`doctor`	check the deployment and this shell's environment
`arenas`	list arenas and their categories
`arena create --id --name [--visibility] [--organization]`	create an arena (operator)
`category create --arena --id --name --kind`	create a category, kind image\|text\|html (operator)
`arena edit --id [--name] [--visibility [--organization]]`	change an arena's name, visibility or organization (operator); the id never changes
`arena remove --id --yes`	remove an arena and everything under it (operator); without --yes it names what it would delete and removes nothing
`category edit --arena --id --name`	change a category's name (operator); its id and kind never change
`category remove --arena --id --yes`	remove a category and its items, pairs, choices and rankings (operator); without --yes it names what it would delete and removes nothing
`vote --arena --category [--count N]`	vote interactively: l, r, t (tie), s (skip)
`leaderboard --arena --category [--subject generator\|item]`	print the Bradley-Terry ranking
`profile [--arena --category]`	your voter record, or your taste profile in one category
`export --arena --category --format ster-pairs [--voter ID \| --all]`	write ster contrastive pairs to stdout: your own choices, one voter's with --voter, or the whole category's with --all (operator)
`submit --manifest FILE --arena --category --generator NAME`	upload a generator run (operator)
`import --file FILE`	retain preferences-import-v1 candidates, participants and choices
`rank --submission ID [--provisional]`	the winner of a submission (operator)
`hide --item ID`	hide one item from future pairs (operator)
`unhide --item ID`	put a hidden item back into pairs and the leaderboard (operator)
`recompute --arena --category`	rebuild the rankings of one category (operator)
`climb start --arena --category --name --seed FILE.html`	hill-climb a user interface in an html category from a seed, the first incumbent (arena manager)
`climb round --climb ID --variants DIR`	put a copy of the incumbent against every .html file in DIR, each named by its file name, for people to vote on (arena manager)
`climb advance --climb ID [--out FILE.html]`	decide the open round once the vote separated a leader: the winner becomes the incumbent, written to --out; not ready yet while the leader's interval overlaps another's (arena manager)
`climb show --climb ID`	one climb: its incumbent and every round; with a round open, each variant's score, 95% interval and whether a leader has separated (standing)
`climb list --arena --category`	the climbs of one html category
`climb history --climb ID --out DIR`	every incumbent the climb has had, the seed first, written to DIR as <position>-<round>-<variant>.html
`climb propose --climb ID --model MODEL --out DIR DIRECTION...`	write one variant of the incumbent per DIRECTION ("bolder headline") to DIR with a model through Brama, told what earlier rounds decided; nothing is uploaded until climb round reads DIR
`climb step --climb ID --model MODEL [--out FILE] DIRECTION...`	take a climb one step on, for a scheduler to run unattended: advance the open round once the vote separated a leader (exits 69 until then), then open the next with one proposed variant per DIRECTION

Environment and exit codes#

Every command exits 0 on success, 1 on a refusal or error, 2 on a wrong invocation such as an unknown command or a missing required flag, and 69 when the answer is not ready yet and the same command can succeed later. A refusal is a sentence the server wrote; the command line prints it on stderr word for word, so a script can match on it.

Variables the command line reads
Variable	Meaning
`PREFERENCES_URL`	deployment to talk to (required; no built-in deployment)
`PREFERENCES_TOKEN_ROLE`	ROLE#FIELD of the vault role holding the operator bearer, for the operator commands
`PREFERENCES_ACCOUNT_TOKEN_ROLE`	ROLE#FIELD of the vault role holding a Supabase JWT, to act as your account instead of the anonymous cookie
`STADO_BIN`	the stado executable the roles are read through (default: stado on PATH)
`PREFERENCES_CREDENTIALS_FILE`	without Stado: owner-only JSON file of role -> field -> value that answers both references
`BRAMA_URL`	the model gateway climb propose and climb step ask; without it, the address Stado's service directory published for this machine

Refusals#

Refusal sentences a script can match on
When	Sentence
`an operator command without PREFERENCES_TOKEN_ROLE`	operator bearer required
`an arena that does not exist`	arena "<id>" not found
`a category with one visible item or none`	category "<arena>/<id>" has fewer than two visible items
`the same run submitted twice`	submission for <generator> run <run> at <digest> already exists
`rank before the vote separates a winner`	submission <id> has <n> qualified comparisons; the leader's 95% interval still overlaps candidate <id>'s, so no winner is declared yet
`an anonymous voter who exports`	sign in to export your pairs
`export of an image or html category`	category "<arena>/<id>" holds <kind> items; ster pairs export needs text items