> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexusproject.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Instala el CLI de Nexus y haz tu primer switch en 5 minutos.

## Paso 1: Descargar e instalar el CLI

Ya no es necesario clonar el repositorio ni tener Go instalado. Simplemente descarga el archivo precompilado.

1. Ve a la [página de Releases en GitHub](https://github.com/Epigibson/Nexus/releases) y descarga el archivo para tu sistema operativo.
2. Extrae el archivo (si viene comprimido) y renómbralo a `nexus` (o `nexus.exe` en Windows).
3. Configúralo en tu sistema:

<Tabs>
  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    # Instalar globalmente
    $installDir = "$env:USERPROFILE\.nexus\bin"
    New-Item -ItemType Directory -Force -Path $installDir | Out-Null
    # Mueve el nexus.exe descargado a esa carpeta
    Move-Item nexus.exe "$installDir\nexus.exe" -Force

    # Agregar al PATH (permanente, solo la primera vez)
    $currentPath = [System.Environment]::GetEnvironmentVariable("Path", "User")
    if ($currentPath -notlike "*\.nexus\bin*") {
        [System.Environment]::SetEnvironmentVariable("Path", "$currentPath;$installDir", "User")
    }
    ```

    <Warning>
      Reinicia tu terminal después de agregar al PATH para que tome efecto.
    </Warning>
  </Tab>

  <Tab title="macOS / Linux">
    ```bash theme={null}
    # Dar permisos de ejecución y mover al PATH
    chmod +x nexus
    sudo mv nexus /usr/local/bin/

    # Si no tienes permisos de sudo, puedes moverlo a ~/.nexus/bin
    # mkdir -p ~/.nexus/bin
    # mv nexus ~/.nexus/bin/
    # echo 'export PATH="$HOME/.nexus/bin:$PATH"' >> ~/.zshrc
    # source ~/.zshrc
    ```
  </Tab>
</Tabs>

Verifica la instalación:

```bash theme={null}
nexus version
# → Nexus v1.1.1
```

<Check>
  Si ves `Nexus v1.1.1`, la instalación fue exitosa.
</Check>

## Paso 2: Crear cuenta y API Key

<Steps>
  <Step title="Registrarte en el Dashboard">
    Ve a [nexus-production-a677.up.railway.app](https://nexus-production-a677.up.railway.app) y crea tu cuenta.
  </Step>

  <Step title="Crear un proyecto">
    En el dashboard, crea un proyecto y agrega entornos (development, staging, production). Configura los CLI profiles (GitHub, AWS, etc.) y variables de entorno (API keys, secrets).
  </Step>

  <Step title="Generar una API Key">
    Ve a **Configuración → API Keys → Generar Nueva Key**.

    <Warning>
      La key completa (`ag_live_...`) solo se muestra **una vez**. Cópiala antes de cerrar el modal.
    </Warning>
  </Step>
</Steps>

## Paso 3: Conectar el CLI

```bash theme={null}
# Autenticarte con tu API key
nexus login
```

```
🔐 Nexus CLI — Login
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Generate an API key from your Dashboard:
  → Settings → API Keys → Generate New Key

Paste your API key: ag_live_xxxxxxxxxx...

✅ Authenticated as Ricardo (hackminor@live.com.mx)
📋 Plan: pro

  📦 Syncing projects to local cache...
  ✅ 3 projects cached for instant switching
```

<Tip>
  Al hacer login, el CLI automáticamente descarga y cachea todos tus proyectos.
  Esto permite que los switches futuros sean instantáneos (\~5 segundos).
</Tip>

## Paso 4: ¡Hacer switch!

Tus proyectos ya están cacheados localmente. Ahora solo cambia de contexto:

```bash theme={null}
# Desde CUALQUIER directorio
nexus switch auto-hotel-luxor --env production
```

```
    _   __
   / | / /__  _  ____  _______
  /  |/ / _ \| |/_/ / / / ___/
 / /|  /  __/>  </ /_/ (__  )
/_/ |_/\___/_/|_|\__,_/____/
  📦 Using cached config for 'auto-hotel-luxor'
  🧩 Skills: 12/12 enabled
  ─────────────────────────────────────────
  ✨ cli:aws — Switched aws → 'luxor-prod' (2108ms)
  ✨ cli:gh — Switched gh → 'epigibson' (617ms)
  ✨ cli:supabase — Switched supabase → linked (4002ms)
  ✨ ⚡ Parallel Switch — Executed 11 skills in parallel (0ms)
  ─────────────────────────────────────────

  ✨ Context switch complete! (5467ms)
```

<Check>
  Ahora tu GitHub CLI, AWS, Supabase, Vercel, Expo y todas las variables de entorno están configuradas para el proyecto correcto. Todo en \~5 segundos.
</Check>

### Actualizar cache después de cambios en el dashboard

Si modificaste variables de entorno, CLI profiles o hooks en el dashboard:

```bash theme={null}
# Sincronizar un proyecto específico
nexus sync auto-hotel-luxor

# O sincronizar todos
nexus sync --all
```

## Comandos disponibles

| Comando                               | Descripción                                                          |
| ------------------------------------- | -------------------------------------------------------------------- |
| `nexus login`                         | Autenticarte con tu API key (auto-sync incluido)                     |
| `nexus sync [slug]`                   | Sincronizar proyectos del cloud al cache local                       |
| `nexus sync --all`                    | Sincronizar todos los proyectos                                      |
| `nexus switch [proyecto] --env <env>` | Cambiar contexto completo (\~5s)                                     |
| `nexus switch [proyecto] --refresh`   | Switch con descarga fresca del API                                   |
| `nexus current`                       | Ver el contexto activo global y detectar desalineaciones en la shell |
| `nexus status`                        | Ver estado de conexión al servidor API y proyectos                   |
| `nexus list`                          | Listar todos los proyectos locales descubiertos                      |
| `nexus profiles [proyecto]`           | Ver perfiles activos del sistema o configuraciones de un proyecto    |
| `nexus init`                          | Inicializar una plantilla de `nexus.yaml` local (no interactiva)     |
| `nexus setup-shell`                   | Instalar wrapper para sincronizar variables en la shell activa       |
| `nexus pull <slug>`                   | Descargar configuración del cloud al archivo `nexus.yaml` local      |
| `nexus logout`                        | Eliminar credenciales guardadas localmente                           |
| `nexus version`                       | Ver la versión del CLI                                               |

## Troubleshooting

<AccordionGroup>
  <Accordion title="'nexus' no se reconoce como comando">
    Asegúrate de que `~/.nexus/bin` está en tu PATH y que reiniciaste la terminal después de instalarlo.

    **Windows**: Verifica con `$env:Path -split ";" | Where-Object { $_ -like "*nexus*" }`

    **macOS/Linux**: Verifica con `echo $PATH | tr ':' '\n' | grep nexus`
  </Accordion>

  <Accordion title="Authentication failed al hacer login">
    * Verifica que copiaste la API key completa (empieza con `ag_live_`)
    * Genera una nueva key desde el dashboard si la anterior expiró
    * Verifica conexión a internet
  </Accordion>

  <Accordion title="Error 500 al generar API Key">
    Si ves un error interno al crear la key, espera 2 minutos para que Railway redeployee tras un push reciente.
  </Accordion>
</AccordionGroup>