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] <repo> 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 commandrness 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 <name> the GitHub organization, exact name (github.com/<name>)
--repos <list> comma-separated repositories for your workspace (catalogue
entries are cloned, others added)
--provider <name> where the organization lives: github (gitlab, atlassian
later)
--pm <name> 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 <name> 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 <name> reserved
-h, --help display help for commandcreate never runs inside a workspace. It creates <org>/ in the current directory, with the organization's exact name, and either scaffolds .rness/ (a new organization) or clones the existing <org>/.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 <org>/.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). 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] <repo>
Clone (or adopt) a repository under org/ and declare it in rness.json
Arguments:
repo <repo>, <owner>/<repo>, or a clone URL
Options:
--scopes <list> 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 commandadd 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 <name> 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 <name> 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 commandsync renders the context of every scope and writes it into the AGENTS.md of your clones, as a block between <!-- BEGIN rness --> and <!-- END rness -->; 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).
rness context
Usage: rness context [options]
Resolve and print the context for a scope
Options:
--scope <name> scope to resolve (default: the scope owning the current
directory)
--json print JSON instead of Markdown
-h, --help display help for commandcontext 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 commandstatus 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).
rness validate
Usage: rness validate [options]
Check the .rness/ tree against the contract and every generated block
Options:
-h, --help display help for commandvalidate 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 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 commandmcp 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). 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 commandpulse 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 <org>/.rness whose body is the document (Agent Pulse).
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": <number> }, 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 <org>/.rness. Without them they stop before writing anything, with:
the pulse needs Issues on <org>/.rness: turn them on in its Settingsrness 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). 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 commandupgrade 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). 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 commandlogin 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 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 commandlogout 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. |