# CLI reference Every command, with its own `--help` and what it does. Inside a workspace, every command except `create`, `upgrade`, `login` and `logout` runs the version pinned in `.rness/package.json`, whichever `rness` you type. ``` Usage: rness [options] [command] Configuration-plane CLI for rness workspaces Options: -v, --version print the version -h, --help display help for command Commands: context [options] Resolve and print the context for a scope status [options] [tab] Show the status of every decision, specification and plan, a tab per directory validate [options] Check the .rness/ tree against the contract and every generated block sync [options] Write the rness block into every AGENTS.md of the cloned repositories pulse Show the agent's work on the organization's board mcp [options] Serve the workspace context to agents over MCP (stdio, read-only) add [options] Clone (or adopt) a repository under org/ and declare it in rness.json login [options] Log in to GitHub, to list and clone private repositories logout Forget the GitHub login of this machine upgrade|update [options] [version] Move this workspace to another @rness/cli: pin it in .rness/package.json, install, sync create [options] [name] Create or join a GitHub organization's workspace, or a blank one with --blank help [command] display help for command ``` ## `rness create` ``` Usage: rness create [options] [name] Create or join a GitHub organization's workspace, or a blank one with --blank Arguments: name the GitHub organization, same as --org; with --blank, the workspace directory Options: --org the GitHub organization, exact name (github.com/) --repos comma-separated repositories for your workspace (catalogue entries are cloned, others added) --provider where the organization lives: github (gitlab, atlassian later) --pm package manager for .rness/ (npm, pnpm, yarn, bun; default: the one running this command) --ssh force git@github.com: (default: SSH when it works, else HTTPS) --https force https://github.com/ --blank a local workspace with no GitHub organization: .rness/, an empty org/, the root files --agent a new workspace's agent, declared in rness.json (repeatable; supported: claude) --skip-install do not install .rness/ dependencies -y, --yes do not ask for confirmation --template reserved -h, --help display help for command ``` `create` never runs inside a workspace. It creates `/` in the current directory, with the organization's exact name, and either scaffolds `.rness/` (a new organization) or clones the existing `/.rness` (joining). In a terminal it lists the organization's repositories to pick from, with every catalogue repository pre-selected when joining; picked repositories are cloned under `org/`, new ones are added to the catalogue. Without a terminal or with `--yes`, `--repos` is the selection, and a join without `--repos` clones the whole catalogue. Logged in, it offers to create the private `/.rness` on GitHub and push. A cancelled prompt writes nothing and exits 0. In a terminal, before the organization, it asks `Where does your organization live?`: GitHub, the one this version talks to; GitLab and Atlassian (Bitbucket + Jira) are listed, disabled. `--provider github` answers it off a terminal. The answer is written to `rness.json` as `provider` ([the catalogue](../guide/workspace.md#rness-json-the-list-of-repositories)). A join asks too, then takes the provider the organization's `rness.json` names; `--blank` asks nothing. Joining is served by the version the organization pinned, whatever copy you ran: `create` installs `.rness/` and hands the first sync to it. ## `rness add` ``` Usage: rness add [options] Clone (or adopt) a repository under org/ and declare it in rness.json Arguments: repo , /, or a clone URL Options: --scopes comma-separated sub-directories to declare as scopes extending the repository --ssh force git@github.com: (default: SSH when it works, else HTTPS) --https force https://github.com/ -y, --yes do not ask for confirmation -h, --help display help for command ``` `add` clones the repository under `org/` — or adopts a clone already there — and declares it in `rness.json` for the whole team: an entry in `repos`, a scope of the same name, and one scope per `--scopes` directory, each extending the repository. Names are lowercased. In a workspace that clones over SSH, a failing SSH test offers `--https` for that repository only. ## `rness sync` ``` Usage: rness sync [options] Write the rness block into every AGENTS.md of the cloned repositories Options: --scope only this scope (the root block is skipped) --check render and compare only; exit 1 when a block is out of date --pull git pull --ff-only in every clean clone --all clone every rness.json repository missing from org/ --agent declare an agent in rness.json, then write its files (repeatable; supported: claude) -y, --yes do not ask for confirmation -h, --help display help for command ``` `sync` renders the context of every scope and writes it into the `AGENTS.md` of your clones, as a block between `` and ``; the rest of each file is untouched. A `CLAUDE.md` holding `@AGENTS.md` is created next to it when there is none. In a terminal, catalogue repositories missing from `org/` are offered for cloning first; with `--yes` or `--check` they are named on one `not cloned:` line instead. A clone `rness.json` does not know gets no block and a `not in rness.json:` line. `--check` writes nothing and exits 1 when a block is out of date — the command for a repository's CI. With agents declared in `rness.json`, it also writes the files those agents need ([agent targets](../guide/claude-code.md)). ## `rness context` ``` Usage: rness context [options] Resolve and print the context for a scope Options: --scope scope to resolve (default: the scope owning the current directory) --json print JSON instead of Markdown -h, --help display help for command ``` `context` prints the resolved context — standards, ADRs, specifications, plans and skills — of one scope: the global files of each collection, the scope's own, and everything along its `extends` chain. Without `--scope`, the scope owning the current directory; at the workspace root, the global files only. `--json` prints the same as one object. No prompt, no network. ## `rness status` ``` Usage: rness status [options] [tab] Show the status of every decision, specification and plan, a tab per directory Arguments: tab open on this tab: adr, specs, plans, … Options: -h, --help display help for command ``` `status` shows where every decision, specification and plan stands: a tab for ADRs, one for specifications, one for plans, and one for each other directory of `.rness/` whose Markdown files carry a `status` in their front matter; a line per document, newest first — its number or date, its title, its status. In a terminal it is a full-screen view: `←`/`→` or `Tab` change tab, `↑`/`↓`, `PgUp`/`PgDn` and `Home`/`End` scroll, `q` or `Esc` closes and gives the screen back. Off a terminal — a pipe, CI, an agent's tool — it prints Markdown, a table per tab; `rness status specs` prints that one. It reads `.rness/` and writes nothing. In Claude Code, `/rness:status` shows the tables ([agent targets](../guide/claude-code.md)). ## `rness validate` ``` Usage: rness validate [options] Check the .rness/ tree against the contract and every generated block Options: -h, --help display help for command ``` `validate` checks `.rness/` against its contract — `rness.json`, and the front matter and allowed statuses of every ADR, specification and plan — and, when `org/` clones are present, every generated block: stale (its hash no longer matches a fresh render, or someone edited inside the markers) is a problem, missing is a warning. So is a value an [agent target](../guide/claude-code.md) needs and a clone lacks. It warns when the scaffold merged in `.rness` is behind the pin. It runs alone in a checkout of `.rness/`, which is what the scaffold's CI workflow does. No prompt, no network. ## `rness mcp` ``` Usage: rness mcp [options] Serve the workspace context to agents over MCP (stdio, read-only) Options: -h, --help display help for command ``` `mcp` is a local MCP server, started by an agent over stdio — not a command to type. It reads the workspace's `.rness/` and writes nothing. Four tools answer "what applies here" and "where was this decided": | Tool | Returns | | --- | --- | | `rness_context({ scope? })` | The scope of the working directory, or the one named, and what applies to it: standards, decisions, specifications and plans — id, status, title and path, no bodies. | | `rness_list({ collection, status? })` | Every document of a collection, across scopes, optionally of one status. | | `rness_read({ path })` | One file of `.rness/`, by its path there; 256 KiB at most, nothing outside `.rness/`. | | `rness_search({ query, collection? })` | The documents whose text matches, most matching first, with the matching lines. | `.rness/` is read again on each call, so an edit shows at once. It speaks the MCP revision `2026-07-28` and the earlier ones that open with `initialize` (`2025-11-25` back to `2024-11-05`). For Claude Code, `rness sync` registers it in each repository ([agent targets](../guide/claude-code.md)). Another agent can run the same command from a clone. ## `rness pulse` ``` Usage: rness pulse [options] [command] Show the agent's work on the organization's board Options: -h, --help display help for command Commands: create [options] Create the organization's Agent Pulse board and sync it sync [options] Bring the board up to date with the documents of .rness/ help [command] display help for command ``` `pulse` shows the documents of `.rness/`, and the agent at work on them, in the organization's GitHub Projects: a project named **Agent Pulse**, a board per directory, each document an issue of `/.rness` whose body is the document ([Agent Pulse](../guide/agent-pulse.md)). `rness pulse create`, once per organization, needs an `org` in `rness.json` — a blank workspace is refused — and no pulse declared yet. It creates the project and at once writes `"pulse": { "project": }`, and the `provider`, into `rness.json`; then it adds the fields and the views and runs a first sync, its `created` line saying what it added. A step failing after the project exits 1 with the pulse declared: `rness pulse sync` completes the layout. Commit `rness.json` in `.rness`. A workspace with no `provider` whose repositories look like GitLab is refused before anything is created: write `"provider": "github"` if the organization is on GitHub. Both need Issues on `/.rness`. Without them they stop before writing anything, with: ```text the pulse needs Issues on /.rness: turn them on in its Settings ``` `rness pulse sync`, as often as wanted, works in two passes. First each document gets its issue — created, or reopened — with its label and fields; then the bodies that changed are written, since a body links to other documents' issues. It archives the items whose document is gone and adds the option or the board a new status or directory needs. It says what it did to the issues, then to the items: `created 1 issue`, `reopened 1 issue`, `synced 52 items: 1 created, 2 updated, 49 unchanged`. The `synced` line also counts the items it archived. On one of GitHub's rate limits it waits as GitHub says, and says so as it begins (`waiting 60 s — GitHub's rate limit`), 10 minutes at most in all; past that it stops with how many changes it did not make, and the next sync makes them. Both also need a login with the `project` scope ([`rness login`](#rness-login)). Without one, `create` offers to log in, in a terminal; with `-y` or off a terminal, the pulse stops with `the pulse needs a GitHub login: run rness login` or `the pulse needs the project scope: run rness login`. A classic `GITHUB_TOKEN` works when it carries the scope; a fine-grained or GitHub App token reports no scope, and the pulse refuses it. When GitHub cannot be reached, it says so (`cannot reach GitHub: …`) instead of asking for a login. ## `rness upgrade` ``` Usage: rness upgrade|update [options] [version] Move this workspace to another @rness/cli: pin it in .rness/package.json, install, sync Arguments: version an exact version (default: the latest release) Options: -y, --yes do not ask for confirmation -h, --help display help for command ``` `upgrade` merges the target version's scaffold into `.rness` with git, pins the version in `.rness/package.json`, installs with the workspace's package manager, syncs through the new copy — the blocks and the agent files — then commits `.rness` ([the scaffold, merged with git](../guide/upgrade.md#update)). The next steps say what is left: push `.rness`, and per repository the files the sync changed. A hook refusing the commit leaves everything staged, and `upgrade` exits 1. `.rness` must be clean, with no merge in progress. It is never delegated: the copy you ran is the one that upgrades. Teammates' next `rness` command installs the new pin itself. ## `rness login` ``` Usage: rness login [options] Log in to GitHub, to list and clone private repositories Options: --setup-git make rness git's credential helper for github.com --no-setup-git do not ask about git -h, --help display help for command ``` `login` connects Rness to your GitHub account through GitHub's device flow — a code to approve at `https://github.com/login/device`, from any machine — so that `create` lists your private repositories and organizations, and clones over HTTPS carry the login. The login is one file under your config directory, readable by you only; the token lives 8 hours and is renewed on its own. `GITHUB_TOKEN`, then `GH_TOKEN`, win over it. `--setup-git` makes Rness git's credential helper for github.com, for your own `git pull` and `git push`; it needs a global install. It asks for the `repo` and `read:org` scopes, and for `project` too where the workspace declares a pulse, or when `rness pulse create` runs it: a developer who never uses the [pulse](#rness-pulse) grants nothing more. A login made before the pulse was declared lacks the scope: run `rness login` again. A `provider` written in `rness.json` that this version cannot talk to is refused. ## `rness logout` ``` Usage: rness logout [options] Forget the GitHub login of this machine Options: -h, --help display help for command ``` `logout` forgets the login of this machine and undoes the git credential helper. The authorization itself is revoked in GitHub's settings; the command prints the link. ## Environment | Variable | Effect | | --- | --- | | `RNESS_NO_INSTALL=1` | After a pull that moved the pin, do not install it: warn and run the command anyway. For CI, a container image, a machine that cannot install. | | `RNESS_NO_DELEGATE=1` | Run the copy you invoked, never the pinned one. | | `RNESS_DEBUG=1` | Stack traces on errors, and a line naming the copy delegated to. | | `GITHUB_TOKEN`, `GH_TOKEN` | Used before the stored login, in that order: CI needs no `rness login`. | | `NO_COLOR=1`, `FORCE_COLOR=1` | Plain output, or coloured output through a pipe. Output through a pipe or in CI is plain by default. | ## Exit codes | Code | Meaning | | --- | --- | | `0` | Success — including a prompt the user cancelled or declined. | | `1` | Failure: a handled error, a stale block under `--check`, a problem under `validate`. | | `2` | Bad usage — or a command that needs a terminal, run without one and without `--yes`. |