CLI and MCP installation guide

Use the public CLI when a technical operator, Claude Code, Codex, Cursor, or another local agent needs to help set up and operate ROST. Use MCP when the local agent should call ROST tools directly from its own client.

The MCP server is remote and token-backed. There is no local MCP daemon to install. The CLI logs you in, mints a scoped MCP token, and prints the registration block for the deployed /mcp route.

Prerequisite: a human approver in a browser

A headless agent cannot complete setup unattended. Two things always require a human, so plan to announce the handoff rather than stall silently:

• Device-code approval at first login. rost login --device prints a code; a human must open the workspace URL in a browser, sign in with Google, match the code, and approve.
• Durable gated commands. Setting or approving a Charter, staffing a seat, and taking an agent live each open a confirmation that a human approves (an agent never approves its own request — see the confirmations-guide). The CLI surfaces the confirmation_id and an approveVia URL for the human. (rost mcp install is a partial exception: for an interactive operator it completes its own token-mint approval inline; in a headless/agent session it surfaces the confirmation and stops unless --skip-permissions / ROST_CLI_SKIP_PERMISSIONS=1 is set — see Approving the token mint below.)

Treat these as blocking prerequisites: the agent prepares the request and waits for the human approver.

Placeholder legend

Commands below use angle-bracket placeholders. The CLI prints the real, fully-resolved values at runtime — read them from the terminal, do not hand-construct them:

• <your-workspace-url> — your workspace origin. The CLI prints the full /auth/device and /mcp URLs in its output; copy them from the terminal rather than guessing the host.
• <tenant-slug-or-id> — a tenant identifier from rost tenants.
• <seat-id> — a seat id from rost command seat.create output or rost_get_responsibility_graph / rost command graph.get.
• <token-id> — an MCP token id printed by mcp install, or discoverable later via rost command mcp_token.list / rost_list_mcp_tokens.
• <confirmation-id> — shown in the CLI error or output for a gated command; see the confirmations-guide.

Before you start: create your account and company

A ROST account (the human identity) is created with Google sign-in — in the browser at /signup, or headlessly via rost login --device (a human approves the code in any browser). A company (tenant) can then be created either way:

• Browser: at /signup, name your company, then return to the CLI.
• Headless (no browser step): once logged in, run rost signup --company "<name>". This provisions the company for your session and makes it your active tenant, so rost onboard status and every other tenant-scoped command work immediately. This is the recommended path for an autonomous agent setting up from scratch.

If you run a tenant-scoped command before any company exists, the CLI tells you both options. You only get one company per signup; running rost signup --company again returns your existing company rather than creating a duplicate.

Install the CLI

Run the published package with npx:

npx @rosthq/cli@latest --help
npx @rosthq/cli@latest login

Or install it globally:

npm i -g @rosthq/cli
rost login

The package requires Node 22 or newer. The binary name is rost. Check your version before installing — npx will still launch the package on Node 20 or 18, but the CLI rejects an older runtime:

node --version

If it prints anything below v22, upgrade Node first.

Headless agent login (device-code flow)

A coding agent (Codex, Claude Code, or any headless shell) signs in without a browser of its own: the agent prints a short code, and a human approves it in any browser. This is the recommended path for autonomous agents. Plain rost login (the browser-callback flow) stays the default for an interactive human at a keyboard.

rost login --device

How it works:

