Comandos
Cada comando del binario sypnia, con sus opciones, ejemplos, salida y códigos de salida.
En esta página
- Opciones de todos los comandos
- Correr el motor
- sypnia serve
- sypnia aggregate
- sypnia migrate
- sypnia doctor
- Proyectos, llaves y tokens
- sypnia project create
- sypnia project list
- sypnia project delete
- sypnia key create
- sypnia key list
- sypnia key revoke
- sypnia token create
- sypnia token list
- sypnia token revoke
- Trabajar con un proyecto
- sypnia sourcemaps upload
- sypnia problems
- sypnia problem
- sypnia version
Cada comando de sypnia, en tres grupos. Cada uno dice dónde funciona: Motor en un motor alojado por ti, Nube contra Sypnia Cloud. Cómo instalar el binario, las variables que lee y qué significan sus códigos de salida está en el resumen de la CLI.
| Comando | Qué hace |
|---|---|
sypnia serve | Corre el motor |
sypnia aggregate | Procesa lo que ha llegado, una vez |
sypnia migrate | Crea o actualiza las tablas de la base de datos |
sypnia doctor | Comprueba que el motor está bien configurado |
sypnia project create, list, delete | Administra proyectos |
sypnia key create, list, revoke | Administra llaves de ingesta |
sypnia token create, list, revoke | Administra tokens de API |
sypnia sourcemaps upload | Sube los source maps de un build y registra su versión |
sypnia problems | Lista los problemas |
sypnia problem | Muestra un problema, o imprime su prompt listo |
sypnia version | Imprime la versión |
Los nombres de los comandos y de las opciones, y lo que imprimen, están en inglés.
Opciones de todos los comandos
Opciones
-
--jsonbooleanImprime el resultado en JSON, con la misma forma que la API HTTP. Las tablas y los colores son para personas; los scripts deben usar esto.
-
--quiet, -qbooleanImprime solo los errores.
-
--no-colorbooleanSin colores. También cuando
NO_COLORestá definida o la salida no es una terminal. -
--config <file>pathSolo comandos del motor. Un archivo de configuración en TOML. Las variables de entorno ganan sobre el archivo. También
SYPNIA_CONFIG. -
--help, -hbooleanExplica el comando y sus opciones.
Correr el motor
Estos comandos corren donde corre el motor. Leen la configuración del motor (mira la referencia de configuración) y necesitan la base de datos y el almacenamiento.
Corre el motor.
Arranca todo en un solo proceso: la API HTTP, los endpoints de ingesta y de OTLP, el servidor MCP, la Consola y el trabajador que procesa lo que llega (problemas, sesiones, números, comprobaciones de disponibilidad, alertas, webhooks, retención). Es el motor completo para un despliegue con Docker.
El trabajador busca fallas nuevas cada SYPNIA_PROCESSING_INTERVAL_SECONDS (30 por defecto), y de inmediato
cuando la ingesta del mismo proceso escribió eventos nuevos, así un problema nuevo aparece en menos de 2
minutos. Todo lo demás lo cuenta cada 5 minutos.
Se detiene con orden al recibir SIGTERM: termina las peticiones en curso, hasta 20 segundos, y el trabajador
termina su paso actual. El procesamiento es idempotente, así que un trabajador que muere no pierde nada.
Para repartir la carga, corre varios procesos con roles distintos contra la misma base de datos y el mismo bucket. La plantilla de AWS lo hace con funciones; cada función es este mismo binario con un rol.
Opciones
-
--listen <address>stringLa dirección y el puerto donde escucha. También
SYPNIA_LISTEN.Por defecto:
0.0.0.0:8080 -
--role <role>all | ingest | api | workeringest: solo los endpoints de ingesta y de OTLP.api: solo la API, el servidor MCP y la Consola.worker: solo el procesamiento, sin HTTP salvo/healthz.all: todo. TambiénSYPNIA_ROLE.Por defecto:
all
Correr el motor completo
sypnia servesypnia 1.0.0 role=all listen=0.0.0.0:8080
database ok postgres 16.4, schema 12
storage ok s3://sypnia-shop (us-east-1)
ai off (SYPNIA_AI_PROVIDER=none)
ready https://sypnia.example.comCorrer la ingesta y el trabajador por separado
sypnia serve --role ingest --listen 0.0.0.0:8081
sypnia serve --role workerCódigos de salida: 0, 3, 4.
Procesa lo que ha llegado, una vez.
Corre una pasada del trabajador y termina: lee los eventos crudos que llegaron desde la pasada anterior, agrupa
las fallas en problemas, arma las sesiones, actualiza los números, corre las comprobaciones de disponibilidad
que tocan, crea alertas y envía webhooks. sypnia serve hace esto solo cada 30 segundos; este comando solo
hace falta para procesar desde tu propio programador de tareas (córrelo cada minuto), o para volver a procesar
un rango de tiempo con --from y --to.
Volver a procesar un rango es seguro, y nada se cuenta dos veces. Los números que se guardan por hora (rendimiento de páginas y de la API) se reemplazan con lo que dan los eventos crudos de esa hora. Los contadores que solo suman (los totales de una sesión, los clics por día, el uso, las ocurrencias de un problema) no se reemplazan: el motor lleva un registro de los objetos crudos que ya sumó, y suma cada uno una sola vez.
Opciones
-
--project <id or slug>stringSolo este proyecto. Todos si se omite.
-
--from <time>stringVuelve a procesar desde este momento: una fecha ISO 8601 o un valor relativo (
6h,2d). Necesita--to, o toma ahora. -
--to <time>stringFin del rango que se vuelve a procesar.
-
--task <task>all | events | uptime | alerts | webhooks | retention | suggestionsCorre solo una parte de la pasada.
suggestionscorre ahora las sugerencias semanales, para la semana que terminó.Por defecto:
all -
--watchbooleanSigue corriendo y hace otra pasada cada
SYPNIA_PROCESSING_INTERVAL_SECONDS. Igual queserve --role workersin/healthz.
Una pasada
sypnia aggregateshop events 412 -> 2 sessions, 1 problem (0 new), 3 routes 0.8 s
shop uptime 1 check, 0 down
shop alerts 0 created, webhooks 0 sent
done in 1.1 s, data through 2026-03-12T10:34:10ZVolver a procesar ayer para un proyecto
sypnia aggregate --project shop --from 2026-03-11T00:00:00Z --to 2026-03-12T00:00:00ZCódigos de salida: 0, 1, 3, 4.
Crea o actualiza las tablas de la base de datos.
Aplica las migraciones de base de datos que trae el binario, en orden, cada una en una transacción. Córrelo una vez después de instalar y después de cada actualización, antes de arrancar la versión nueva. Las migraciones solo agregan: un binario más viejo sigue funcionando contra un esquema más nuevo, así que puedes actualizar sin detener nada.
sypnia serve se niega a arrancar contra un esquema más viejo que él (código de salida 3), salvo que
SYPNIA_AUTO_MIGRATE sea true.
Opciones
-
--statusbooleanMuestra qué migraciones están aplicadas y cuáles faltan, y no cambia nada.
-
--dry-runbooleanImprime el SQL que correría, y no cambia nada.
Aplicar las migraciones pendientes
sypnia migrateschema 11 -> 12
applied 0012_suggestions (0.2 s)
database is up to dateCódigos de salida: 0, 3, 4.
Comprueba que el motor está bien configurado.
Lee la configuración y prueba cada pieza de la que depende el motor, una línea por cada una: los ajustes
mismos, la base de datos (alcanzable, Postgres 15 o posterior, esquema al día), el almacenamiento (escribe, lee
y borra un objeto de prueba, y firma un enlace), la dirección pública, el proveedor de IA (una petición pequeña
al modelo que configuraste) y el webhook de alertas (envía un ping firmado). Cada falla dice qué está mal y
qué ajuste cambiar.
Córrelo después de instalar, después de cambiar un ajuste, y antes que nada cuando algo no funcione. La
comprobación de IA le envía unos 20 tokens a tu proveedor; sáltala con --skip ai.
Opciones
-
--only <checks>stringComprobaciones que correr, separadas por comas:
config,database,storage,address,ai,webhook,clock. -
--skip <checks>stringComprobaciones que saltar, separadas por comas.
Comprobar todo
sypnia doctorconfig ok 14 settings read, 0 unknown
database ok postgres 16.4, schema 12 (up to date), 3 ms
storage ok s3://sypnia-shop: put, get, delete, presign
address ok https://sypnia.example.com/healthz answered 200
ai ok openrouter, model <model>: answered in 0.9 s
webhook skip SYPNIA_ALERT_WEBHOOK_URL is not set (alerts are recorded only)
clock ok 0.2 s from the database's clock
all checks passedCuando el nombre del modelo está mal
sypnia doctor --only aiai FAIL openrouter answered 404: no model named "<model>"
Set SYPNIA_AI_MODEL to a model your provider offers.
1 check failedCódigos de salida: 0, 1, 3.
Proyectos, llaves y tokens
Estos comandos llaman a la API HTTP, así que funcionan desde cualquier máquina. En un motor alojado por ti usa el token raíz (SYPNIA_ROOT_TOKEN) y di cuál motor con SYPNIA_BASE_URL. En Sypnia Cloud, key y token funcionan con un token de API admin; los proyectos se crean en la app.
Crea un proyecto.
Crea un proyecto e imprime su primera llave de ingesta. Solo en motores alojados por ti; necesita el token raíz. En Sypnia Cloud los proyectos se crean en la app.
Llama a: POST /v1/projects
Opciones
-
--name <name>string obligatorioEl nombre que ve la gente.
-
--slug <slug>stringUn nombre corto para URLs y comandos. Por defecto, el nombre en minúsculas con guiones.
-
--timezone <zone>stringUna zona horaria IANA, como
America/Bogota. Los días se cortan en ella.Por defecto:
UTC
Crear el proyecto de la tienda
sypnia project create --name Shopproject shop (prj_5k2m9x4q7w1z)
ingest key spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e
Put the ingest key in your app. It is public: it can only send.
Next: sypnia token create --project shop --name "My laptop" --scopes read,replayCódigos de salida: 0, 1, 4, 5.
Lista los proyectos.
Con el token raíz, todos los proyectos del motor. Con un token de API, el único proyecto al que pertenece.
Llama a: GET /v1/projects
Opciones
Ninguno.
Listar proyectos
sypnia project listSLUG ID NAME CREATED ENVIRONMENTS
shop prj_5k2m9x4q7w1z Shop 2026-02-02 production, developmentCódigos de salida: 0, 4, 5.
Borra un proyecto y todos sus datos.
Borra el proyecto para siempre. Te pide escribir otra vez el slug, salvo que pases --yes. Solo en motores alojados por ti; necesita el token raíz.
Llama a: DELETE /v1/projects/{project_ref}
Argumentos
-
<slug>string obligatorioEl slug o el id del proyecto.
Opciones
-
--yesbooleanNo preguntar. Para scripts.
Borrar un proyecto de prueba
sypnia project delete playground --yesCódigos de salida: 0, 4, 5, 6.
Crea una llave de ingesta.
Crea otra llave de ingesta para un proyecto. Dale a cada app o plataforma la suya.
Llama a: POST /v1/keys
Opciones
-
--project <id or slug>stringEl proyecto. Hace falta con el token raíz. También
SYPNIA_PROJECT. -
--name <name>string obligatorioPara qué es la llave.
-
--rate-limit <n>integerPeticiones por minuto que se aceptan desde una misma dirección con esta llave. De 10 a 6000.
Por defecto:
600
Una llave para el servidor de la API
sypnia key create --project shop --name "Checkout API"key_8b5n2m7v4c1x spk_a3c9e1f7b5d2084c6e0a9f3b7d1c5e82 Checkout APICódigos de salida: 0, 1, 4, 5, 6.
Lista las llaves de ingesta de un proyecto.
Muestra todas las llaves, incluidas las revocadas. Las llaves de ingesta son públicas, así que se imprimen completas.
Llama a: GET /v1/keys
Opciones
-
--project <id or slug>stringEl proyecto. Hace falta con el token raíz. También
SYPNIA_PROJECT.
Listar llaves
sypnia key list --project shopID KEY NAME LAST USED STATUS
key_3n8v2c6b1m4x spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e Web app 2026-03-12 10:00 activeCódigos de salida: 0, 4, 5, 6.
Revoca una llave de ingesta.
Revoca una llave. Las apps que todavía la usan dejan de enviar en menos de un minuto. La última llave activa de un proyecto no se puede revocar.
Llama a: DELETE /v1/keys/{key_id}
Argumentos
-
<key_id>string obligatorioEl id del registro de la llave (
key_…), dekey list.
Opciones
-
--project <id or slug>stringEl proyecto. Hace falta con el token raíz. También
SYPNIA_PROJECT.
Revocar una llave
sypnia key revoke key_8b5n2m7v4c1x --project shopCódigos de salida: 0, 1, 4, 5, 6.
Crea un token de API.
Crea un token de API e imprime su secreto una sola vez. Cópialo ahora; no se puede volver a mostrar.
Llama a: POST /v1/tokens
Opciones
-
--project <id or slug>stringEl proyecto. Hace falta con el token raíz. También
SYPNIA_PROJECT. -
--name <name>string obligatorioQuién o qué va a usar el token.
-
--scopes <list>string obligatorioSeparados por comas:
read,replay,admin. Da los mínimos que alcancen para el trabajo. -
--expires <time>stringCuándo deja de funcionar el token: un valor relativo (
90d) o una fecha ISO 8601. Si se omite, no vence.
Un token para tu agente de código
sypnia token create --project shop --name Cursor --scopes readtok_9r4t6y2u8i1o Cursor read
sps_4Kq9Zt2MxV7bN1cR5wY8pL3dF6hJ0sA2gE4uT9iO
This is the only time the token is shown.Un token para CI, para subir source maps
sypnia token create --project shop --name "CI source maps" --scopes admin --expires 365dCódigos de salida: 0, 1, 4, 5, 6.
Lista los tokens de API de un proyecto.
Muestra cada token con sus permisos y cuándo se usó por última vez. Los secretos nunca se muestran; el prefijo basta para reconocer uno.
Llama a: GET /v1/tokens
Opciones
-
--project <id or slug>stringEl proyecto. Hace falta con el token raíz. También
SYPNIA_PROJECT.
Listar tokens
sypnia token list --project shopID NAME PREFIX SCOPES LAST USED EXPIRES STATUS
tok_9r4t6y2u8i1o Cursor sps_4Kq9Zt2M read, replay 2026-03-12 10:00 never activeCódigos de salida: 0, 4, 5, 6.
Revoca un token de API.
Revoca un token. Las peticiones con él se rechazan en menos de un minuto.
Llama a: DELETE /v1/tokens/{token_id}
Argumentos
-
<token_id>string obligatorioEl id del registro del token (
tok_…), detoken list.
Opciones
-
--project <id or slug>stringEl proyecto. Hace falta con el token raíz. También
SYPNIA_PROJECT.
Revocar un token
sypnia token revoke tok_9r4t6y2u8i1o --project shopCódigos de salida: 0, 4, 5, 6.
Trabajar con un proyecto
Estos comandos llaman a la API HTTP con un token de API en SYPNIA_API_TOKEN. Funcionan igual contra Sypnia Cloud y contra un motor alojado por ti.
Sube los source maps de un build y registra su versión.
Córrelo en tu build, después de empaquetar y antes de desplegar. Hace cuatro cosas:
- Encuentra cada archivo JavaScript dentro del directorio y el mapa al que apunta (su comentario
sourceMappingURL, o el archivo de al lado que termina en.map). - Registra la versión, con lo que sabe git: el commit, los commits desde la versión anterior y los archivos que cambiaron. Esto es lo que le permite a Sypnia decir «desde el cambio de ayer».
- Sube los mapas que Sypnia todavía no tiene, directo al almacenamiento.
- Con
--delete-after, borra los archivos.mapdel directorio, para que nunca se publiquen.
Correrlo dos veces cuesta poco: los mapas que ya están se saltan. Necesita un token de API con el permiso
admin en SYPNIA_API_TOKEN; guárdalo en los secretos de tu CI.
Por defecto una falla detiene tu build (código de salida 1 o 4). Pasa --allow-failure si un despliegue nunca
debe esperar a Sypnia: el comando imprime el error y termina con 0, y las pilas de esa versión quedan
minificadas.
Llama a: POST /v1/releases, POST /v1/releases/{version}/sourcemaps
Argumentos
-
<directory>string obligatorioLa salida del build que tiene los archivos JavaScript y sus mapas, por ejemplo
disto.next/static.
Opciones
-
--release <version>string obligatorioEl nombre de la versión: la misma cadena que tu app le pasa a
initcomorelease. Usa el commit corto de git. -
--url-prefix <path>stringLa ruta desde la que tu sitio sirve el directorio. Con
dist/assets/a.jsservido como/assets/a.js, subedistcon/, odist/assetscon/assets.Por defecto:
/ -
--environment <name>stringEl entorno donde se despliega la versión.
Por defecto:
production -
--changes <mode>git | nonegitenvía el commit, los commits desde la versión anterior y los archivos cambiados, leídos del repositorio del directorio actual.noneenvía solo el nombre de la versión.Por defecto:
git -
--patchesbooleanEnvía además el diff de cada archivo cambiado. Hace más preciso el análisis. Los diffs son tu código: se guardan en tu motor, o en Sypnia Cloud, y se envían al proveedor de IA con el análisis.
-
--previous <version>stringLa versión a la que esta reemplaza. Por defecto, la última versión del proyecto en el entorno.
-
--delete-afterbooleanBorra los archivos
.mapdel directorio después de una subida exitosa. -
--allow-failurebooleanTermina con 0 aunque la subida falle.
-
--dry-runbooleanMuestra qué se registraría y qué se subiría, y no envía nada.
-
--concurrency <n>integerSubidas al mismo tiempo. De 1 a 32.
Por defecto:
8
En un script de build
sypnia sourcemaps upload dist --release "$(git rev-parse --short HEAD)" --delete-afterrelease 4f2a91c (production), previous 9c1e7b2: 1 commit, 2 files changed
found 42 JavaScript files with a source map
uploaded 41 maps (6.2 MB), skipped 1 already there
deleted 42 .map files from dist
done in 3.4 sCódigos de salida: 0, 1, 2, 4, 5.
Lista los problemas.
Imprime los problemas del proyecto en una tabla, con la actividad más reciente primero. Los mismos filtros que la API. Con --json imprime lo que devuelve GET /v1/problems.
Llama a: GET /v1/problems
Opciones
-
--status <status>open | resolved | ignored | allQué problemas listar.
Por defecto:
open -
--since <time>stringSolo problemas vistos después de este momento.
Por defecto:
30d -
--environment <name>stringEl entorno que se lee.
Por defecto:
production -
--query <text>stringTexto que buscar en la frase, el título o el archivo.
-
--sort <field>last_seen | first_seen | people | occurrencesEl orden.
Por defecto:
last_seen -
--limit <n>integerCuántos imprimir. De 1 a 200.
Por defecto:
20 -
--project <id or slug>stringEl proyecto. Hace falta con el token raíz. También
SYPNIA_PROJECT.
Qué está abierto
sypnia problems1 open problem in shop (production)
pay-button-does-nothing 3 people since today 09:12 release 4f2a91c
3 people tried to pay today and could not. The Pay button does nothing
since yesterday's change.
src/checkout/checkout.tsx:142 confidence highCódigos de salida: 0, 4, 5.
Muestra un problema.
Imprime un problema: la frase, a quién afectó, desde cuándo, la causa con su evidencia, qué hacer y dónde
mirar. Con --context agrega la pila con líneas de código, lo que hizo la persona antes y la traza. Con
--prompt imprime solo el prompt listo, en texto plano, para que lo puedas pasar a un archivo o a un agente de
código.
Llama a: GET /v1/problems/{problem}, /context, /prompt
Argumentos
-
<problem>string obligatorioEl slug o el id del problema.
Opciones
-
--contextbooleanImprime además la pila, los pasos previos, la traza y los cambios de la versión.
-
--promptbooleanImprime solo el prompt listo.
-
--project <id or slug>stringEl proyecto. Hace falta con el token raíz. También
SYPNIA_PROJECT.
Leer un problema
sypnia problem pay-button-does-nothingpay-button-does-nothing open prb_8f3k2m9x4q7w
3 people tried to pay today and could not. The Pay button does nothing
since yesterday's change.
Who 3 people. Two of them tried again and gave up.
Doing Paying for an order, at the last step of checkout.
Since Yesterday's change, deployed at 18:40. It worked before.
Cause Release 4f2a91c renamed the cart's total from cart.total to
cart.totalCents. The checkout still reads cart.total, so the
payment goes out without an amount and the API answers 400.
(confidence: high)
Evidence 4f2a91c:src/cart/cart.ts renames total to totalCents
src/checkout/checkout.tsx:142 still passes cart.total
trace 7c2e9a4b… POST /api/checkout answered 400 amount_required
What to do Read cart.totalCents in confirmPayment(), and show the customer
a message when a payment is rejected.
Where src/checkout/checkout.tsx:142 confirmPayment()
Open https://app.sypnia.com/shop/problems/pay-button-does-nothingCopiar el prompt para tu agente de código
sypnia problem pay-button-does-nothing --prompt > fix.mdCódigos de salida: 0, 4, 5, 6.
Imprime la versión.
Imprime la versión del binario, su commit y el esquema de base de datos más nuevo que conoce. Con --json, como objeto.
Opciones
Ninguno.
Versión
sypnia versionsypnia 1.0.0 (a1c9e3f, 2026-03-01) schema 12Códigos de salida: 0.