Instalación

Theus CLI se instala con una línea. El instalador oficial detecta tu plataforma, instala Bun por ti si falta (verificando su checksum SHA-256), descarga el último release verificado e instala el comando theus en tu PATH.

Requisitos

Sistema: macOS o Linux, en x64 o arm64. En Windows, mira más abajo.
Runtime: Bun — el CLI es un bundle con target bun, no corre bajo Node. No necesitas instalarlo tú: si falta, el instalador oficial descarga el binario oficial de Bun y verifica su checksum SHA-256 antes de instalarlo (nunca ejecuta instaladores remotos por tubería).
Herramientas base: curl y tar (presentes en casi cualquier sistema). El modo source requiere además git.

Instalador oficial (recomendado)

curl -fsSL https://theus.pe/install.sh | bash
theus --version

Qué hace el instalador, paso a paso:

Detecta tu plataforma (macOS/Linux, x64/arm64; en Linux distingue musl y CPUs sin AVX2 para elegir el build correcto de Bun).
Verifica Bun; si falta, descarga el binario oficial, comprueba su SHA-256 contra el archivo de sumas publicado y lo instala en ~/.bun/bin.
Descarga el tarball del último release — primario desde theus.pe/dl (funciona aunque el repositorio de código sea privado), con GitHub Releases como respaldo automático — y verifica su SHA-256 contra el archivo SHA256SUMS del release. Si el checksum no coincide, la instalación se aborta.
Instala Theus en ~/.theus/app y enlaza el comando theus en el primer directorio escribible de tu PATH (~/.local/bin, /usr/local/bin o ~/.bun/bin; si ninguno existe, crea ~/.local/bin). Si ese directorio no está en tu PATH, te lo advierte con la línea exacta que debes añadir a tu shell.

El instalador es idempotente: para actualizar Theus, vuelve a ejecutar la misma línea. Descarga el último release, reemplaza ~/.theus/app y deja el enlace apuntando a la versión nueva.

Variables del instalador

Todas son opcionales; se exportan antes de ejecutar el script:

Variable	Uso	Por defecto
`THEUS_INSTALL_MODE`	`auto` \| `release` \| `source`	`auto`
`THEUS_VERSION`	tag del release, p.ej. `v0.1.3`	`latest`
`THEUS_HOME`	carpeta de instalación	`~/.theus/app`
`THEUS_BIN_DIR`	dónde enlazar el comando `theus`	primer directorio escribible del PATH
`THEUS_DL_BASE`	origen primario de los tarballs	`https://theus.pe/dl`
`THEUS_REF` / `THEUS_COMMIT`	rama/tag y commit exacto a fijar (solo modo `source`)	`main` / HEAD del ref

Instalación desde el código fuente

Con THEUS_INSTALL_MODE=source el instalador clona el repositorio, instala dependencias con bun install y compila el bundle localmente con bun run build. Para instalaciones reproducibles, fija el commit exacto:

THEUS_INSTALL_MODE=source THEUS_COMMIT=<sha> \
  bash -c "$(curl -fsSL https://theus.pe/install.sh)"

En modo auto (el predeterminado), si no hay release descargable el instalador cae solo al modo source.

Instalación vía npm

El paquete theus-cli publica el bundle compilado con el binario theus:

npm install -g theus-cli
theus --version

También puedes probarlo sin instalar globalmente:

npx theus-cli

