Installation Guide¶

Quick Install (recommended)¶

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 alpha or a specific version, download and run with flags:

irm https://docs.raiseframework.ai/install.ps1 -OutFile install.ps1
.\install.ps1 -Alpha                # latest alpha from GitLab registry
.\install.ps1 -Version 3.1.0a7 -Alpha # specific alpha from GitLab registry
.\install.ps1 -DryRun              # preview without changes

Options¶

Flag	Linux/macOS	Windows	Effect
Alpha channel	`bash -s -- --alpha`	`-Alpha`	Install latest alpha from GitLab registry
Specific alpha	`bash -s -- --alpha --version 3.1.0a7`	`-Alpha -Version 3.1.0a7`	Pin exact alpha from GitLab registry
Specific stable	`bash -s -- --version 3.1.0`	`-Version 3.1.0`	Pin exact stable version from PyPI
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 alpha from GitLab registry
curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --alpha

# Specific alpha from GitLab registry
curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --alpha --version 3.1.0a7

# Windows — latest alpha from GitLab registry
irm https://docs.raiseframework.ai/install.ps1 -OutFile install.ps1
.\install.ps1 -Alpha

# Windows — specific alpha from GitLab registry
.\install.ps1 -Alpha -Version 3.1.0a7

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¶

Checks Python 3.12+ is available
Installs uv if not present
Creates a .venv in your project directory (or reuses an existing one)
Installs raise-cli from PyPI for stable releases, or from the GitLab alpha registry with --alpha
Verifies the installation
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.1.0
~/projects/experiment/.venv/   → raise-cli 3.1.0a7

No conflicts, no global state, no surprises.

Want one rai for every repo?

Alpha testers who work across many repositories can install RaiSE system-wide with uv tool instead — a single rai on your PATH, no per-project venv. See Global Install (All Repos).

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
# alpha:
# uv pip install --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 \
#   raise-cli==3.1.0a7
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

For alpha users, use the GitLab alpha channel explicitly:

cd your-project
curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --alpha --version 3.1.0a7

To upgrade to a specific stable version:

source .venv/bin/activate
uv pip install raise-cli==3.1.0

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:

Open Claude Code in your project directory
Run /rai-welcome for guided onboarding
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.