| title | Commands |
|---|---|
| description | Every CLI command and flag. |
| sidebar_order | 9 |
roster here means either of these. With nothing installed, run commands through npx:
npx @nanocollective/roster@latest upgrade. Or install it once with
npm install -g @nanocollective/roster and type roster upgrade. When you run through npx,
the commands roster suggests are printed the npx way, so they can be pasted as they are.
Every command that changes anything prints a plan and changes nothing unless you pass
--apply. lint, prompt, export, brief, doctor and fix never change anything.
portal is the exception: it is interactive, and each change there is a button you press after
seeing what it will do.
Where setup has got to, and the one thing to do next. Every step is read from GitHub and from disk each time, so it never disagrees with the world and it is safe to run as often as you like.
--json the steps as JSON: each with done, who (agent or human), do and command
--join <org> check out an org that already runs roster, here
--add-repo <name> add a repo in the org to org.yaml as a product the staff work on
--dir <path> where the workspace is, or would be
This is what the SKILL.md install follows: a coding
agent runs roster setup --json, does next, and runs it again until ready is true. A step
for a human is one only you can do: signing in, confirming on GitHub, a credential typed in your
own terminal.
Saves Roster's SKILL.md for each coding agent on this machine (Claude Code in
~/.claude/skills/roster, Codex in ~/.codex/skills/roster), so a later session knows how to
run Roster without being told. It is the same file as https://roster.nanocollective.org/SKILL.md.
--print print the file instead
Every scanner's findings, as one brief you paste into a coding agent working in this workspace.
--json the findings as data, rather than as a brief
--offline skip everything needing the network
--ops <dir> ops repo directory
doctor, the prompt audit and lint each already carry the sentence that fixes their own
finding; this collects them. Two piles come out: what an agent editing files here can do, and
what only a person can: an org permission, an App install, a credential. The second is listed
but marked not to attempt, because an agent handed one of those invents a workaround.
The brief states which files belong to the framework before it states any of the work. A fix
applied to a vendored file is reverted by the next roster upgrade, and that has happened.
The portal's Health screen has the same text behind a copy button.
Stand up a new tenant: the ops repo, the org layer, and the recorded merge base.
--org <name> the GitHub organisation. Required.
--name <text> what the business is called. Defaults to the org.
--human <login> who the agents answer to. Defaults to your gh login.
--marker <tag> provenance tag on a fact they ruled on.
--agent <id> coding agent. See docs/agents.md.
--dir <path> where to create the workspace.
--ops <name> ops repo name. Defaults to roster-ops.
--apply
With --apply it also sets the ops repo's Actions access to "accessible from repositories in
the organisation", which is what lets every brain call its workflow. If GitHub refuses (it needs
admin on the repo), it prints the reason and the settings page to click instead.
Will not write org/business.md. That is yours.
Scaffold a staff member: repo, two callers, manifest, memory index, charter stub, labels, pinned status issue, and peer wiring in both directions.
--name <text> role name, e.g. "Chief Financial Officer"
--dir <name> workspace directory and repo name
--schedule <cron> defaults to a slot staggered after the last one
--model <id>
--timeout <n> daily ceiling, minutes
--mention-timeout <n>
--secret-prefix <X> secrets become <X>_APP_ID and <X>_APP_PRIVATE_KEY
--app <slug> defaults to the pattern the peers use
--public-app <slug> the shared public identity
--no-review-gate leave the product repos' branch rules alone
--apply
With --apply it also:
- commits and pushes, as you, what it changed in repos that already exist: each peer's
staff.yaml,org.yaml, and the newstaff.yamlonce the status issue has a number. The plan lists each commit first, and a push that fails is reported and left for you. - adds the new brain to the agent credential's org secret, if there is one, so the credential is
never asked for again. See
roster credential. - adds a review-before-merge ruleset to each product repo that does not already require an approving review. See security.
Create the GitHub App and put its credentials in the brain repo's secrets.
--public create the shared public identity instead
--port <n> localhost port for the hand-off. Default 4310.
--no-open print the URL rather than opening a browser
--apply actually create it; without it, prints the App name, secrets and repos
Cannot install the App: GitHub asks a person to confirm which repos it reaches. It prints a link
to the install page with the org and every repo the staff member needs already selected (its
brain, its peers' trackers, the product repos), so confirming is one click. The pre-selection uses
suggested_target_id and repository_ids[], which GitHub's own links use but does not document;
when the ids cannot be read the link is the plain install page. See
manual steps.
Store the coding agent's credential once for the org.
--repo-secrets a secret on each brain repo, even where an org secret would work
--apply read the credential and store it
By default it is one organisation secret, named after the agent's token_env, shared with every
brain repo; roster hire adds each new brain to it. It uses a secret on each brain instead, and
the plan says why, when an org secret would not arrive: on GitHub Free an org secret does not
reach a private repo, and only an org owner can set one. Setting an org secret also needs the
admin:org scope on your gh token (gh auth refresh -h github.com -s admin:org); if it is
refused, the credential goes on each repo and the output says so.
The value comes from standard input, or a prompt that does not echo, and goes to gh on its
standard input. It is never on a command line and never on disk.
claude setup-token # Claude Code; see docs/agents.md for the others
roster credential --applyGive staff an outside service to use in their runs, as an MCP server. See connectors.
roster connector [list]
roster connector add <name> [--staff <handles>] [--read-only] [--set <field=value>] [--apply]
roster connector remove <name> [--apply]
--staff <handles> who gets it, comma separated (default: the catalogue's suggestion)
--read-only hold it to reading, for everybody who has it
--set <field=value> a setting the service needs, such as --set project_ref=abc123
--url <url> a service roster does not know: its MCP server's URL
--command <line> or the command that starts it
--secret <NAME> a key that service needs, by the name it is given (repeatable)
--keep-key change who has it without asking for the key again
--apply do it
list shows the services roster knows and the ones this org has, with who has each and whether
its key is stored. add asks for the key at a prompt that does not echo, checks it with the
service, stores it as a GitHub secret every brain repo can read, and commits org.yaml. A key
the service rejects is not stored. remove deletes the keys and takes the connector out of
org.yaml.
roster connector add sentry --staff cto --apply
roster connector add supabase --set project_ref=abc123 --read-only --applyNotion's hosted server signs in with a browser, so it is added from the hosted portal's Connectors page.
Start one daily run now and follow it to the end.
--no-wait start it and print the link, without following it
--apply start the run
Runs gh workflow run <handle>-daily.yaml, finds the run it started, and polls it until it
finishes. It prints the outcome, the step it failed at if it did, and the log's link. A success
is what roster doctor counts as proof that the App, its grant, the secrets and the callers all
work, so its "unproven" warning goes away. It is a real run and spends what a scheduled one
would, which is why it needs --apply. The staff card and Health have the same as
Run once now.
When a staff member wakes beyond the daily round, and what they do then. With no action it lists their daily round and routines.
add --name <n> --at <cron> --do <text> a new routine; --do-file <path> reads the text from a file
remove <id> take one away
daily <cron> move the daily round
run <id> start one routine now
--apply write, commit and push the brain repo
--ops <dir> ops repo directory
Times are five-field cron in UTC. A change writes staff.yaml, routines/<id>.md and the
daily caller together, so the schedule GitHub fires on is always the one in the manifest. The
portal's Routines screen does the same with a picker. See routines.
Stop a staff member without destroying anything.
--apply
--ops <dir>
Their brain repo is their entire memory and there is no undo for deleting one, so this does
not touch it. It disables their three workflows through the API, removes them from org.yaml,
removes them from every peer's staff.yaml, and deletes the from-<handle> labels their peers
carried for them. Everything they ever knew stays where it is, readable in the portal and on
GitHub.
Disabling rather than deleting the workflow files is what makes it reversible: the files stay, so re-enabling is one click, and nothing has to be regenerated from templates that have moved on since.
It deliberately does not delete or archive the repo, close their issues, or unpin their status issue. All three are one click on GitHub, having thought about it.
Plan-then-apply, like everything else that changes something.
Check the org is wired up, and that the agents have actually been running.
--offline skip everything needing the network
--json machine-readable findings
Exit 1 if anything failed. Warnings do not fail.
Carry framework changes into the tenant. See upgrading.
--apply
--check exit non-zero if anything is pending
--baseline <git-ref> one-time: reconstruct a merge base
--verbose show files that are already up to date
Check memory against the grammar, and warn when a fact, the index or the decision log is over its budget. See memory.
--quiet print only problems
Print a self-contained brief for authoring one of the files the agents run on. Paste it into whatever agent you use, or pipe it.
discover write org/business.md, which every prompt is composed on top of
charter <who> write a staff member's CHARTER.md
voice revise org/voice.md, the house style every surface inherits
amend <who> change what a staff member is told, with the whole prompt attached
--kind <k> for amend: daily | mention (default: daily)
--want <text> for amend: what you want changed
--example <e> for charter: an example's handle, or none (default: matched to the role)
--ops <dir>
roster brief amend cto --want "stop opening decision issues for anything reversible"
roster brief discover
roster brief charter cto | pbcopy
roster brief voice > /tmp/brief.mdcharter carries one of the worked examples as a
model to adapt, matched to the role by handle or name. It is a model for the shape, not content
to copy, and the brief still interviews you first. --example picks another; --example none
leaves it out. The portal's copy-a-prompt has the same choice.
amend is the different one. It carries the composed prompt and every file it is assembled
from, so the agent you paste it into does not have to ask for any of them. The portal's Prompt
screen builds the same thing, and offers it per audit finding.
The other three are the only files anybody writes by hand. org/operating.md, org/voice.md and
org/guardrails.md ship written; a charter and org/business.md cannot, because they are the
half that is about you.
Nothing in a brief is specific to any agent. Claude Code gets /discover, /voice and
/charter as well, generated from these same files by roster init and roster hire. To add
them to a tenant that predates this, redirect the brief into the file:
roster brief discover > roster-ops/.claude/commands/discover.mdCompose and print what a staff member is actually sent.
--kind daily|mention
--diff <workflow.yaml>
--inflight
A run also carries the pull requests people have open on the product repos. --inflight reads
them through your own gh and includes them; without it that section is left out, so the output
does not move with somebody else's branch.
mention needs trigger context:
ROSTER_CONTEXT='{"issue_number":"1","comment_id":"1","repo":"o/r"}' \
roster prompt cto --kind mentionServe the portal on your machine. roster with no arguments does the same, which is the
shortest way in. It takes the same flags: roster --no-open is roster portal --no-open.
It reads the org from GitHub as you, with your gh login (or GITHUB_TOKEN), so it needs no
checkout to show it. Setting up, hiring, retiring and Health use the checkout.
--port <n> default 4300
--host <a> default 127.0.0.1. Anything else exposes write actions to the network.
--dir <path> where a tenant would be created or checked out. Default: here.
--org <org> show this org, with no checkout. Default: the checkout's org.yaml.
--ops-repo <n> its ops repo, with --org. Default: roster-ops.
--no-open don't open a browser
It opens the page in your browser when it starts. It stays closed in CI, over SSH, when output
is not a terminal, or with BROWSER=none.
With no tenant where you started it, this is the setup screen: it stands up a new org, or checks out one that already runs roster. Local only. See the portal.
Views: Home, Trackers, Runs, Org, Staff, Docs, and per staff member Brain, Prompt, Graph, What changed, Health.
It can act as you: reply, close, reopen and open issues; hire and retire; edit and commit the org layer, prompt fragments and charters; create a staff member's GitHub App; store the agent credential; set the ops repo's Actions access; start one run and follow it; and copy a prompt for authoring the two files nothing can generate.
The same portal on your own URL, on Cloudflare Workers, behind Sign in with GitHub. Only the
people in org.yaml's humans: can sign in, and each acts as themselves. Setting up, hiring
and Health stay on your machine.
--domain <host> where it lives, on a zone in your Cloudflare account. Needed the first time.
--account <id> the Cloudflare account, pinned so a deploy cannot land on another one
--apply deploy. Without it, says what it would do.
--ci no questions: deploy what portal/wrangler.jsonc says (the workflow uses this)
The first deploy walks you through creating the GitHub OAuth App, then writes
portal/wrangler.jsonc and a workflow that redeploys every morning. See
hosting the portal.
The whole org as one JSON document.
--out <file>
--ops <dir> ops repo directory. Default: found by walking up.