Acceso anticipadoSolo por invitación, y los SDK aún no están publicados.Pedir una invitación
Ir al contenido
Docs

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:

  1. --human escribe tablas, incluso hacia un pipe. --json escribe JSON, incluso en una terminal. No se pueden usar juntos.
  2. 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.
  3. 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:

VariableLa define
LYRELOG_AGENTTú: dale cualquier valor para forzar el modo agente en cualquier sitio
AI_AGENTLa convención común entre herramientas: Claude Code la define, @vercel/detect-agent de Vercel la lee
AGENTAmp (AGENT=amp), Goose (AGENT=goose); también 1 o true. Cualquier otro valor se ignora: el nombre es demasiado común
CLAUDECODE, CLAUDE_CODE_ENTRYPOINTClaude Code, en cada shell que ejecuta
CURSOR_AGENT, o CURSOR_EXTENSION_HOST_ROLE=agent-execEl agente de Cursor (CLI y editor)
CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_CI, CODEX_THREAD_IDOpenAI Codex CLI
GEMINI_CLILa herramienta de shell de Gemini CLI
OPENCODE=1, OPENCODE_CLIENTopencode
AMP_CURRENT_THREAD_IDAmp
AUGMENT_AGENT, ANTIGRAVITY_AGENTAugment, Antigravity
CIGitHub 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.

  • --follow escribe un objeto JSON por línea (NDJSON), uno por evento, hasta que se detiene.

  • Cuando una lista se cortó, por --limit o por páginas, stderr recibe una línea que dice cómo obtener el resto. Pasa next como 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}

    error y hint son para personas. code es estable, para programas. status es el código de estado HTTP, cuando el servidor respondió. retry_after va 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 --yes se 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ódigocodeSignificado
0Hecho
1errorFalló otra cosa (el servidor, un archivo)
2usageUn comando, flag o valor incorrecto; o hace falta --yes
3not_signed_inSin sesión iniciada, o la sesión terminó: lyrelog login
4reauth_requiredLa acción requiere un inicio de sesión de los últimos 10 minutos: lyrelog login y reintentar
5forbiddenCon sesión iniciada, pero sin permiso (una acción de propietario)
5browser_onlySolo 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
6not_foundNo existe ese proyecto, evento, clave o persona (o no es tuyo)
7refusedEl servidor rechazó la petición tal como está (un 400 o un 409, por ejemplo)
8rate_limitedDemasiadas peticiones, o el servidor está ocupado: espera retry_after
9networkNo se pudo conectar con el servidor
130interruptedCtrl-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.