1. The CLI prints a verification URL (your workspace's /auth/device page) and a short code, then polls and waits:

   To sign in, open this URL in any browser and approve the code:
     https://<your-workspace-url>/auth/device
     Code: ABCD-EFGH
   Waiting for approval…

The <your-workspace-url> shown here is a placeholder for this doc; the CLI prints your actual workspace origin. Read the URL and code from the terminal — do not hand-construct them. 2. A human opens the URL, signs in with Google, confirms the code shown in the browser matches the one in the agent's terminal, and clicks Approve. 3. The CLI detects the approval, exchanges a one-time handoff for a session, and stores it in the OS keychain. rost whoami then shows the account, and tenant-scoped commands (rost onboard status, etc.) operate in the approver's active tenant. If the approver has no company yet, create one headlessly with rost signup --company "<name>" — no browser step.

Notes:

• The code expires after 10 minutes — rerun rost login --device if it lapses.
• No password is entered, and no access token is stored on the server; only the agent's own machine holds the session (in its OS keychain).
• Matching the code before approving is a security step: only approve a code your own agent printed.
• Approve only in a browser you control and trust — never on a kiosk or someone else's device, and sign out afterward on any shared machine. Approval grants a live ROST session tied to your Google identity, not just a code match.

Headless Linux, CI, and machines with no keychain

By default the CLI stores the session in the macOS Keychain (on darwin). There is no built-in Windows or Linux keychain integration today — on any non-macOS host, or any machine without a keychain, the CLI errors with "No OS credential store is available" unless you opt into the file store.

For headless Linux, CI runners, or any no-keychain environment, set ROST_CLI_ALLOW_FILE_TOKEN_STORE=1 to opt into the development-only plain-file token store. It is not encrypted — it writes the file with owner-only permissions (directory 0700, file 0600) and prints a stderr warning. It stores only the CLI session token, never tenant secrets, API keys, or vault refs. Treat that file as a credential: do not bake it into a shared image and do not commit it.

The CLI checks this flag on every invocation, not just login. Export it for the whole shell or CI job (so rost whoami, rost onboard status, and the rest also find the file store), not only on the login line:

export ROST_CLI_ALLOW_FILE_TOKEN_STORE=1
rost login --device

For CI, do not run an interactive device login on every job (a device code still needs a human approver, which CI does not have). Note that the CLI session is a short-lived auth session (it carries an expiry), not a durable credential — so storing the session file as a long-lived CI secret will stop working once it expires, and re-approving a device code unattended is not possible. For ongoing unattended automation, prefer a seat-scoped MCP token used directly by your MCP client, and treat that client config as a secret. Such a token now defaults to a 90-day expiry, so for automation that must outlive that window, mint it with an explicit --expires-in <days> (up to 365) or, accepting the long-lived-credential tradeoff, --no-expiry — e.g. mcp install --scope seat --seat-id <id> --expires-in 365. Rotate it before it lapses (--rotate <old-token-id>), and revoke and re-mint if a runner image is rebuilt or shared.

First-run path

This is the install/auth quickstart — it gets you logged in, MCP registered, and onboarding started. It is a convenience view, not the full org-setup procedure: for the canonical end-to-end setup order beyond install, agent-reference-map is the source of truth (its 19-step Standard Setup Order). Read it with rost reference get agent-reference-map (step 6 below).

1. Log in: npx @rosthq/cli@latest login (or rost login --device for a headless agent) 2. Confirm identity: rost whoami 3. Create your company if you have none yet: rost signup --company "<name>" (no browser step) 4. List tenants: rost tenants 5. Select a tenant when needed: rost use <tenant-slug-or-id> 6. Read the agent map: rost reference get agent-reference-map (the full canonical setup order lives here) 7. Register MCP for the client (pick a scope — --scope is required): rost mcp install --client claude-code --scope tenant-admin for setup, or --scope seat --seat-id <id> for a narrower seat token 8. Inspect onboarding: rost onboard status 9. Get the guided agent prompt: rost onboard run

Or use the one-shot helper: rost init logs in when needed, optionally selects a tenant, installs MCP, and prints the onboarding prompt. It does not run every numbered step above (it does not create your company or call onboard status) — it gets you logged in, registered, and handed the onboarding prompt. As the first-run helper it defaults to a tenant-admin token (no seats exist yet), so unlike a direct mcp install it does not need --scope; pass --scope seat --seat-id <id> if you already have a seat to scope it to:

rost init --tenant <tenant-slug-or-id> --client codex

MCP install commands

A direct mcp install now requires an explicit `--scope` — there is no silent default. Choose --scope seat --seat-id <id> (the narrowest scope, limited to one seat's Charter and permission manifest — prefer it for day-to-day operation) or --scope tenant-admin (can administer the whole company — reserve it for initial setup). Running mcp install without --scope errors and mints nothing, naming both options. (The first-run helper rost init is the exception: it defaults to --scope tenant-admin because no seats exist yet at setup; and --rotate inherits the old token's scope, so it does not need --scope either.)

mcp install accepts an optional --skip-permissions flag (equivalently ROST_CLI_SKIP_PERMISSIONS=1). It governs the token-mint approval in a non-interactive session — see Approving the token mint below. An interactive operator never needs it.

Claude Code (tenant-admin):

npx @rosthq/cli@latest mcp install --client claude-code --scope tenant-admin

Codex (tenant-admin):

npx @rosthq/cli@latest mcp install --client codex --scope tenant-admin

Cursor (tenant-admin):

npx @rosthq/cli@latest mcp install --client cursor --scope tenant-admin

The tenant-admin token administers the whole company. For day-to-day operation, prefer a seat-scoped token instead — it operates only as one seat and is limited by that seat's Charter and permission manifest. Reserve the tenant-admin token for initial setup.

Seat-scoped MCP for a specific seat:

npx @rosthq/cli@latest mcp install --client codex --scope seat --seat-id <seat-id>

The <seat-id> comes from rost command seat.create output or rost_get_responsibility_graph / rost command graph.get.

Approving the token mint

Minting a token (and the inline revoke that --rotate performs) is a human-gated authority change at the command layer. How rost mcp install handles that approval depends on whether it runs in an interactive session:

• Interactive operator (a human at a real terminal). The CLI completes the approval inline: the operator who ran the command is the human in the loop, so it runs the gated mint, completes the confirmation for that same command, and prints the registration block — a single step, no separate URL to click.
• Non-interactive / headless / agent session. The CLI does not approve its own request. By default it surfaces the confirmation and stops, minting nothing: it prints the confirmation_id, the exact rost command confirmation.approve --json '{"confirmation_id":"<id>"}' command, and the approveVia URL when the server provided one, then exits non-zero ("pending human approval"). A human then approves it (in a browser or with that approve command) — and that approval executes the mint and returns the token in the approve output (shown once), so register it with your client from there. Do not re-run mcp install after approving: that starts a second mint and orphans the first token. (For an unattended agent that should mint and register in one step, use --skip-permissions below.)
• Opting into auto-approval in a headless session. Pass --skip-permissions on mcp install, or set ROST_CLI_SKIP_PERMISSIONS=1, to auto-approve the mint/revoke confirmation inline even without a TTY. This is a deliberate loosening (the running session stands in for the human approver) — use it only for trusted automation where you accept that the agent approves its own token mint.

The broader rule still holds for durable changes an agent proposes — charters, decisions, compass and charter amendments — where an agent never approves its own request and a human approves the surfaced approveVia confirmation. See the confirmations-guide for the four confirmation levels and that flow.

Handling the printed token (read this before you paste anything)

The registration block mcp install prints embeds a live bearer token — a real, scoped credential. mcp install prints this block; it does not write any client config itself. You apply it, and once applied the token lands in the client's config file in plaintext:

• Claude Code: run the printed claude mcp add command — that command writes the token into Claude Code's MCP config.
• Codex: paste the printed TOML stanza into your Codex config file.
• Cursor: paste the printed JSON entry into Cursor's MCP config.

Because the token lands on disk in plaintext, treat it like a password:

• Never commit the block or the client config to version control, and never paste it into a chat, issue, or log. A leaked block grants its full scope until revoked.
• The session asymmetry matters: your CLI login session lives in the OS keychain and is cleared by rost logout. The MCP token is a separate credential written in plaintext into the client config — rost logout does not revoke it. Revoke MCP tokens separately (below).

Example shapes of what mcp install prints (token redacted as <MCP_TOKEN>; the real values, including the workspace URL, are printed by the CLI — do not hand-construct them):

# Claude Code
claude mcp add --transport http rost https://<your-workspace-url>/mcp --header "Authorization: Bearer <MCP_TOKEN>"

# Codex (config.toml)
[mcp_servers.rost]
url = "https://<your-workspace-url>/mcp"
transport = "http"
headers = { Authorization = "Bearer <MCP_TOKEN>" }

// Cursor (mcp.json)
{
  "mcpServers": {
    "rost": {
      "url": "https://<your-workspace-url>/mcp",
      "headers": { "Authorization": "Bearer <MCP_TOKEN>" }
    }
  }
}

Verify the MCP connection

After registering, confirm the client can actually reach the server with the new token before doing real work. Make one cheap read call scoped to your token type:

• Any valid token: call rost_list_commands with {}.
• Tenant-admin token: read the resource rost://tenant/status.
• Seat-scoped token: call rost_get_context with {} (or read rost://seat/<seat-id>/context). A seat token cannot read rost://tenant/status — that is tenant-admin only, so do not use it to test a seat token.
• Success returns a normal JSON payload (the command list, your tenant/onboarding status, or your seat context). An auth error (a 401 / "not authorized" shape) means the token did not register — re-run mcp install.

Token lifetime and rotation

Every MCP token now carries an expiry. Tokens minted by rost mcp install default to a 90-day TTL (for both tenant-admin and seat-scoped tokens); after that the token stops authenticating and you re-mint. Override the lifetime at mint time:

• --expires-in <days> — set an explicit TTL, between 1 and 365 days. Example: rost mcp install --client codex --scope tenant-admin --expires-in 30.
• --no-expiry — mint a token with no practical expiry (a ~100-year TTL). This is a deliberate loosening for long-lived automation; the CLI prints a warning. Prefer a finite --expires-in and rotate instead.

mcp install echoes the chosen expiry, and rost command mcp_token.list reports expires_in_days for every token so you can see what is about to lapse.

One-step rotation. Replace a live token in a single command — it mints the replacement, prints the new registration block, then revokes the old token:

rost mcp install --client <client> --rotate <old-token-id>

Rotation preserves the original token's scope and seat: rotating a seat-scoped token mints a new seat-scoped token for the same seat, and rotating a tenant-admin token mints a tenant-admin token — you do not pass --scope/--seat-id (and if you do, they must match the old token, or the command errors without minting). The CLI looks the old token up first, so an unknown --rotate id fails cleanly with nothing minted. If the mint succeeds but revoking the old token fails (or the id isn't found at revoke time), the CLI says so on stderr and prints the manual mcp_token.revoke command — the new token is already live, so revoke the old one by hand. Find the <old-token-id> with rost command mcp_token.list.

You can also rotate the long way (mint then revoke separately):

1. Re-run rost mcp install --client <client> --scope <tenant-admin|seat> (add --seat-id <seat-id> for a seat token) to mint and register a fresh token — a direct install requires --scope. 2. Revoke the old one (below). Rotate on a periodic cadence, and whenever the scope or seat changes.

Revoke a token

Revoke the server-side token with the command printed by mcp install:

rost command mcp_token.revoke --json '{"token_id":"<token-id>"}'

Revocation is not just end-of-session housekeeping — it is your incident-response action. Revoke immediately if a laptop is lost or stolen, the client config leaks, or the token is committed to version control. If you no longer have the original printout, find the <token-id> with rost command mcp_token.list (MCP rost_list_mcp_tokens) — it returns token metadata, never token material.

Uninstall and cleanup

Revoking the server-side token leaves a dead entry in the client config that will keep erroring. To fully tear a setup down:

1. Revoke the token (mcp_token.revoke, above). 2. Remove the ROST entry from the client config: claude mcp remove rost for Claude Code; delete the [mcp_servers.rost] stanza from the Codex TOML; delete the rost entry from Cursor's mcp.json. 3. rost logout to clear the CLI session from the keychain (this does not revoke MCP tokens — step 1 does that).

Blast radius of a tenant-admin token

A leaked tenant-admin token can administer the whole tenant, not just one seat. It can run tenant-wide setup and onboarding, staffing (rost_staff_seat), member add / remove / role-change (rost_remove_member), Charter approval (rost_approve_charter), settings changes, and further token minting (rost_create_mcp_token) across every seat in the tenant. A seat-scoped token can act only as its one seat, bounded by that seat's Charter and permission manifest. This is why a direct mcp install now requires you to choose `--scope` explicitly (no silent tenant-admin default), why you should mint the narrowest scope that does the job, and why you should reserve tenant-admin for initial setup. mcp install echoes the granted scope and its blast radius at mint time on every path. See the security-model-guide for tenant isolation, vault-backed credentials, and the seat-scoped-authority principle.

Storing the Anthropic key and other credentials

Storing the tenant model key or any other secret goes through credential ingress as a vault reference — the secret is never pasted into a prompt, config, or log. Use rost_save_tenant_anthropic_key (tenant.anthropic_key.save) for the tenant Anthropic key, or rost_store_credential (credential.ingress) for other secrets; rost_configure_agent_tools stages credential requests but never accepts raw secrets. Credential storage is a gated credential_flow confirmation that a human approves. For the vault model and the security posture behind this, see the security-model-guide and the tool-access-and-vault guide; for the confirmation gate, see the confirmations-guide.

When to use MCP or CLI

• A technical operator wants to drive onboarding from a local agent session.
• A partner wants to use their own local model subscription.
• A Steward wants a local agent to inspect context, draft changes, or prepare work.
• A developer wants repeatable setup commands.

Access scopes

Tenant-admin access can help set up the company. Seat-scoped access lets an agent act only as a specific seat. Prefer the narrowest scope that can do the job — a direct mcp install requires you to choose --scope tenant-admin or --scope seat --seat-id <id> and mints nothing until you do. rost init defaults to tenant-admin (first-run setup, no seats yet), and --rotate inherits the existing token's scope. See the security-model-guide for tenant isolation, vault-backed credentials, server-side authority checks, and the seat-scoped-authority principle.

For pairing and running a local runner, see the runner-guide.

Safe operating practices (security checklist)

These are the security posture rules for operating after install — a checklist applied across the whole setup, not a competing install procedure. For the full rationale, see the security-model-guide.

1. Log in with the CLI and select the tenant if needed. 2. Read agent-reference-map. 3. Register MCP for the narrowest needed scope (prefer a seat-scoped token for day-to-day operation). 4. Start with onboarding.status or context lookup. 5. Draft changes before durable activation. 6. Route approvals through human confirmation (an agent never approves its own request — see the confirmations-guide). 7. Revoke tokens when you finish operating or the seat changes — and immediately on a lost laptop, leaked config, or committed token. (Revoking is separate from rost logout, which clears only the CLI session, not MCP tokens.)

CLI command catalog

Authentication and tenant selection

Reference and docs

--audience <human|cli|mcp|in_app_agent> (on reference list and reference search) filters guides to those tagged for that audience. When omitted, all audiences are returned.

Onboarding

Direct command execution

Seat scope (`--seat <seat-id>`). Seat-operating commands run in a seat context. A seat-scoped MCP token already carries that context; a tenant or owner session does not, so pass --seat <seat-id> to target a specific seat — an owner can target any seat in the tenant, a member only a seat they occupy. The flag rides the x-rost-seat header out-of-band and is never part of the command body; the server resolves and authorizes the seat scope. It works on both the raw rost command <id> path and the ergonomic wrappers (e.g. rost task list --seat <seat-id>).

Regular operation wrappers

Ergonomic subcommands for everyday operation. Each wrapper is sugar over the same server-side command shown in the command-id column — it builds the JSON body from flags and routes through the same execution path as rost command <id> --json. Add --json to any wrapper for stable, machine-parseable output; without it the wrapper prints a concise line that still includes the ids needed for follow-up calls. rost command <id> --json remains the completeness floor for fields a wrapper does not expose.

These ergonomic wrappers (including the rost agent group) require rost 0.2.0 or newer — run npx @rosthq/cli@latest … to get them. Older versions can still reach every command through the rost command <id> --json floor, since command execution is server-side.

MCP registration

MCP tool and resource catalog

This catalog is the canonical machine surface — the rost_* tools your MCP client calls. Three different things are called "tools" in ROST; do not confuse them:

1. The MCP tools below — the rost_* surface your client actually calls to read and act. 2. `rost tools list` / `tool.catalog` (MCP rost_list_tool_catalog) — the agent-configuration catalog the builder reads when staffing an agent. It is selectable per agent and does not execute yet; it is not the surface you call to operate. 3. The "Available tools guide" (in the sidebar) — covers tool *categories* and governance, not a callable surface. See the available-tools-guide.

Sections below: Command discovery (2) · Public reference (3) · Tenant-admin tools (grouped by domain) · Seat-scoped operating tools (9) · MCP operation resources (9).

Command discovery tools

These read-only tools are available to any valid MCP token (like the reference tools). Use them to discover a command's exact contract before calling it, and when a command fails, read the error's help field and run the command it names.

The equivalent CLI verbs are rost command schema <id> and rost command list. The discoverable tool catalog is rost tools list (MCP rost_list_tool_catalog, tenant-scoped).

Public reference tools and resources

Tenant-admin tools

These names are available to tenant-admin MCP tokens. They are aliases over the shared command layer and are audited as MCP tool calls. The list spans far more than onboarding — it groups, in order: onboarding, seats, Charter, confirmations, Compass, staffing, credentials/tokens, graph reads, agents, runners and work orders, notifications, members and settings, Signals, Cascade goals, Friction, tasks, Sync, and escalations.

Several rows here are seat-operating commands (task.create, the signal.*, goal.*, and friction.* families) surfaced because they are also tenant-admin-callable — which is why the CLI wrapper table marks them "Seat". Scope selection follows the Seat scope note above: a seat-scoped token already carries seat context, while a tenant or owner token must pass --seat <seat-id> (CLI) or supply seat context (MCP). See the security-model-guide for the seat-vs-tenant authority principle.

Seat-scoped operating tools

Seat-scoped MCP tokens expose the operating protocol below. The server still checks the seat's permission manifest, Charter, task ownership, and tenant boundary. These are the seat-token equivalents of the CLI rost task / rost signal / rost friction wrappers and the tenant-admin task tools above: rost_get_tasks, rost task list, and task.list are the same operation reached three different ways. The command-id column makes the mapping explicit.

MCP operation resources

These read-only resources bundle the facts the UI shows so an agent can avoid guessing ids. Each enforces tenant, role, and seat scope server-side and never returns secrets, tokens, local file paths, or cross-tenant ids. Tenant-wide resources require a tenant-admin token; the seat-context resource is readable by the owning seat token (or a tenant-admin for any seat in the tenant); the operations map is public to any valid token.

Troubleshooting

These rows are quick, at-a-glance triage. For deeper auth, tenant, scope, confirmation, and MCP-token errors — including structured error-code interpretation — see the troubleshooting-guide.

• Not logged in: run rost login, then retry rost whoami.
• Session not persisting (keychain issue — "not logged in" right after a successful login): clear and re-run rost login --device; the session is stored in the macOS Keychain by default. On a non-macOS or no-keychain host the CLI errors unless you opt into the plain-file token store — see Headless Linux, CI, and machines with no keychain.
• Wrong tenant: run rost tenants, then rost use <tenant-slug-or-id>.
• Missing Node: install Node 22 or newer, then rerun npx @rosthq/cli@latest --help.
• Node present but too old (npx launches but the CLI rejects it): run node --version; if it is below v22, upgrade Node.
• Stale npx cache: rerun with npx @rosthq/cli@latest --help or clear the npm cache.
• MCP connection not working after registering: call rost_list_commands with {} (any token); with a tenant-admin token read rost://tenant/status, with a seat-scoped token call rost_get_context with {} (a seat token cannot read rost://tenant/status). A 401 / not-authorized shape means the token did not register — re-run mcp install.
• Revoked, expired, or invalid MCP token: run rost mcp install --client <client> --scope <tenant-admin|seat> again to mint and register a fresh one (a direct install requires --scope; or rotate the old token in place with --rotate <old-token-id>, which inherits its scope). Tokens minted by mcp install default to a 90-day expiry — check expires_in_days in rost command mcp_token.list; mint with --expires-in <days> or --no-expiry to change it.
• Confirmation required: a human approves from the approveVia web link or runs the rost command confirmation.approve --json ... command shown in the CLI error output (an agent never approves its own request — see the confirmations-guide).
• Command denied by scope or manifest: switch to a tenant-admin token for setup, or ask a human Steward to update the seat Charter and permission manifest.
• Inference budget hard cap reached (a run stops with a budget precondition error): raise the tenant hard cap with rost settings update --hard-cap-usd <amount> (command settings.update), then retry. A new company starts at a $0 hard cap, so managed-inference runs are blocked until it is set. The sandbox dry run is free and is never blocked by the cap, so you can charter, dry-run, and go live before setting a budget.
• Need command guidance: run rost docs, rost reference search "onboarding", or rost reference get agent-reference-map.
• Need MCP guidance: call rost_reference_get with {"slug":"agent-reference-map"}.