The staros CLI, command by command

this page as plaintext

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//.task.md, the same files the F11 kanban + orchestrator’s tasks_sync use
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///, the 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
  • FAILlint/web-reference 12 Nov on tower
  • PASSlint/staros-ref 12 Nov on tower

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.