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] [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 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 "projects": { "pulse": <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.
rness pulse create <collection> 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).
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, 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). 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. |