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.
En esta página
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
curl -fsSL https://sypnia.com/install.sh | shLinux y macOS, x86-64 y ARM. Se instala en ~/.local/bin/sypnia.
Docker
docker run --rm ghcr.io/sypnia/sypnia:1 versionLa imagen trae el mismo binario. Su comando por defecto es serve.
npm
npx sypnia versionPara proyectos de JavaScript y para CI. El paquete sypnia descarga el binario de tu plataforma.
Compruébalo:
sypnia versionsypnia 1.0.0 (a1c9e3f, 2026-03-01) schema 12Di 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. |
export SYPNIA_API_TOKEN=<tu token de API>
sypnia problemsexport SYPNIA_BASE_URL=https://sypnia.example.com
export SYPNIA_API_TOKEN=<tu token de API>
sypnia problemsLa 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:
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
- Cada comando con sus opciones, ejemplos, salida y códigos de salida.
- Cada ajuste que leen los comandos del motor.
- Dónde poner
sypnia sourcemaps uploaden tu pipeline.