Guía de Instalación¶

Instalación Rápida (recomendada)¶

Un solo comando instala RaiSE en un entorno virtual por proyecto. Cada proyecto obtiene su propia versión — puedes ejecutar v2.4 y v3.0 en paralelo.

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"

Para el canal alpha o una versión específica, descarga el script y ejecútalo con flags:

irm https://docs.raiseframework.ai/install.ps1 -OutFile install.ps1
.\install.ps1 -Alpha                # última alpha desde GitLab registry
.\install.ps1 -Alpha -Version 3.1.0a7 # alpha específica desde GitLab registry
.\install.ps1 -DryRun              # vista previa sin cambios

Opciones¶

Flag	Linux/macOS	Windows	Efecto
Canal alpha	`bash -s -- --alpha`	`-Alpha`	Instala la última alpha desde GitLab registry
Alpha específica	`bash -s -- --alpha --version 3.1.0a7`	`-Alpha -Version 3.1.0a7`	Fija una alpha exacta desde GitLab registry
Stable específica	`bash -s -- --version 3.1.0`	`-Version 3.1.0`	Fija una versión estable desde PyPI
Simulación	`bash -s -- --dry-run`	`-DryRun`	Muestra qué ocurriría

Ejemplos:

# Última versión estable
curl -LsSf https://docs.raiseframework.ai/install.sh | bash

# Última alpha desde GitLab registry
curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --alpha

# Alpha específica desde GitLab registry
curl -LsSf https://docs.raiseframework.ai/install.sh | bash -s -- --alpha --version 3.1.0a7

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

# Windows — alpha específica desde GitLab registry
.\install.ps1 -Alpha -Version 3.1.0a7

Después de instalar, activa el entorno virtual:

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

Requisitos Previos¶

Git — el único requisito obligatorio. El script se encarga del resto.
Claude Code — instalar desde Anthropic para usar los flujos de trabajo de RaiSE.

El script instala uv y Python 3.13 automáticamente si no están disponibles — no es necesario instalarlos previamente.

Qué hace el script¶

Verifica que Python 3.12+ esté disponible
Instala uv si no está presente
Crea un .venv en el directorio del proyecto (o reutiliza uno existente)
Instala raise-cli desde PyPI para versiones estables, o desde GitLab alpha registry con --alpha
Verifica la instalación
Ejecuta la migración de datos si se actualiza desde una versión anterior

Aislamiento por proyecto¶

A diferencia de instalaciones globales (pipx), este enfoque le da a cada proyecto su propia versión de RaiSE:

~/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

Sin conflictos, sin estado global, sin sorpresas.

¿Quieres un solo rai para todos los repos?

Los alpha testers que trabajan en muchos repositorios pueden instalar RaiSE a nivel de sistema con uv tool — un único rai en tu PATH, sin venv por proyecto. Ver Instalación Global (Todos los Repos).

Instalación manual¶

Si prefieres no usar el script:

cd your-project
pip install uv              # si no tienes uv
uv venv                     # crear entorno virtual
uv pip install raise-cli    # última versión estable
# 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

Configuración para Desarrollo (desde el código fuente)¶

Para contribuidores que trabajan en raise-commons:

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

Actualización¶

¿Actualizando desde 2.x?

RaiSE 3.0 incluye cambios incompatibles en archivos de configuración, almacenamiento y comandos CLI. Consulta la guía de migración antes de actualizar.

Ejecuta el mismo script de instalación nuevamente en el directorio del proyecto — es idempotente:

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

Para usuarios alpha, usa explícitamente el canal GitLab:

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

Para actualizar a una versión estable específica:

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

Desinstalación¶

RaiSE se instala por proyecto en un directorio .venv. Para eliminarlo:

Linux / macOS¶

cd your-project
rm -rf .venv

Windows¶

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

# Eliminar también el shim global (opcional):
Remove-Item "$HOME\.local\bin\rai.cmd"

Esto no modifica los archivos del proyecto, la gobernanza ni el directorio .raise/ — solo se elimina el entorno virtual de Python.

Problemas Conocidos¶

Problema	Causa	Solución
`python3` apunta a la versión incorrecta	shim de asdf/pyenv	Usa `which python3` para verificar; usa el Python del sistema o configura tu gestor de versiones
`uv` no se encuentra tras la instalación	PATH no actualizado	Abre una terminal nueva y vuelve a ejecutar
`rai` no se encuentra tras la instalación	entorno virtual no activado	Ejecuta `source .venv/bin/activate`
Errores de importación tras la actualización	entorno virtual obsoleto	Elimina `.venv` y ejecuta el script de instalación nuevamente
`rai doctor` muestra advertencias	Configuración faltante	Ejecuta `rai doctor --fix` para aplicar reparaciones automáticas

Próximos Pasos¶

Tras la instalación:

Abre Claude Code en el directorio del proyecto
Ejecuta /rai-welcome para el onboarding guiado
Ejecuta /rai-session-start para comenzar tu primera sesión