Global Install (All Repos)¶

The standard installer puts RaiSE in a per-project .venv — each repo gets its own version. That is the recommended default, but alpha testers who work across many repositories often want a single rai available everywhere, without activating a virtualenv in each project.

This guide installs raise-cli as a global tool with uv tool, so one rai serves every repo on the machine.

When to use this

Use the global install if you maintain 3+ repos and want one rai on your PATH. If you need different RaiSE versions per project (e.g. running v2.4 and v3.1 side by side), keep the per-project install instead.

Prerequisites¶

Ubuntu 24.04 (or any Linux / macOS). Ubuntu 24.04 ships Python 3.12, which satisfies RaiSE's >=3.12 requirement.
Git — the only hard requirement for using RaiSE.

You do not need to install Python or uv beforehand — the first step installs uv, and uv manages Python automatically if needed.

1. Install uv¶

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc        # or open a new terminal

2. Install raise-cli globally (latest alpha)¶

uv tool install \
  --index-url https://gitlab.com/api/v4/projects/82108942/packages/pypi/simple \
  --extra-index-url https://pypi.org/simple/ \
  --index-strategy unsafe-best-match \
  --prerelease=allow \
  raise-cli

What each flag does:

Flag	Why
`--index-url <gitlab>`	The RaiSE alpha registry on GitLab (anonymous read — no token needed)
`--extra-index-url https://pypi.org/simple/`	Normal dependencies (typer, pydantic, …) come from PyPI
`--index-strategy unsafe-best-match`	Lets `raise-core` resolve from GitLab while everything else resolves from PyPI
`--prerelease=allow`	Required — alpha versions are pre-releases

Pin an exact alpha (reproducible)¶

To install a specific build instead of the latest, pin the version:

uv tool install \
  --index-url https://gitlab.com/api/v4/projects/82108942/packages/pypi/simple \
  --extra-index-url https://pypi.org/simple/ \
  --index-strategy unsafe-best-match \
  --prerelease=allow \
  'raise-cli==3.1.0a13'

3. Put `rai` on your PATH¶

uv tool update-shell      # adds ~/.local/bin to PATH if missing
source ~/.bashrc

4. Verify (from any directory)¶

cd ~/any/repo
rai --version             # → raise-cli version 3.1.0a13
rai --help

rai now works in every repository on the machine — no source .venv/bin/activate required.

Upgrading¶

When a new alpha ships, upgrade the global tool in place:

uv tool upgrade raise-cli --prerelease=allow \
  --index-url https://gitlab.com/api/v4/projects/82108942/packages/pypi/simple \
  --extra-index-url https://pypi.org/simple/ \
  --index-strategy unsafe-best-match

Uninstalling¶

uv tool uninstall raise-cli

This removes only the global rai tool. Your projects, governance, and .raise/ directories are untouched.

Global vs per-project — which am I running?¶

If you have both a global rai and a project .venv, an activated venv takes precedence. Check which one is active:

which rai                 # ~/.local/bin/rai → global tool
                          # ./.venv/bin/rai → per-project venv

To always use the global tool, don't activate the project venv (or deactivate it with deactivate).

Known pitfalls¶

Problem	Cause	Solution
`rai` not found after install	`~/.local/bin` not on PATH	Run `uv tool update-shell`, then open a new terminal
Install resolves an old version	uv cache	Add `--reinstall` to the `uv tool install` command
`No matching distribution` right after a release	PyPI/registry indexing lag (~30–60s)	Wait a minute and retry
Project still uses old RaiSE	A project `.venv` is shadowing the global tool	`deactivate` the venv, or remove `.venv` if you want global everywhere

Next steps¶

Open Claude Code in any project directory
Run /rai-welcome for guided onboarding
Run /rai-session-start to begin your first session