<!-- GENERATED by starlens/site/tools/reference_pages.py from the engine's sources: do not edit; run it. -->

[[nav: reference | here=cli]]

<div class="doc">

<!-- GENERATED by scripts/staros-ref.py from `staros --help`: do not edit; rebuild staros, then run it. -->

# The staros CLI, command by command

<p class="plain"><a href="../cli/index.md">this page as plaintext</a></p>

*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](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/<project>/<slug>.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/<id>/<sha>/, 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"). |

<details class="changes">
<summary>The work on this page: the checks that hold it</summary>

[[work: checks | rows=lint/web-reference,lint/staros-ref]]

</details>

<nav class="pager"><a href="../cli/guide/">← cli/guide</a><a href="../">The reference</a><a href="../verbs/">verbs/index →</a></nav>

*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.*

</div>
