# 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 doc Documents of the workspace: doc new 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 doc` ``` Usage: rness doc [options] [command] Documents of the workspace: doc new Options: -h, --help display help for command Commands: new [options] Write the next numbered document of a collection (adr, specs, plans) and print its path help [command] display help for command ``` `doc new ` writes the next numbered document of `adr`, `specs` or `plans` and prints its path. The number is the highest of the collection plus one, on four digits, counted from the files present, so two sessions never pick the same one. The file is `NNNN-.md`, the slug taken from `--title` (`untitled` without it), with its collection's front matter — `date` today, the first status (`Proposed` for an ADR, `Draft` otherwise), an empty `repo`, and `updated` except on an ADR — and its opening sections, those of `adr/0000-template.md` for an ADR. It never overwrites a file (exit 1); any other collection is bad usage (exit 2). It runs from anywhere in the workspace. No prompt, no network. The lifecycle skills of Claude Code number what they create with it ([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, each named `NNNN-.md` with a number no other document of its collection has — 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] [collection] Create the organization's Agent Pulse board, or a collection's own project, and sync sync [options] Bring every declared project 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 `"projects": { "pulse": }`, 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. `rness pulse create ` gives a collection of `.rness/` — a directory whose documents carry a status — a project of its own, named after it, and adds it to `projects`; its documents leave Agent Pulse. `pulse`, a collection declared already or a directory with no document is refused ([a collection's own project](../guide/agent-pulse.md#a-collection-s-own-project)). 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, syncs every declared project, the collections' own first and Agent Pulse last. On each it 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`. |