# Referencia de la CLI

> El comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.

Aplica a: el motor de Sypnia (código abierto, en tu propia infraestructura) y Sypnia Cloud (servicio pago). Estado: al lanzar.  
Fuente: https://docs.sypnia.com/es/cli/

Para agentes: Resumen de la CLI sypnia: un binario que es a la vez el motor (serve, aggregate, migrate, doctor) y su cliente (project, key, token, sourcemaps upload, problems, problem); formas de instalarlo, variables de entorno, códigos de salida.

**\[Motor]** **\[Nube]** `sypnia` es un solo programa. Es el motor mismo (`sypnia serve`) y la herramienta que usas a su alrededor: crear proyectos y tokens, subir source maps desde tu build, leer problemas desde una terminal.

| Quieres                                            | Comando                                          | Funciona con                                                     |
| -------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------- |
| Correr el motor en tu propio servidor              | `sypnia serve`, `migrate`, `doctor`, `aggregate` | Un motor alojado por ti                                          |
| Crear proyectos, llaves de ingesta y tokens de API | `sypnia project`, `key`, `token`                 | Un motor alojado por ti. `key` y `token` también en Sypnia Cloud |
| Subir source maps en tu build                      | `sypnia sourcemaps upload`                       | Los dos                                                          |
| Ver qué está fallando, desde una terminal          | `sypnia problems`, `sypnia problem`              | Los dos                                                          |

Si usas Sypnia Cloud y un SDK de framework como `@sypnia/next`, puede que nunca necesites la CLI: el SDK sube los source maps por su cuenta y la app hace el resto.

## Instalar

**Script**

```bash
curl -fsSL https://sypnia.com/install.sh | sh
```

Linux y macOS, x86-64 y ARM. Se instala en `~/.local/bin/sypnia`.

**Docker**

```bash
docker run --rm ghcr.io/sypnia/sypnia:1 version
```

La imagen trae el mismo binario. Su comando por defecto es `serve`.

**npm**

```bash
npx sypnia version
```

Para proyectos de JavaScript y para CI. El paquete `sypnia` descarga el binario de tu plataforma.

Compruébalo:

```bash
sypnia version
```

**Deberías ver:**`sypnia 1.0.0 (a1c9e3f, 2026-03-01) schema 12`

## Di dónde y quién

Los comandos que hablan con la API necesitan saber cuál motor y cuál credencial. Los leen del entorno.

| Variable            | La usan       | Qué es                                                                                                                                                                                                      |
| ------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SYPNIA_BASE_URL`   | admin, client | Dónde está la API. Para un motor alojado por ti, su URL base, sin `/v1`. En la máquina del propio motor es además el ajuste que dice la dirección pública del motor. Por defecto: `https://api.sypnia.com`. |
| `SYPNIA_API_TOKEN`  | admin, client | Un token de API (`sps_…`). `read` para `problems` y `problem`; `admin` para `sourcemaps upload`, `key` y `token`.                                                                                           |
| `SYPNIA_ROOT_TOKEN` | admin         | El token raíz de un motor alojado por ti. Hace falta para `project create` y `project delete`. Cuando los dos tokens están definidos, los comandos de administración usan el token raíz.                    |
| `SYPNIA_PROJECT`    | admin, client | El id o el slug de un proyecto. Solo hace falta con el token raíz; un token de API ya pertenece a un proyecto. Igual que `--project`.                                                                       |
| `SYPNIA_CONFIG`     | engine        | Ruta del archivo de configuración. Igual que `--config`.                                                                                                                                                    |
| `SYPNIA_…`          | engine        | Cada ajuste del motor. Mira la referencia de configuración.                                                                                                                                                 |

`Contra Sypnia Cloud`

```bash
export SYPNIA_API_TOKEN=<tu token de API>
sypnia problems
```

`Contra tu propio motor`

```bash
export SYPNIA_BASE_URL=https://sypnia.example.com
export SYPNIA_API_TOKEN=<tu token de API>
sypnia problems
```

La CLI nunca guarda un token. No tiene comando `login` y no escribe ningún archivo de configuración propio.

## Salida

Por defecto la CLI imprime para personas: tablas, colores, frases cortas. Agrega `--json` a cualquier comando que lea datos e imprime exactamente lo que devuelve la API HTTP, para que un script lo use:

```bash
sypnia problems --json | jq '.data[].slug'
```

Los errores van a la salida de error, en una línea: el `code` y el `message` de la API.

## Códigos de salida

Los mismos en todos los comandos, para que un script sepa qué salió mal.

| Código | Qué significa                                                                                                                                          |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `0`    | Todo salió bien.                                                                                                                                       |
| `1`    | El comando corrió y la respuesta es no: una comprobación de `doctor` falló, una subida falló, la API respondió un error que no está en esta lista.     |
| `2`    | Mal uso: una opción desconocida, un argumento que falta. No se hizo nada.                                                                              |
| `3`    | Mala configuración: falta un ajuste obligatorio o no es válido, o el esquema de la base de datos es más viejo que el binario (corre `sypnia migrate`). |
| `4`    | No se pudo llegar a algo: la base de datos, el almacenamiento, la API o la red. Se puede reintentar sin riesgo.                                        |
| `5`    | No permitido: falta el token, es desconocido, está revocado o no tiene el permiso (`401`, `403`).                                                      |
| `6`    | No existe: no hay tal proyecto, problema, llave o token (`404`).                                                                                       |

## Comandos
