Upgrading to RaiSE 3.1.0¶

This guide is the how. For what changed and why, see the 3.1.0 release notes.

On a release candidate? Do not run rai self-update

On every 3.1.0 release candidate, rai self-update deletes ~/.local/bin and everything in it -- the rai symlink and any unrelated tool you keep there -- and removes its own backup in the same operation, so nothing is recoverable.

Publishing 3.1.0 makes three surfaces offer you that exact command: the prompt at rai session start, your agent following its session-start skill, and the fix hint in rai doctor. Decline all three. Upgrade with the installer instead -- route B.

1. Which route is yours?¶

Run both commands:

rai self-upgrade --help     # does the command exist?
ls -l "$(which rai)"        # where does it point?

What you see	You are on	Route
`self-upgrade` exists	3.1.0 or newer already	A
No such command; `rai` is a symlink into `~/.local/share/rai/`	a release candidate	B
No such command; `rai` is under a `.venv/`, pipx, or `uv tool` path	2.x, 3.0.x, or a 3.1.0 beta	C
`rai: command not found`	nothing installed	Installation guide

Every route ends at the same checklist.

2. First, back up the database¶

The schema migration is forward-only and runs on the first database open -- including read-only commands such as rai db status. Once it has run, no older binary can open the file again.

cp ~/.rai/raise.db ~/.rai/raise.db.backup-pre-3.1.0

3. Your route¶

Route A -- when `rai self-upgrade` already exists¶

You are on 3.1.0 or newer, so the package layer already carries the fix. This is the normal path from here on: it upgrades the binary first, then the current project's governance files.

rai self-upgrade             # preview first with --dry-run

It only touches the project you run it from. Run rai upgrade in every other checkout -- the first line of the checklist.

Route B -- from a release candidate¶

Upgrade with the installer. It is a separate code path from rai self-update: it replaces the private bundles under ~/.local/share/ and then recreates the symlinks, and never treats ~/.local/bin as a directory to swap -- which is what the release-candidate defect did.

Linux / macOSWindows (PowerShell)

curl -fsSL https://github.com/humansys/raise/releases/latest/download/install.sh | bash

irm https://github.com/humansys/raise/releases/latest/download/install.ps1 | iex

The Windows installer is equally safe over a release candidate: it clears the install directory before copying, so no stale metadata survives to make rai --version report the wrong build.

To pin an exact build or review the script first, see the installation guide.

If rai self-update already destroyed ~/.local/bin

Re-running the installer restores rai and rai-mcp-pipeline. It does not restore anything else that lived there -- other tools and shims have to be reinstalled by hand.

Then continue with the checklist.

Route C -- from a venv, pip, pipx, or `uv tool` install¶

Your upgrade is a migration: the install method itself changes, and there are residues to remove before the new binary behaves. The venv-to-binary migration guide is the complete procedure and already contains the checklist below -- follow it end to end.

Coming from 2.x, read the 2.x migration guide first, and do not skip rai db import-legacy: 2.x pattern files do not migrate on their own and are lost silently.

Staying on pip or uv tool rather than moving to the binary? Stable releases come from PyPI and prereleases only from the prerelease registry, so a pinned prerelease index no longer resolves what you want. The exact commands are in the installation guide.

4. After the binary -- the checklist¶

The installer and rai self-upgrade move the binary. These are the parts that nothing moves for you.

Do this	Where	Why
`rai upgrade`	every checkout	Skills, `.raise/`, and `AGENTS.md`. Route A already did the project you ran it from.
`rai graph build`	every checkout and worktree	The graph is checkout-scoped in 3.1, and the new columns are only populated by a build.
`rai memory ingest --apply`	once	Tier-2 memory is not automatic. Without it, demoted notes leave the index and are not retrievable.
`rai db import-legacy`	once, only from 2.x or 3.0	Idempotent; originals are renamed `*.migrated`, never deleted.
Restart your agent session	once	The MCP server keeps the previous binary in memory even after `rai --version` reports the new one.

Then verify:

rai --version
which rai        # a leftover .venv or pipx shim can still win
rai doctor

If which rai does not print your global binary, you have PATH shadowing -- see PATH shadowing.

Check your scripts and CI

Four command-level breaking changes in 3.1.0 can break automation that worked before: rai init no longer writes without --apply, five rai scm commands were removed, rai db migrate was renamed, and rai clean now defaults to scanning every registered project. See Command changes that break scripts in the release notes.

5. If you need to go back¶

The binary rolls back; the database does not. Both are machine-level — one binary and one database serve all your projects. Rolling back to fix one project's post-upgrade issue affects every project on the machine. See Rollback and Recovery for the full architecture explanation and per-project mitigation strategies.

curl -fsSL https://github.com/humansys/raise/releases/latest/download/install.sh | bash -s -- --version <older-version>

The schema migration is forward-only — an older binary opening a migrated database is not supported. To actually return to an earlier build you must also restore the backup from section 2:

cp ~/.rai/raise.db.backup-pre-3.1.0 ~/.rai/raise.db

Anything recorded after the upgrade is lost in that restore — across all projects, not just the problematic one. This is why the backup is the first step — and remember that any release candidate you roll back to still carries the rai self-update defect described at the top of this page.