Update Rness
Your organization uses one version of Rness, pinned in .rness/package.json. Every rness command in the workspace runs that version, whichever rness you type, so the whole team stays in step. Moving to a new version is a change to .rness, reviewed like any other.
Update
From the workspace's .rness/:
npx rness upgradepnpm rness upgradeyarn rness upgradebunx rness upgradeIt moves the pin to the latest release, installs it, brings in the new version's starter files (CI workflow, hooks, templates) without losing your edits, updates every repository's generated files, and commits .rness. Then:
- Push
.rness. - In each repository, commit the files it lists at the end, for example
.claude/skills/rness/.
To go to a given version, up or down: pnpm rness upgrade 0.14.0.
If rness stops on the Node.js version before it starts, see Troubleshooting.
rness.json is rewritten once
rness.json has one current shape, contract 2: no repos key, a repository and the parts of it all declared under scopes (The workspace). upgrade rewrites the file once, in the same commit as the new pin. It reads and checks the file first, before changing anything. If the file holds something the new shape cannot (a repository with no scope at org/<name>, a scope inside no repository, a scope outside org/), it stops with one line per problem, changes nothing and leaves the pin where it was: fix the file by hand, then run upgrade again. Meanwhile the current version keeps working, unless the pin already names a version that reads contract 2 (a Dependabot pull request merged first): every command then stops on the file, and Claude Code may not edit .rness/. Fix the file in your editor, outside Claude Code, or go back to the previous version first with npx @rness/cli@0.24.0 upgrade 0.24.0. When a part now inherits its repository by nesting, upgrade says so (scope "web" now inherits platform (nested)).
To do it in one step, use the new copy:
npx @rness/cli@latest upgradeRun from the workspace's .rness/, rness upgrade of an older pin (pnpm rness upgrade) installs the new version but cannot rewrite the file. Its sync then stops with rness.json is contract 1: run npx @rness/cli@latest upgrade. Run that, or the pinned copy once more from .rness/ (pnpm rness upgrade, npm exec -- rness upgrade): it finishes the update, rewrites the file, syncs and commits. A global rness older than 0.25.0 cannot: it answers that a merge is in progress, or that the workspace is already at that version. If a newer release came out between the two runs, name the version the first run installed: upgrade <version> finishes it.
In a workspace whose packageManager is npm, pnpm rness fails: use npm exec -- rness upgrade or npx rness upgrade.
Until the file is rewritten, every command but upgrade, login and logout stops with that line. The hooks do not block your commits: they print one line, rness: policies not checked, naming npx @rness/cli@latest upgrade. Once rewritten, a downgrade below 0.25.0, the first version that reads contract 2, is refused: the older version cannot read the file.
A teammate who joins with rness create <org> a workspace still on the former shape is told which version to use, in the form npx @rness/cli@<version> create <org>. If its pin already names a version that reads contract 2, they are told to have the update run first: a teammate runs npx @rness/cli@latest upgrade in .rness/ and pushes, then they run create again.
Your teammates
They pull .rness, then run any rness command, such as rness status, before opening Claude Code:
git -C .rness pullThat command sees the new pin, installs it, and carries on. The hooks that Claude Code and git run use the version installed in .rness and never install one: until a command has, they run the previous version, which may not read the new rness.json.
Hear about new releases
A pull request for each release
Every .rness comes with .github/dependabot.yml. For each release of Rness, Dependabot opens a pull request on your organization's .rness that moves the pin, and the validate check runs with the new version before anyone merges.
- Review the pull request, and merge it with a merge commit rather than a squash.
- Pull
.rness, then run the update above. It finds the pin already moved, brings in the starter files, updates the repositories and commits.
When the pull request moves the pin of a workspace still on the former shape to a version that reads contract 2, its validate check fails with rness.json is contract 1: run npx @rness/cli@latest upgrade: the new version does not read the former shape. Tell the team once: one developer runs npx @rness/cli@latest upgrade in .rness/ (on the pull request's branch before merging it, or on main after) and pushes; the others git pull, then run any rness command before opening Claude Code (Your teammates).
Dependabot checks weekly and waits 3 days after a release before opening the pull request, which guards against a compromised release. To get it sooner, give up that wait for Rness only. In .rness/.github/dependabot.yml, under allow:, at the same indentation:
cooldown:
exclude:
- "@rness/cli"Or watch the repository
On github.com/rness-dev/rness, Watch → Custom → Releases notifies you of each release. The changelog says what each one changed, and what to commit.
When the starter files conflict
If you edited a starter file on the same lines as the new version, upgrade stops before installing and lists the conflicts. For each file, keep yours with git checkout --ours <file> or take the new one with git checkout --theirs <file>, then git add and git commit, and run the update again.
.rness must be committed, with no merge in progress, before an update.
pnpm and same-day releases
pnpm refuses packages published less than 24 hours ago. Every .rness exempts Rness in its pnpm-workspace.yaml (minimumReleaseAgeExclude), so an update on release day works. Only pnpm create rness on release day still picks the previous version.
In CI
The validate workflow of .rness sets RNESS_NO_INSTALL=1: a pin that moved is reported, not installed. Set the same variable on any machine that must not install.