Skip to content

Installation Guide

One command installs RaiSE into a per-project virtual environment. Each project gets its own version — you can run v2.4 and v3.0 side by side.

Linux / macOS

cd your-project
curl -LsSf https://docs.raiseframework.ai/install.sh | bash

Windows (PowerShell)

cd your-project
irm https://docs.raiseframework.ai/install.ps1 | iex
Install-RaiSE          # latest stable

For pre-release or a specific version:

irm https://docs.raiseframework.ai/install.ps1 | iex
Install-RaiSE -Pre                  # latest pre-release
Install-RaiSE -Version 3.0.0a6     # specific version

Alternatively, download and run directly (supports all flags natively):

irm https://docs.raiseframework.ai/install.ps1 -OutFile install.ps1
.\install.ps1 -Pre

Options

Flag Linux/macOS Windows Effect
Pre-release bash -s -- --pre -Pre Install latest alpha/beta
Specific version bash -s -- --version 3.0.0b1 -Version 3.0.0b1 Pin exact version
Dry run bash -s -- --dry-run -DryRun Show what would happen

Examples:

# Latest stable release
curl -LsSf https://docs.raiseframework.ai/install.sh | bash

# Latest pre-release (alpha/beta)
curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --pre

# Specific version
curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --version 3.0.0b1

# Windows — latest pre-release
irm https://docs.raiseframework.ai/install.ps1 | iex
Install-RaiSE -Pre

# Windows — specific version
irm https://docs.raiseframework.ai/install.ps1 | iex
Install-RaiSE -Version 3.0.0b1

After install, activate the venv:

source .venv/bin/activate   # Linux/macOS
.venv\Scripts\Activate.ps1  # Windows

Prerequisites

  • Git — the only hard requirement. The script handles everything else.
  • Claude Code — install from Anthropic to use RaiSE workflows.

The script installs uv and Python 3.13 automatically if they are missing — you do not need to install them beforehand.

What the script does

  1. Checks Python 3.12+ is available
  2. Installs uv if not present
  3. Creates a .venv in your project directory (or reuses an existing one)
  4. Installs raise-cli from PyPI into the venv
  5. Verifies the installation
  6. Runs data migration if upgrading from a previous version

Per-project isolation

Unlike global installs (pipx), this approach gives each project its own RaiSE version:

~/projects/legacy-app/.venv/   → raise-cli 2.4.0
~/projects/new-app/.venv/      → raise-cli 3.0.0b1
~/projects/experiment/.venv/   → raise-cli 3.0.0a6

No conflicts, no global state, no surprises.

Manual installation

If you prefer not to use the script:

cd your-project
pip install uv              # if you don't have uv
uv venv                     # create virtual environment
uv pip install raise-cli    # latest stable
# or: uv pip install raise-cli --prerelease=allow   # latest pre-release
source .venv/bin/activate
rai --version

Development Setup (from source)

For contributors working on raise-commons:

git clone https://github.com/humansys/raise.git
cd raise-commons
uv venv
uv pip install -e ".[dev]"
rai --version

Upgrading

Upgrading from 2.x?

RaiSE 3.0 includes breaking changes to config files, storage, and CLI commands. Follow the migration guide before upgrading.

Run the same install script again in your project directory — it's idempotent:

cd your-project
curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --pre

To upgrade to a specific version:

source .venv/bin/activate
uv pip install raise-cli==3.0.0b1 --prerelease=allow

Known Pitfalls

Problem Cause Solution
python3 points to wrong version asdf/pyenv shim Use which python3 to check; use system Python or configure your version manager
uv not found after install PATH not refreshed Open a new terminal and re-run
rai not found after install venv not activated Run source .venv/bin/activate
Import errors after upgrade stale venv Delete .venv and re-run the install script

Next Steps

After installation:

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