Para agentes y scripts
Cuándo escribe JSON la CLI, cómo es ese JSON, sus códigos de salida y un prompt para que un agente de programación investigue un error.
La herramienta de línea de comandos está pensada para que la ejecuten tanto programas como personas. Bajo un agente de programación, en CI o en un pipe, escribe JSON y nada más: sin colores, sin spinner, sin preguntas. Así un agente de programación puede buscar eventos, leer errores y seguir a una persona a lo largo de una sesión con la misma facilidad que tú en el panel.
JSON o tablas
Cada ejecución lo decide una vez, en este orden:
--humanescribe tablas, incluso hacia un pipe.--jsonescribe JSON, incluso en una terminal. No se pueden usar juntos.- Si no, escribe JSON cuando stdout no es una terminal (
lyrelog errors | jq,> file.json), o cuando está definida alguna de las variables de abajo. - Si no, en una terminal, escribe tablas.
Los agentes suelen ejecutar los comandos en una pseudoterminal, así que comprobar solo la terminal no basta. Estas variables cuentan:
| Variable | La define |
|---|---|
LYRELOG_AGENT | Tú: dale cualquier valor para forzar el modo agente en cualquier sitio |
AI_AGENT | La convención común entre herramientas: Claude Code la define, @vercel/detect-agent de Vercel la lee |
AGENT | Amp (AGENT=amp), Goose (AGENT=goose); también 1 o true. Cualquier otro valor se ignora: el nombre es demasiado común |
CLAUDECODE, CLAUDE_CODE_ENTRYPOINT | Claude Code, en cada shell que ejecuta |
CURSOR_AGENT, o CURSOR_EXTENSION_HOST_ROLE=agent-exec | El agente de Cursor (CLI y editor) |
CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_CI, CODEX_THREAD_ID | OpenAI Codex CLI |
GEMINI_CLI | La herramienta de shell de Gemini CLI |
OPENCODE=1, OPENCODE_CLIENT | opencode |
AMP_CURRENT_THREAD_ID | Amp |
AUGMENT_AGENT, ANTIGRAVITY_AGENT | Augment, Antigravity |
CI | GitHub Actions, GitLab CI, CircleCI, Buildkite y casi todos los demás. CI=false o CI=0 no cuentan. |
Algunas se dejan fuera a propósito. CURSOR_TRACE_ID y REPL_ID están definidas en toda
terminal de Cursor y todo shell de Replit, también en los de una persona. aider ejecuta los
comandos sin terminal, así que la comprobación del pipe lo detecta igualmente.
Los colores solo aparecen en las tablas en una terminal. NO_COLOR (con cualquier valor),
TERM=dumb y --no-color los desactivan. A un agente o a un CI nunca se le hace una pregunta,
ni siquiera con --human.
El contrato del JSON
-
stdout lleva solo los datos. Una lista es un array JSON con los propios objetos del servidor, con los nombres de campo de la API del panel sin cambios. Un único elemento es un objeto.
-
Indentado en una terminal (con
--json), en una línea en los demás casos. -
--followescribe un objeto JSON por línea (NDJSON), uno por evento, hasta que se detiene. -
Cuando una lista se cortó, por
--limito por páginas, stderr recibe una línea que dice cómo obtener el resto. Pasanextcomo flags al mismo comando:{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVh..."} {"more":true,"next":"--page 1"} -
Un fallo escribe una línea en stderr y termina con un código:
{"error":"This needs a recent sign-in","hint":"Run lyrelog login again, then retry within 10 minutes.","code":"reauth_required","status":403}erroryhintson para personas.codees estable, para programas.statuses el código de estado HTTP, cuando el servidor respondió.retry_afterva en segundos, cuando el servidor pidió esperar. -
Lo que no se puede deshacer necesita
--yes: revocar una clave, borrar los datos de una persona, quitar a alguien de una organización, borrar una vista guardada. Nadie puede responder a una pregunta, así que sin--yesse detiene con el código de salida 2.
lyrelog events --level error --since 7d -n 1[{"event_id":"adea33e4-26eb-422e-b904-96649c0e7830","ts":1795167007485,"level":"error","category":"sync","message":"cloud_save_failed","user_id":"pl-fe0958c6","install_id":"76f5a7d0-81b0-4c36-8908-eefd6c936abf","session_id":"51e19a18-ca3e-4428-a10b-baeadc7eaaf8","app_id":"com.example.tilefall","app_version":"1.6.3","app_build":"202609301304","os_name":"iOS","os_version":"27.2.0","device_model":"iPhone18,2","locale":"fr_FR","country":"FR","environment":"production","platform":"ios","received_at":1795167047509,"verified_by":"","attrs":{"reason":"schema_mismatch","record":"progress","status":422}}]y en stderr:
{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVhMzNlNC0yNmViLTQyMmUtYjkwNC05NjY0OWMwZTc4MzA"}Las horas van en milisegundos Unix. Algunos más:
lyrelog errors | jq -c '.[0] | {name, area, count, players, versions, sample_event}'
lyrelog events values message --level error --since 7d | jq -c '.[0:2]'
lyrelog events -f --level error | jq -r '.message'
lyrelog keys create --type server --name tilefall-api | jq -r .secret{"name":"cloud_save_failed","area":"sync","count":823,"players":124,"versions":["1.6.3"],"sample_event":"adea33e4-26eb-422e-b904-96649c0e7830"}
[{"value":"cloud_save_failed","count":823,"players":124},{"value":"daily_upload_failed","count":178,"players":124}]Los nombres de campo son los de la API, así que un recuento de personas es players llame como
llame el proyecto a sus personas.
Códigos de salida
Son estables: los scripts y los agentes pueden decidir según ellos.
| Código | code | Significado |
|---|---|---|
| 0 | Hecho | |
| 1 | error | Falló otra cosa (el servidor, un archivo) |
| 2 | usage | Un comando, flag o valor incorrecto; o hace falta --yes |
| 3 | not_signed_in | Sin sesión iniciada, o la sesión terminó: lyrelog login |
| 4 | reauth_required | La acción requiere un inicio de sesión de los últimos 10 minutos: lyrelog login y reintentar |
| 5 | forbidden | Con sesión iniciada, pero sin permiso (una acción de propietario) |
| 5 | browser_only | Solo lo hace el panel: borrar la cuenta o un proyecto, cambiar cómo inicias sesión. El error nombra la página. También un token de acceso que intenta crear o cambiar tokens |
| 6 | not_found | No existe ese proyecto, evento, clave o persona (o no es tuyo) |
| 7 | refused | El servidor rechazó la petición tal como está (un 400 o un 409, por ejemplo) |
| 8 | rate_limited | Demasiadas peticiones, o el servidor está ocupado: espera retry_after |
| 9 | network | No se pudo conectar con el servidor |
| 130 | interrupted | Ctrl-C |
Detener --follow con Ctrl-C lo termina con normalidad, con 0.
Iniciar sesión
Un agente no puede iniciar sesión por su cuenta. lyrelog login se niega a ejecutarse bajo un
agente o en CI:
{"error":"An agent (claude-code) can't sign in by itself: signing in needs a person","hint":"Ask a person to run `lyrelog login` in a terminal on this computer; the CLI then uses that sign-in. In CI, set LYRELOG_TOKEN to an access token from your account page: https://docs.lyrelog.com/cli/login#scripts-and-ci","code":"not_signed_in"}Una persona ejecuta lyrelog login una vez, en una terminal de ese ordenador, y todos los
agentes de ese ordenador usan esa sesión hasta que termine (consulta
Iniciar sesión). El agente actúa como esa persona, con sus proyectos y
su rol. Crear una clave de servidor, de lectura o de administración también requiere que esa
persona haya iniciado sesión en los últimos 10 minutos.
En CI, o para un agente sin ninguna persona cerca, usa un token de acceso: una persona crea uno
con lyrelog tokens create justo después de lyrelog login, o en la página de la cuenta, y lo
define como LYRELOG_TOKEN (consulta Scripts y CI).
Un prompt para investigar un error
Pega esto en Claude Code, Cursor u otro agente de programación, en el repositorio de la app,
después de haber ejecutado lyrelog login y lyrelog use <project> en una terminal de ese
ordenador. Pon el nombre del error en lugar de cloud_save_failed.
Investigate the error "cloud_save_failed" in our app with the Lyrelog CLI (lyrelog),
which is installed and signed in. It writes JSON when you run it. Run `lyrelog --help` and
the commands' --help first; don't guess flags. Read only: don't create, change, revoke or
delete anything.
1. `lyrelog errors --since 7d` and find this error: how many times, how many people, which
versions, when it started, and its sample_event and sample_session.
2. `lyrelog events get <sample_event>`: read its attributes and payload.
3. `lyrelog events --session <sample_session> --oldest-first`: what happened before it in
that session.
4. Compare: `lyrelog events values version --message cloud_save_failed --since 7d`,
and the same with device, then `lyrelog insights rate --hits cloud_save_failed
--of "<the events that attempt it>" --by version`.
5. Look at one or two more people it reached (`lyrelog person <user_id>`), to check the
pattern holds.
6. Find the code that logs this event in this repository, explain the most likely cause from
what the events show, and propose a fix. Say what's proven by the events and what's a
guess.
If a command fails with code reauth_required or not_signed_in, stop and tell me: I'll sign in
again. Don't paste customers' event content anywhere outside this conversation.Los agentes también leen esta documentación en Markdown: consulta Uso con agentes de IA.