La ruta npm también requiere Bun en tu PATH (el entrypoint corre con #!/usr/bin/env bun) y, a diferencia del instalador oficial, no lo instala por ti. Si no tienes Bun, usa el instalador oficial o instala Bun primero.

Windows

En Windows también se instala con un solo comando. Tienes dos caminos y conviene saber qué esperar de cada uno.

Windows nativo (PowerShell)

powershell -c "irm https://theus.pe/install.ps1 | iex"

Hace lo mismo que el instalador de macOS y Linux, con las mismas garantías: instala Bun si te falta (verificando su checksum SHA-256), descarga el último release verificado, deja el comando theus en tu PATH y añade Ñaupa. Es idempotente: relánzalo cuando quieras para actualizar.

Cada cambio del instalador se ejecuta en una máquina Windows limpia, en x64 y arm64, comprobando que instala, que theus queda en el PATH, que responde, y que relanzarlo encima funciona.

¿theus «no se reconoce» en la terminal de tu editor? No es un problema de permisos: el comando se instala en tu PATH de usuario, sin administrador. Los editores basados en VS Code —incluidos Cursor y Antigravity— cachean el PATH al arrancar, así que una terminal integrada nueva no ve el comando recién instalado hasta que reinicias el editor por completo (no basta con abrir otra pestaña de terminal). Reinícialo y theus resuelve igual en cmd, PowerShell y la terminal integrada.

¿«No se puede cargar theus.ps1 porque la ejecución de scripts está deshabilitada» (PSSecurityException)? Instalaciones anteriores al 30 de julio de 2026 dejaban, junto al theus.cmd, un segundo lanzador theus.ps1; PowerShell le da prioridad y la directiva de ejecución por defecto de Windows lo bloquea. No toques la directiva de seguridad: relanza el instalador (ya no lo crea y borra el antiguo), o elimínalo a mano: Remove-Item "$env:LOCALAPPDATA\Theus\bin\theus.ps1". Con eso theus vuelve a resolver al .cmd, que funciona en cualquier terminal.

En PowerShell, curl no es curl Windows PowerShell trae curl como alias de Invoke-WebRequest, así que los comandos curl … | bash de esta documentación (pensados para macOS/Linux) fallan ahí con errores como «Falta un argumento para el parámetro 'SessionVariable'». En Windows usa siempre los comandos irm … | iex de esta sección; si necesitas el curl real, escribe curl.exe.

Si prefieres npm y ya tienes Bun:

npm install -g theus-cli

Alcance de lo verificado nuestras pruebas comprueban que instala y arranca. La sesión interactiva completa en Windows nativo todavía no está cubierta por ellas, así que puedes encontrarte detalles ásperos. Si algo no va, cuéntanoslo.

¿Se abre el mapa del proyecto clásico y no el grafo 3D? Hasta el 26 de julio de 2026, el instalador de Windows omitía Ñaupa en todas las instalaciones: al paquete le faltaba su huella de verificación en el canal de descargas y, sin poder verificarlo, se salta por seguridad (verás un aviso amarillo del tipo «No hay entrada de checksum»). Ya está corregido. Relanza el instalador y abre una terminal nueva; Theus monta el motor y su mapa 3D en la siguiente sesión. Si aun así no aparece, apunta THEUS_NAUPA_BIN al binario (%LOCALAPPDATA%\Theus\bin\naupa.exe) y arranca Theus con --debug para ver si el problema es que no lo encuentra o que su mapa no respondió a tiempo.

WSL (el camino más rodado)

Dentro de WSL, Theus es una instalación de Linux normal: funciona el instalador oficial, con Bun y Ñaupa incluidos.

curl -fsSL https://theus.pe/install.sh | bash

Es la opción recomendada si quieres el camino más probado o prefieres no gestionar Bun a mano.

Primer arranque

cd /ruta/de/tu/proyecto
theus                    # sesión interactiva
theus -p "tu prompt"     # modo no interactivo
theus --help             # ayuda del CLI

Al iniciar dentro de un proyecto, Theus indexa archivos y símbolos localmente, construye el grafo del código, guarda índice y memoria en ~/.theus/knowledge/ y expone un dashboard visual en 127.0.0.1. Dos variables útiles para ese arranque:

Variable	Efecto
`THEUS_NO_OPEN_DASHBOARD=1`	Levanta la API local sin abrir el navegador.
`THEUS_NO_PROJECT_INTELLIGENCE=1`	No levanta índice, API local ni dashboard para esa sesión.

Interfaz terminal y accesibilidad

Desde v0.2.62, el splash, el menú y las pantallas de configuración cambian de densidad según el ancho y la altura disponibles. Las acciones principales siguen accesibles incluso en una terminal de 40×14; cualquier tecla omite el splash.

Variable	Efecto
`NO_COLOR=1`	Elimina los colores decorativos y conserva la jerarquía mediante texto y símbolos.
`THEUS_CODE_REDUCE_MOTION=1`	Detiene animaciones recurrentes y acorta la transición inicial.
`THEUS_CODE_ACCESSIBILITY=1`	Activa la política accesible de movimiento y presentación.
`THEUS_FORCE_ASCII=1`	Usa símbolos compatibles con terminales que no representan bien Unicode.

La pantalla de acceso también muestra la frontera efectiva del modelo: local para endpoints de este equipo, remoto para un proveedor de red y por confirmar si todavía no existe una configuración resoluble. El índice del proyecto y la memoria permanecen en ~/.theus/knowledge/; el contexto enviado al modelo sigue la frontera indicada en pantalla.

Conectar tu cuenta: `theus login`

theus login conecta el CLI a tu suscripción de theus.pe con OAuth y PKCE. El flujo completo:

El CLI levanta un callback local en 127.0.0.1 y abre el navegador en la página de autorización de theus.pe.
Inicias sesión en la web — por magic link a tu correo, o con los proveedores de identidad que la web tenga habilitados — y autorizas al CLI.
El CLI intercambia el código por un token (PKCE, /v1/oauth/token), consulta tu perfil y plan, y crea automáticamente una API key de Theus para el CLI.
Deja instalado el proveedor theus-official (endpoint https://api.theus.pe/v1, con el modelo orquestador por defecto) en ~/.theus/providers.json, y guarda los datos de sesión en ~/.theus/session.json.

Al terminar verás tu plan, la URL de tu consola y el sufijo de la API key activa. A partir de ahí basta con theus: no exportas ninguna variable ni pegas ninguna key.

theus login                      # flujo normal (abre el navegador)
theus login --no-open            # imprime la URL de login en vez de abrir el navegador
theus login --token <api_key>    # instala una API key existente sin pasar por el navegador

theus signin y theus entrar son alias de theus login. El flujo de navegador expira a los 5 minutos; si se agota, vuelve a ejecutarlo. Con --token la cuenta se trata como plan free hasta que el servidor confirme una suscripción.

Actualizar

# instalación con el instalador oficial (macOS/Linux)
curl -fsSL https://theus.pe/install.sh | bash

# Windows (PowerShell) — el mismo instalador es idempotente
powershell -c "irm https://theus.pe/install.ps1 | iex"

# instalación vía npm
npm update -g theus-cli

Dentro de una sesión, theus update actualiza el CLI y también Ñaupa en un solo paso.

Desinstalar

El instalador oficial solo toca tres lugares: el enlace theus, la app en ~/.theus/app y (si lo instaló) Bun en ~/.bun. Para desinstalar:

rm "$(command -v theus)"    # quita el enlace del PATH
rm -rf ~/.theus/app         # quita la aplicación

Tu configuración, proveedores, sesión y memoria de proyectos viven en el resto de ~/.theus/ (providers.json, session.json, knowledge/…). Consérvala si piensas reinstalar; para borrar todo rastro:

rm -rf ~/.theus

Si instalaste por npm: npm uninstall -g theus-cli.