The staros CLI, as the house uses it
The command pages this index names, one per command, are the repo’s (docs/cli/<command>.md); the site carries the guide and the index. The text is docs/cli/’s, copied by tools/reference_pages.py and held equal.
Hand-written (2026-10-20); the reference beside it (index.md, one page per command) is generated from
the binary and names what each flag does. This page says what we actually type, day to day, and where the deeper doc
is. Every command line here exists in the reference (scripts/test_staros_ref.py checks). staros is clap: staros <cmd> --help is the long form, -h the short one; staros alone prints the list.
Two rules first. Prefix shell commands with rtk (rtk git …, rtk cargo …; staros prehook refuses a bare
one with the rewrite). A Claude session’s HOME is routed (~/.claude_host/accounts/<slot>): anything that reads a
machine-wide path (~/.staros/…, the keep, the bridge’s token) must see the real home — the Rust side uses
claude_host::platform::real_home_dir(), Lua shared.platform.real_home(); from a shell, export HOME=/Users/<you>
(or USERPROFILE='C:\Users\User' HOME=/c/Users/User on the tower) before a staros command that writes there.
1. A session’s claim: tasks
A development session claims its work before it starts, on a lease both machines see; an unanswered “who takes X?” means nobody starts X (the root CLAUDE.md’s ruling of 10-05).
staros tasks intend --new <project> "<title>" --note "dev session on the M2; log docs/working-<program>.md"
staros tasks intend --release <project>/<slug>
staros tasks intend <project>/<slug> --hours 8 --note "the angle" # an existing task
The lease rides the task file (~/.staros/tasks/<project>/<slug>.task.md, intent_host / intent_until) and dies by
expiry, --release or done. The task is a terminal too:
staros tasks term <project>/<slug> --host m2 --session task/<project>/<slug> # bind it (the agent's home does this on creation)
staros tasks snapshot # ~/.staros/hub/tasks.json, what this host holds
staros tasks handoff <project>/<slug> --to tower # MOVES it (write remote → read back → delete local)
staros tasks ls --project <project>
staros tasks show --project <project> --slug <slug>
staros tasks board # the TUI kanban
handoff deletes the local copy only after the far side confirms, so a failed transport keeps it. intend and
handoff take project/slug; show takes --project X --slug Y. A tasks note (a line under a task’s
## Activity) is in startune’s design and not in the binary yet: startune’s DAW appends the line itself
(daw/tasks.lua), everyone else edits the file. The deeper docs: docs/m2-tower-sync-protocol
(memory), starplot/docs/delegation.md for the queue.
Who runs a task (2026-10-31). A task’s runner says which dispatcher takes it: sub, the default, is a
subscription agent staros fill tick takes from queued; credit is a credit agent through the credits lane, on its
own branch (section 9); session is you, and no dispatcher takes it.
staros tasks assign <project>/<slug> --runner credit --max-usd 2 # a request in the lane's mailbox at once; it waits for a fill window
staros tasks assign <project>/<slug> --runner credit --when now # spends now (at most $3)
staros tasks assign <project>/<slug> --runner session
staros tasks add <project> "<title>" --runner credit # assign's defaults: the window, $2, sonnet
staros tasks sync-credit # each credit task follows its request
A credit task follows its request: running, review while its branch waits for staros credits review, done when the
branch lands, blocked with the error, backlog when cancelled or discarded. The lane syncs the tower’s board after each
change; from the M2 the request forwards to the tower, and the push script syncs after each pull. An open request
refuses a reassignment until staros credits request cancel <id>. tasks ls and the board mark the runner ($cr,
@me).
The lease names the session (buildfleet P2, 2026-10-30). Run from a Claude session, or any agent that sets
STAROS_SESSION_ID, intend records the session beside the host: intent_session, intent_account, intent_pid,
intent_proc_start and intent_name. The same session renews its own lease. Another LIVE session on the same host is
refused (--steal overrides, with an audit line in the task’s body). A session that has ended is taken over with an
audit line, no --steal needed. Over ssh, --host is required. The board shows the holder as ⚑tower·<session name>.
Slots: who is building, on the GPU, or driving a console
staros slot run build:engine --task <project>/<slug> -- cargo build --release # hold build:engine for the command's life
staros slot ls # who holds what, for which task
staros slot history gpu -n 10 # finished holds, the contended ones marked
A slot never blocks (the operator’s ruling): a second taker is told who holds it and runs anyway. The scripts take
them for you: check.py holds gpu for its run, build-sim.sh holds build:<lane>, the battery holds
console:<n> and gpu and takes the first free console instance from 7 up, and ab.py stamps an A/B that overlapped
another holder contended. A killed slot run takes its command’s children with it (Windows) unless
--keep-children. The board shows a task’s holds beside its lease ([build:engine 12m]). The programme:
docs/working-buildfleet-2026-10.md.
2. Running an agent
staros run -- <claude args> # the router picks an account, swaps HOME, execs claude
staros run --account max-b -- # pin one
staros spawn --kind reviewer "…" # an agent via the router
staros router --explain 5 # replay the last routing decisions
staros accounts list
staros accounts doctor
staros accounts sync-settings # the per-account settings.json after a hook change
staros delegate "<task>" --repo <dir> --to or|claude|auto
staros resume # a resumable session across accounts × projects
run is what the agent’s home types into a task’s terminal (love-shared/agents/launchers.lua, the claude
launcher). delegate --to or runs a cheap OpenRouter model in an isolated worktree with --verify-cmd and a cost
cap; --to claude spawns Opus from excess quota (starplot/docs/delegation.md). The quota side: usage, fill status, calibrate report, gain --since 7d (where tokens went).
3. The daemon and the services
Nothing auto-starts after a reboot: a quiet fleet is the expected post-boot state.
staros daemon status
staros daemon ensure # start it if it is not up (holds the ssh stdio open over ssh: check status separately)
staros daemon services list
staros daemon services start staros.term-bridge
staros daemon services stop staros.term-bridge # the term bridge's sessions survive this (kill_tree = false)
staros daemon services logs staros.term-bridge
staros daemon services restart <project>.<service>
A missing daemon.lock beside a live daemon was the duplicate-daemon loop (starplot 95fed0d); 0x800710E0 on a
scheduled task is MultipleInstances=IgnoreNew, not permissions. services.toml is the manifest; the launcher’s
services page polls the same daemon. Docs: starplot/docs/hook-and-watchdog.md, the root CLAUDE.md’s fleet rules.
4. Reading code, and the hooks
staros sym ls <file> # the symbols of a file over ~200 lines
staros sym read <file> <symbol> # one function, not the file
staros sym map <dir> --budget 1000 # orient in a repo
staros sym find <name>
staros check # the project's Claude Code setup, fixed where it can be
staros hook prehook status # the rtk enforcement, per routed account (never conclude it is off from a settings.json an agent does not read)
staros hook status
The wsl prohibition lives in prehook and sees through bash -c, ssh <host> '…' and heredocs: starting WSL on
the tower took it off its own LAN (2026-08-20). sym is the AST read (starplot/docs/staros-cli.md is the older
guide to check and usage).
5. The apps from outside
An app’s actions are verbs (love-shared/docs/app-verbs.md): scripts/staros-tap.py <app> verbs | state | verb <name> '<json>' | activity --since N over its tap (the port in ~/.staros/ports.json), and the pages love-shared/docs/ verbs/<app>.md. For an agent outside the house:
staros mcp serve # the MCP adapter: screenshots, the launcher's tap, the services, the keep's names,
# the stories, and (a proposal) staros_app_verbs / staros_app_verb
staros open <project> --claude # a terminal at a registered project, a Claude session in it
staros launch <project> # tell the running desk to launch or focus an app
The carts: staros cart log/refs/verify (a cartridge’s record), staros ship/pull (a channel), staros pack
(a LÖVE game for distribution), staros export-app (an app as a standalone repo the cloud builder clones),
staros bootstrap (the shared/ link an app needs per box). The program’s docs: docs/working-cartridges-2026-10.md.
6. The web and the sites
staros web build <site> # a star-web site from its site.toml
staros web serve <site>
staros web check <dist> --a11y # self-contained + embed policy + a11y + invisible chars
staros web check <dist> --links --outside examples # every inside link names a file and an id (2026-11-11);
# --outside: a folder another publisher owns on the same host
staros web sitemap <dist> --site <site> # sitemap.xml + robots.txt over the FINISHED dist, after the last generator
staros web diff <site>
staros web deploy <site> # a dry run; --execute is the operator's (ruling 30)
staros web adapt # a studies draft adapted into a site's page (codylee.ca)
The bench’s make site and the platform’s build wrap these. The words on a site are drafts for the operator.
A site’s [site] table switches the foundations on (each absent = the output before): head_meta (a themed page’s
canonical URL and share tags, with the site’s image), md_twins (each markdown page’s source beside it, where it
sits under content/, named in its head; the twin drops a comment and a <style> block that open a line and keeps
fenced code as written, and a page that is HTML in a markdown file says twin = false), feed / feed_title (another generator’s feed named from every page),
skip_link (a themed page opens with a link to its <main id=main>), sitemap (the build writes the sitemap
itself: for a site no other generator adds to), sitemap_exclude, and search (staros web sitemap <dist> also
writes search-index.json: the sitemap’s own pages as what their reader can see, cut at the headings that can be
linked to, for the site’s own search to read; --search asks for it without the key).
Releasing s2ar.dev is one command (2026-11-12; starlens/site/tools/release.sh, from the tower’s Git Bash):
bash starlens/site/tools/release.sh # the plan: what is live, what each step would do and why; changes nothing
bash starlens/site/tools/release.sh go # the steps still needed, in order (--apps / --work ship what is held back)
bash starlens/site/tools/release.sh dry # the publish's dry run on the M2 as it stands; nothing published
bash starlens/site/tools/release.sh check # the live site from outside (--browser adds the browser tests)
The steps are build (the clean staros, when the masters moved), install (it, on the tower), bridge (the masters
merged on the M2 and its staros rebuilt, since the M2 builds the site) and publish (the dry run in a scratch
worktree of master’s commit, the live site backed up on work1, the dist the dry run checked shipped as it is, the
site checked from outside, the release on record). Each runs only when the plan says it is needed, so a run that
stopped is run again; --only a,b and --skip a,b narrow it. A publish is the operator’s (ruling 30): a session
runs go only at her word. What is live at any time: python3 starlens/site/tools/release_record.py --status.
Since 2026-11-12 a publish is a release: work1’s receiver (ops-site) unpacks the checked dist whole and makes it
live by a link, five kept. release.sh rollback puts the one before back (and checks it from outside),
release.sh releases lists them, release.sh backups lists the old tarballs. The ops plan’s on-box deploys have
the same shape: bash ops/bin/apply.sh plans them from the boxes, and bash ops/bin/apply.sh <stage> go runs the
steps not done (ops/README.md).
7. Secrets, the vault and the keeps
STAROS_KEEP_DIR=~/.staros/keep staros secret get <name> # (`keep` is the alias) — never print a value into a transcript
staros secret ls
staros vault status
staros vault peers
staros repo status # starkeep: content-addressed, mergeable, LF-normalized
staros sync status # every keep in the grove roster, in doctrine order
staros conflict list
Services take credentials by name through staros.toml (credentials = [...]); Lua reads shared.secrets. The vault
sidecar (127.0.0.1:13152) can accept TCP and never answer: anything reading it degrades silently. Docs:
docs/file-distribution.md, docs/sync-and-conflict-design.md, docs/staros-mesh.md.
8. The studies, the press and the stories
staros study serveserves the studies READER over the dev plane. The server asks for a token and never writes to the repo. A client with no Python can callGET /study/verify?witness=<id>&span=<text>, which answers with concord’s verdict object (studiesshared/docs/study-json.md). The reader’s token opens that call, and so does a device token with thepiecescope.staros study run <tool> [args]runs any studies tool with the house’s interpreter and passes the tool’s exit code through (staros study run list --kit;staros study run concord --project <studies>/atlas --witness <id> verify "<span>" --json). The study package’s log isdocs/working-study-package-2026-10.md.staros press foldfolds the studies repo into the hub’s snapshots.press serveserves them on loopback and refolds on change.press take-uptakes up a work and opens a reading intent. The intents are an append-only op log at~/.staros/study-queue.ndjson.staros lore add/lint/graphworks on StarLore notes and spaced repetition (starlore/docs/integrations.md).staros branch lint/validatechecks StarBranch dialogue trees.staros story renderandstaros saga queueare the short-form exporter and the content queue (starplot/docs/story-exporter.md). Posting is the operator’s.staros latex buildandstaros arxiv endorsersare the preprint tooling.
9. The API credit
Each Max plan links one Console org with $200 of API credit a cycle, and it expires with the cycle (no rollover): two
wallets, max-b and max-c, $400 a month. Claude Code itself never runs on it (the keys stay out of its spawns); the
lane spends through its own door, and only the tower spends (docs/api-credits.md).
staros credits status # each wallet: left, cycle end, pace, spend by job (--json; --refresh on the tower)
The same figures sit in the statusline’s dimmed api:$<left> ⟲<expiry> (? = stale, api:dry = every wallet out), in
the dashboard’s Accounts room (ctrl+4), and on the study reader’s /credits page, which also has the request form.
staros credits ask "review this" # one metered answer; a prompt on stdin works too
staros credits agent "<task>" --max-usd 2 # a credit agent in a fresh worktree, under a dollar cap
staros credits agent "<task>" --on m2 # the same, run on the M2's clone
staros credits run memory-lint # a job by hand (commit-review is off since 10-31: no credit on git hygiene)
A board task goes on the credit with staros tasks assign <project>/<slug> --runner credit (section 1). A request from
another machine or the phone goes to the tower’s mailbox, capped at $3 a request and $15 a day across
them; a verify command is refused there. Spend it: unspent credit is lost at the cycle’s end.
The fill list is the work you choose for a cycle’s last days: an item waits until a wallet’s fill window opens (its
last three days, the end confirmed on the Console), then runs as a credit agent, one at a time, each up to $5. (Not
staros fill, the subscription pacer: that one spends the plans’ weekly quota before it resets, this one the API
credit before it expires.)
staros credits fill add "<task>" --repo-name starplot --title "short name"
staros credits fill add --from-task staros/<slug> --repo-name starplot # a board task's title and body
staros credits fill plan # each wallet's window, what would expire, what the list holds
staros credits fill rm <id>
Each verb’s own flags are in credits-engine.md.
An agent’s work lands on a credits-agent/<stamp>-<slug> branch under ~/.staros/credits/worktrees/, and stays
there until you decide. A branch goes by its name, a part of it, or #N; merge, discard and prune are dry runs until
--yes:
staros credits review # every branch waiting: repo, first commit, diffstat, cost, who asked
staros credits review show "#1" # its commits and diff
staros credits review merge "#1" --yes # land it on the repo's checked-out branch, then drop the branch
staros credits review discard "#2" --yes
A merge commits on a private index, so another session’s staged files stay out of it; it refuses a file someone has
uncommitted changes in, and a branch HEAD has moved past. The agent’s message is kept, signed Assisted-by:.
A subscription agent’s branch waits in the same list (since 10-31): the pacer runs a sub task on
fill-agent/<stamp>-<slug> in a worktree beside its repo (<repo>.wt-… in the monorepo root), never in your
checkout. Its line shows sub where a credit branch shows its cost. Merging it then runs the task’s acceptance check
on the tree (staros tasks landed <project>/<slug> --branch <b>): done when it passes, blocked with its words when
not. Discarding it sends the task back to backlog.
staros credits request cancel <id> # drop a queued request, or stop a running one (its reserve settled as lost)
staros credits pause --reason=testing # the brake: nothing spends on its own until `staros credits resume`
A job’s findings come back as a report, ~/.staros/credits/out/<job>/ (commit-review’s digest lists any
credential-shaped string first). Nothing is posted anywhere.
What the older docs still get wrong
starplot/cli/CLAUDE.md’s table documents transcripts list|archive|restore, which the binary lacks, and lists
sym ls|read|map without find, chunks, index, where; daemon without install/uninstall; and the crate layout
from before the 2026-07 workspace split (accounts.rs, check/, daemon/ are in the domain crates now).
starplot/docs/staros-cli.md (08-17) covers check and usage and marks its own file layout stale.
starplot/docs/rust-architecture.md names the old topology. The reference beside this page is the current word on
each command; the richer help text those pages would read from is a proposal for starplot (the crate is unassigned).
The work on this page: the checks that hold it
- FAIL
lint/web-reference - PASS
lint/staros-ref
Generated by tools/reference_pages.py from docs/cli/guide.md; the twin bfaad079a7ce (434093 bytes). The words are a draft.