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
powershell -ExecutionPolicy ByPass -c "irm https://docs.raiseframework.ai/install.ps1 | iex"

For pre-release or a specific version, download and run with flags:

irm https://docs.raiseframework.ai/install.ps1 -OutFile install.ps1
.\install.ps1 -Pre                  # latest pre-release
.\install.ps1 -Version 3.0.0a6     # specific version
.\install.ps1 -DryRun              # preview without changes

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 -OutFile install.ps1
.\install.ps1 -Pre

# Windows — specific version
.\install.ps1 -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

Uninstalling

RaiSE is installed per-project in a .venv directory. To remove it:

Linux / macOS

cd your-project
rm -rf .venv

Windows

cd your-project
Remove-Item .venv -Recurse -Force

# Also remove the global shim (optional):
Remove-Item "$HOME\.local\bin\rai.cmd"

This does not touch your project files, governance, or .raise/ directory — only the Python virtual environment is removed.

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
rai doctor shows warnings Missing config Run rai doctor --fix to apply automatic repairs

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

¿Múltiples repos? Si trabajas con 3+ repositorios, revisa la guía de workflow multi-repo para evitar copias redundantes de skills.