<!-- 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">

# The staros CLI, as the house uses it

<p class="plain"><a href="../../cli/guide.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.*

*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 serve` serves 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 call `GET /study/verify?witness=<id>&span=<text>`, which answers with
  concord's verdict object (studies `shared/docs/study-json.md`). The reader's token opens that call, and so does
  a device token with the `piece` scope.
- `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 is `docs/working-study-package-2026-10.md`.
- `staros press fold` folds the studies repo into the hub's snapshots. `press serve` serves them on loopback and
  refolds on change. `press take-up` takes 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/graph` works on StarLore notes and spaced repetition (`starlore/docs/integrations.md`).
- `staros branch lint/validate` checks StarBranch dialogue trees.
- `staros story render` and `staros saga queue` are the short-form exporter and the content queue
  (`starplot/docs/story-exporter.md`). Posting is the operator's.
- `staros latex build` and `staros arxiv endorsers` are 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).

<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="../../formats/script/">← formats/script</a><a href="../../">The reference</a><a href="../../cli/">cli/index →</a></nav>

*Generated by `tools/reference_pages.py` from `docs/cli/guide.md`; the twin `bfaad079a7ce` (434093 bytes). The words are a draft.*

</div>
