Installation Guide¶

Install¶

One command installs rai as a standalone binary. No Python required, no virtual environment, no activation step.

Linux / macOS¶

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

Windows¶

PowerShellInstaller (.exe)

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

Download and run the graphical installer — no terminal needed:

Download rai-installer-windows-x86_64.exe

The installer performs the same steps as the PowerShell script (checksum verification, PATH registration) with a guided UI.

What the installer does¶

Downloads prebuilt binaries (rai + rai-mcp-pipeline) from GitHub Releases
Verifies SHA-256 checksums for both binaries before installing either (atomic)
Installs to ~/.local/share/rai/ (Linux/macOS) or %LOCALAPPDATA%\rai\ (Windows)
Symlinks into ~/.local/bin/ (Linux/macOS) or registers on user PATH (Windows)
No Python required

Verify¶

which rai         # should print ~/.local/bin/rai
rai --version

Then enter your project and run:

cd your-project
rai onboard

Prerequisites¶

Git — the only hard requirement.
Claude Code — install from Anthropic to use RaiSE workflows.

Pin a specific version¶

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

./install.ps1 -Version v3.1.0

Upgrading¶

Step 1 — upgrade the binary (idempotent, atomic swap):

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

# Windows (PowerShell)
irm https://github.com/humansys/raise/releases/latest/download/install.ps1 | iex

Step 2 — sync your project's skills, hooks, and config:

cd your-project
rai upgrade

The binary upgrade replaces the rai executable; rai upgrade updates the governance files, hooks, and skill set inside each project. Both steps are required to get the full update.

Coming from a per-project venv?

See the venv-to-binary Migration Guide.

Coming from RaiSE 2.x?

See the 2.x Migration Guide for breaking changes.

Uninstalling¶

Linux / macOS:

rm -rf ~/.local/share/rai ~/.local/share/rai-mcp-pipeline
rm -f ~/.local/bin/rai ~/.local/bin/rai-mcp-pipeline

Windows:

Remove-Item "$env:LOCALAPPDATA\rai" -Recurse -Force
Remove-Item "$env:LOCALAPPDATA\rai-mcp-pipeline" -Recurse -Force

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

Troubleshooting¶

Problem	Solution
`rai` not found after install	Add `export PATH="$HOME/.local/bin:$PATH"` to your shell profile and restart the terminal
Old version still running	A project `.venv` may be shadowing the binary — see PATH shadowing
`rai doctor` shows warnings	Run `rai doctor --fix` to apply automatic repairs
Windows shows "Windows protected your PC" (SmartScreen)	Binaries are unsigned in 3.1.x. Click "More info" → "Run anyway" on the first launch of `rai.exe` or the installer, or run `Unblock-File <path>` yourself. `install.ps1` already unblocks the files it downloads once their checksum verifies
`rai discover scan` reports a path-length error (`MAX_PATH`)	The checkout path plus a source file's relative path is >= 260 characters. Enable Windows long paths (`HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled=1`) or move the checkout closer to the drive root
`UnicodeEncodeError` when running `rai` on Windows (Spanish/LATAM consoles)	The system console uses code page cp1252, which cannot encode some Unicode characters written by `rai`. Set `PYTHONUTF8=1` to force UTF-8 everywhere. PowerShell (current session): `$env:PYTHONUTF8 = "1"` — to persist across sessions, add that line to your `$PROFILE`. CMD: `set PYTHONUTF8=1` before running any `rai` command. Alternatively, run `chcp 65001` to switch the console to UTF-8 for the current window.

Alternative: `uv tool install` (Python-based)¶

Not recommended for new installations

The uv tool method below requires Python 3.12+. New installations should use the binary installer above. This section is preserved for existing Python-based installs, and because it remains the only documented way to consume pre-release builds from the GitLab registry globally.

Prerequisites¶

Python 3.12+ and uv (curl -LsSf https://astral.sh/uv/install.sh | sh)
Git — the only hard requirement for using RaiSE

Install via `uv tool`¶

Stable releases are published to PyPI — no custom index, no extra flags:

uv tool install raise-cli

Pre-release builds from the GitLab registry¶

Pre-releases (aN, bN, rcN) are published only to the GitLab package registry, never to public PyPI. Only they need the full recipe:

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 \
  --resolution=highest \
  --prerelease=allow \
  raise-cli

What each flag does:

Flag	Why
`--index-url <gitlab>`	The RaiSE pre-release 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
`--resolution=highest`	Forces the resolver to pick the newest compatible version of every dependency — prevents an older `raise-core` being selected when multiple versions exist in the registry
`--prerelease=allow`	Required — pre-release versions are pre-releases

Why --resolution=highest matters

raise-cli and raise-core are co-released in lockstep — each CLI version requires the matching raise-core. Without --resolution=highest, uv's default resolver may select an older raise-core from the registry that is missing modules the CLI imports, resulting in ModuleNotFoundError: raise_core.cartridges at runtime.

Pin an exact version (reproducible)¶

For a stable release, plain PyPI is enough — no custom index, no --prerelease:

uv tool install 'raise-cli==3.1.0'

To pin a pre-release, you still need the GitLab index — pre-releases are not published to PyPI:

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 \
  --resolution=highest \
  --prerelease=allow \
  'raise-cli==3.1.0rc5'

Upgrade via `uv tool`¶

uv tool upgrade raise-cli

If you installed a pre-release with the GitLab index above, drop it when you move to a stable release — left in place it keeps resolving prerelease artifacts ahead of the stable ones. To move to a newer pre-release instead, repeat the full recipe:

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 \
  --resolution=highest

Upgrading the package does not upgrade your projects — run rai upgrade in each checkout afterwards, as in Upgrading above.

Uninstall via `uv tool`¶

uv tool uninstall raise-cli

Next Steps¶

Enter your project directory and run rai onboard — it detects your repo state and routes you to the right setup step:

cd your-project
rai onboard

Continue with Getting Started — it walks you through your first session and work cycles step by step.

Installation Guide¶

Install¶

Linux / macOS¶

Windows¶

What the installer does¶

Verify¶

Prerequisites¶

Pin a specific version¶

Upgrading¶

Uninstalling¶

Troubleshooting¶

Alternative: uv tool install (Python-based)¶

Prerequisites¶

Install via uv tool¶

Pre-release builds from the GitLab registry¶

Pin an exact version (reproducible)¶

Upgrade via uv tool¶

Uninstall via uv tool¶

Next Steps¶

Alternative: `uv tool install` (Python-based)¶

Install via `uv tool`¶

Upgrade via `uv tool`¶

Uninstall via `uv tool`¶