The staros CLI, command by command
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.
C:\Users\User\.cargo\bin\staros.exe (staros 0.1.0), built 2026-11-11 21:49 UTC, read on DESKTOP-V18RQRK. 78 top-level commands, 345 nested. Generated by scripts/staros-ref.py from staros --help; the fleet row lint/staros-ref fails when a page drifts from the binary on the box that runs it. The guide is the house’s usage, hand-written.
Accounts, routing and the quotas
| command | nested | what it does |
|---|---|---|
accounts |
6 | Account management subcommands |
spawn |
0 | Spawn an agent via the smart router |
run |
0 | Smart-route a bare claude invocation |
real |
0 | Run a command with the un-routed (pre-routing) profile environment |
router |
0 | Print the current router status (chains, headroom, quarantine). With --explain N, replay the last N persisted routing decisions from ~/.claude_host/state/router-decisions.ndjson instead |
resume |
0 | Pick a resumable Claude Code session across all accounts × all projects |
delegate |
0 | Delegate a task from a planning session: –to or (cheap OpenRouter model, isolated patch out) | claude (opus spawn, excess quota) | auto (by weight: heavy→claude, light→or). –queue defers to the fill pacer via the kanban |
route |
0 | Routing economics: effective (opportunity) cost of each subscription bucket vs OpenRouter, with per-lane recommendations (plan/heavy/ light). Subscription tokens that would expire unused are ~free; scarce buckets approach the displaced alternative’s price |
usage |
0 | Show token usage against API limits |
credits |
19 | The API-credits lane: the wallets, credit agents, the mailbox, the hourly tick |
calibrate |
5 | Calibrate internal caps / peak multiplier against Anthropic /usage |
throttle |
2 | Throttle measurement surface: is telemetry flowing (status), and what did the limiters actually do (report — utilization, request pressure, cache behavior, classified limit events, identity) |
fill |
9 | Reset-aware quota-fill pacer: consume each account’s weekly Max quota toward ~99% before its reset (the inverse of overnight). Per-account, spreads across accounts, autoheals off rate-limits. tick / status / consent / sync / seed |
overnight |
3 | Autonomous overnight runner: tick / status / consent toggle. Mirrors the in-dashboard dispatcher in starplot/dashboard/core/overnight_dispatcher.lua. Wire to cron / launchd / Windows Task Scheduler for headless dispatch |
gain |
0 | Token-flow analytics: attribute spend per tool / command head, surface waste, track rtk adoption. Our replacement for rtk gain |
hygiene |
1 | Invisible-marker encounter log: which capture points are still running (report panel A — the reason this exists), what is open, and stream volume. Findings are near-zero by design; coverage is the signal |
bench |
4 | Inspect the staros bench NDJSON stream — span p50/p95, per-PID CPU/RSS, regression diffs. Bench data is written to ~/.claude_host/state/bench.ndjson by any process that links the staros_bench crate (today: the daemon; soon: the agent and dashboard). The stream is size-capped at the append seam (staros_bench::MAX_BENCH_BYTES, 64 MB): past the cap the live file rotates to bench.ndjson.1 (one prior generation kept), so tail-readers only ever pay for a bounded file. Read-only — never starts producers |
fleet |
2 | Fleet presence bot. fleet bot [--once] heartbeats this host into the realtime DB (claude:<host>, server culls at 90s) and materializes ~/.staros/fleet/presence.json for the Observatory machine strip; fleet status prints the live presence table. Every pass appends an ok/err+latency row to fleet-bot.ndjson (honesty log) |
notify |
2 | Fleet push notifications over ntfy. notify test [--title T] [--body B] posts one message to the staros-fleet topic through the same notify::push the loop’s INFRA breaker and fill doctor use — so the wire can be proven from any shell |
Tasks, the daemon and the hooks
| command | nested | what it does |
|---|---|---|
tasks |
19 | Kanban task management — ls / add / queue / cancel. Reads + writes ~/.staros/tasks/ |
work |
6 | The work fold: ~/.staros/hub/work.json (the chronicle’s one source: tasks, sessions, programmes, commits, the plan) and programme.json (schema 1, the Observatory’s) from one model — fold / lint / serve |
task |
7 | One-shot / detached JOBS (R9): run a program NOW through the daemon (survives session churn, windowless, audit-logged), schedule one-shots, or register real Windows scheduled tasks via the windowless staros-taskrun shim. (Distinct from staros tasks, the kanban task-file manager.) |
slot |
3 | Advisory slots: who is building, holding the GPU, or driving a console (run / ls / history). A slot never blocks: a second taker is told who holds it and runs anyway (buildfleet P1) |
daemon |
7 | Long-running headless background service. Hosts the CC PostToolUse hook HTTP listener (replaces the popup-flashing python3 hook). Future home for routing audit log writer, drift checker, and (eventually) the orchestrator’s ECS state — once decoupled from orchestrator.dll so agent state survives dashboard restarts |
calendar |
4 | Calendar / scheduler: schedule recurring jobs (incl. autonomous staros spawn agent runs), list the agenda, fire an event now, or remove one. Talks to the running daemon’s /calendar/* API (staros daemon ensure) |
watchdog |
5 | Per-training-run pod watchdog. Wraps Windows Task Scheduler — each register creates a startrade-watchdog-<run_id> task that ticks every 60s. The tick polls the pod via SSH, mirrors logs, and writes status.json. See ~/.startrade/watchdog-tick.sh for the poll-cycle implementation |
pod-monitor |
0 | Watchdog: poll a Verda/RunPod training pod, alert on stalls + OOM + idle |
hook |
8 | PostToolUse hook handler + on/off control. |
prehook |
0 | PreToolUse hook handler: enforce rtk prefix on Bash calls. |
fmthook |
0 | PostToolUse hook handler: auto-format just-edited files. |
check |
0 | Check and fix project Claude Code setup |
ops |
5 | The fleet’s signed ops (the desk’s part three): ops issue --to tower --kind service.restart --service staros-search --reason … signs an op the vault carries to that host; ops apply --once applies the ones addressed here (verified against fleet/hosts’ keys, once only, a receipt each); ops list, ops verify <file>, ops whoami. See docs/ops.md |
The apps from outside: taps, carts, builds
| command | nested | what it does |
|---|---|---|
mcp |
1 | MCP server (staros mcp serve) — north-facing adapter exposing cli_driver / staros-super / staros-keep surfaces to external agents |
open |
0 | Open a WezTerm window at a registered project’s root. With --claude, drops straight into a Claude Code session there. CLI parity with stardash’s “Open Terminal” / “Attach Claude” buttons; project name resolved via ~/.staros/projects.toml |
launch |
0 | Tell the running stardash to launch / focus the given project’s app. Queues to ~/.staros/handoff_pending.json if stardash isn’t running — drained on next stardash boot. Same file-RPC the launcher’s stardash_bridge.lua uses |
registry |
1 | Serve live collab (WebSocket) for a filesystem remote |
cart |
6 | Cartridge inventory and oplog introspection |
ship |
0 | Snapshot + push a cartridge to a remote channel |
pull |
0 | Pull a cartridge from a remote channel into a local dir |
export-app |
0 | Export an app as a standalone git repository the cloud builder can clone (love-shared vendored, the runtimes record beside it; S3 of the cartridge program) |
pack |
0 | Package LOVE games for distribution |
publish |
0 | Publish a game to the remote server |
bootstrap |
0 | Bootstrap a project: create shared/ symlink or junction, validate pin |
build |
0 | Build Rust components in dependency order |
parity |
0 | Numerical parity check: live Rust forward vs training JAX forward (run a golden JSONL through the Rust comparator). See --help |
harness |
4 | Coding-model harness (stardata): scorecards, $0 reward-collapse audit, task miners; --emit routes results into ~/.startrade/audit.log |
component |
6 | A sidecar’s binary by its hash (the desk’s part three): component manifest (shared-target/release’s sidecars by sha256), component install <id> [--from|--manifest] [--restart] (copied to ~/.staros/bin/current link swapped atomically, previous kept), component rollback <id>, component list. Never the desk’s own code, never the running staros |
roster |
1 | What this box runs, at which version (the desk’s part three): roster probe writes ~/.staros/roster.json (the git checkouts with behind/ahead of tower/master as last fetched, the sidecars by sha256 and crate version, never run, the installed games and carts), which the work fold carries so every house compares hosts |
Reading code and screens
| command | nested | what it does |
|---|---|---|
sym |
7 | AST/symbol-level code reads via tree-sitter (rs/lua/py): read the function, not the file |
shot |
0 | Normalize a screenshot for model consumption: downscale to –max-edge, JPEG q–quality, print path + token estimate |
reel |
4 | Video → contact sheets + audio-envelope manifest (gameplay/dev session analysis at ~100-180 tokens per frame) |
gesture |
1 | Agent-native game testing: fold visual-regression verdicts into a gesture run’s .gesture.json (semantic assertions + golden diff) |
glyph |
6 | Font family & MSDF atlas tooling for the LÖVE apps: register faces into love-shared families.json, bake atlases, verify, specimen |
The web and the sites
| command | nested | what it does |
|---|---|---|
web |
20 | Rust web-generation core: build/serve/check/diff site.toml sites (star-web) |
broadcast |
3 | Push rendered clips + the daily agenda to staros.chat’s clip channels / frontpage (HTTP; never rsync) |
The studies, the press and the stories
| command | nested | what it does |
|---|---|---|
study |
4 | The studies READER: serve fascicles, registers, questions and the grammar history over the dev plane (token-gated, read-only against the repo; queueing writes ~/.staros only) |
press |
7 | StarPress: fold the studies repo into hub snapshots (fold/serve) + reading intents (take-up/schedule/done/drop). Intents are an append-only op log at ~/.staros/study-queue.ndjson; the fold never writes into the studies repo |
lore |
10 | StarLore notes + spaced repetition: add / lint / graph / import. See starlore/docs/integrations.md |
branch |
7 | StarBranch dialogue trees: lint / validate / graph / cart round-trip. See starbranch/docs/integrations.md |
story |
12 | Short-form vertical-video exporter (Story / Reel / Shorts). See starplot/docs/story-exporter.md |
saga |
4 | StarSaga content queue + TikTok/Instagram poster: queue ls/add/ approve/schedule/tt-review/post-due, tt-auth, ig-auth. The queue is an append-only op log at ~/.staros/saga-queue.ndjson |
subscriptions |
6 | Track subscriptions/services for accounting (registry + PDFs → annotated markdown + zip bundle) |
arxiv |
2 | arXiv submission tooling: rank candidate endorsers for a first submission |
latex |
6 | Shared LaTeX tooling: md preprint -> arXiv package, lint, tectonic build |
Trading
| command | nested | what it does |
|---|---|---|
ibkr |
2 | IBKR live-stack status: account, positions, orders (pod bridge). Bare = status; subcommands pause/resume the gateway to free the login session |
helm |
1 | StarHelm trading-agent status: book, ladder, exit maintenance + measurement lanes; helm lab = the experimental-apparatus state (backfill quality, FF doors, strategy library, repair round) |
strix |
3 | Strix prop-eval status for both accounts (synced ladder plans). Bare = status; subcommands pause/resume the pod’s token automation + force login |
pm |
0 | Polymarket live-agent P/L snapshot (public on-chain + data-api; no keys) |
fills |
2 | Fill-model calibration: compare simulated vs actual fills (JSONL) |
preflight |
0 | Pre-flight provider quotas (Finnhub / IBKR / Polymarket / Verda) |
pipeline |
3 | TOML-driven pipeline stage runner with audit logging (drives Makefile/script targets, audit lands at ~/.startrade/audit.log) |
weave |
4 | Timeweave registry: list/inspect/deploy with obs-space-hash check |
audit |
5 | Query the unified ~/.startrade/audit.log (tail / grep / stats) |
The vault, the keeps and the secrets
| command | nested | what it does |
|---|---|---|
vault |
7 | File distribution sidecar control: status / peers / transfers / publish / request. See staros/docs/file-distribution.md for the architecture overview |
conflict |
4 | Surface + resolve L3 sync conflicts (keep-local / keep-peer / snooze / list). Reads the conflict detector’s active.json. See staros/docs/sync-and-conflict-design.md |
repo |
11 | starkeep VCS: content-addressed, mergeable, LF-normalized version control with vault-mediated push/pull. staros repo {init,snapshot, log,status,branch,checkout,merge,push,pull} |
sync |
3 | staros-sync orchestrator: survey / push / pull every starkeep keep in the grove roster in doctrine order (love-shared first). staros sync {status,push,pull}. Moves history + surfaces conflicts; staros conflict resolves them |
secret |
4 | Secrets store (staros-keep): get/set/ls/rm credentials. Services consume them via staros.toml credentials=[...] → staros-super delivers $CREDENTIALS_DIRECTORY at spawn (systemd LoadCredential convention); Lua reads via require(“shared.secrets”). |
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/index.md (the command pages stay the repo's); the twin bfaad079a7ce (434093 bytes). The words are a draft.