Instalación Global (Todos los Repos)¶

El instalador estándar coloca RaiSE en un .venv por proyecto — cada repo tiene su propia versión. Ese es el default recomendado, pero los alpha testers que trabajan en muchos repositorios suelen querer un solo rai disponible en todos lados, sin activar un virtualenv en cada proyecto.

Esta guía instala raise-cli como herramienta global con uv tool, de modo que un único rai sirve para todos los repos de la máquina.

Cuándo usar esto

Usa la instalación global si mantienes 3+ repos y quieres un solo rai en tu PATH. Si necesitas versiones distintas de RaiSE por proyecto (p. ej. correr v2.4 y v3.1 en paralelo), conserva la instalación por proyecto.

Prerrequisitos¶

Ubuntu 24.04 (o cualquier Linux / macOS). Ubuntu 24.04 trae Python 3.12, que cumple el requisito >=3.12 de RaiSE.
Git — el único requisito obligatorio para usar RaiSE.

No necesitas instalar Python ni uv de antemano — el primer paso instala uv, y uv gestiona Python automáticamente si hace falta.

1. Instalar uv¶

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc        # o abre una terminal nueva

2. Instalar raise-cli globalmente (último 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

Qué hace cada flag:

Flag	Por qué
`--index-url <gitlab>`	El registry alpha de RaiSE en GitLab (lectura anónima — no necesitas token)
`--extra-index-url https://pypi.org/simple/`	Las dependencias normales (typer, pydantic, …) vienen de PyPI
`--index-strategy unsafe-best-match`	Permite que `raise-core` se resuelva desde GitLab mientras lo demás se resuelve desde PyPI
`--prerelease=allow`	Obligatorio — las versiones alpha son pre-releases

Fijar un alpha exacto (reproducible)¶

Para instalar un build específico en vez del más reciente, fija la versión:

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. Poner `rai` en tu PATH¶

uv tool update-shell      # agrega ~/.local/bin al PATH si falta
source ~/.bashrc

4. Verificar (desde cualquier directorio)¶

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

rai ahora funciona en todos los repositorios de la máquina — sin necesidad de source .venv/bin/activate.

Actualizar¶

Cuando salga un alpha nuevo, actualiza la herramienta global en su lugar:

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

Desinstalar¶

uv tool uninstall raise-cli

Esto elimina solo la herramienta global rai. Tus proyectos, gobernanza y directorios .raise/ quedan intactos.

Global vs por-proyecto — ¿cuál estoy corriendo?¶

Si tienes ambos — un rai global y un .venv de proyecto — un venv activado tiene precedencia. Verifica cuál está activo:

which rai                 # ~/.local/bin/rai → herramienta global
                          # ./.venv/bin/rai → venv por proyecto

Para usar siempre la herramienta global, no actives el venv del proyecto (o desactívalo con deactivate).

Problemas conocidos¶

Problema	Causa	Solución
`rai` no se encuentra tras instalar	`~/.local/bin` no está en el PATH	Corre `uv tool update-shell` y abre una terminal nueva
La instalación resuelve una versión vieja	Caché de uv	Agrega `--reinstall` al comando `uv tool install`
`No matching distribution` justo tras un release	Lag de indexado del registry (~30–60s)	Espera un minuto y reintenta
El proyecto sigue usando RaiSE viejo	Un `.venv` de proyecto está tapando la herramienta global	`deactivate` el venv, o elimina `.venv` si quieres global en todos lados

Siguientes pasos¶

Abre Claude Code en cualquier directorio de proyecto
Corre /rai-welcome para onboarding guiado
Corre /rai-session-start para empezar tu primera sesión