Para agentes e scripts
Quando a CLI escreve JSON, como é esse JSON, os seus códigos de saída e um prompt para um agente de código investigar um erro.
A ferramenta de linha de comando foi feita para ser executada tanto por programas quanto por pessoas. Sob um agente de código, numa CI ou num pipe, ela escreve JSON e mais nada: sem cores, sem spinner, sem perguntas. Um agente de código consegue então buscar eventos, ler erros e seguir uma pessoa ao longo de uma sessão com a mesma facilidade que você tem no painel.
JSON ou tabelas
Cada execução decide uma vez, nesta ordem:
--humanescreve tabelas, mesmo num pipe.--jsonescreve JSON, mesmo num terminal. Os dois não podem ser usados juntos.- Senão, ela escreve JSON quando o stdout não é um terminal (
lyrelog errors | jq,> file.json), ou quando uma das variáveis abaixo está definida. - Senão, num terminal, ela escreve tabelas.
Os agentes costumam rodar comandos num pseudoterminal, então só verificar o terminal não basta. Estas variáveis contam:
| Variável | Definida por |
|---|---|
LYRELOG_AGENT | Você: defina com qualquer valor para forçar o modo agente em qualquer lugar |
AI_AGENT | A convenção entre ferramentas: o Claude Code a define, o @vercel/detect-agent da Vercel a lê |
AGENT | Amp (AGENT=amp), Goose (AGENT=goose); também 1 ou true. Qualquer outro valor é ignorado: o nome é comum demais |
CLAUDECODE, CLAUDE_CODE_ENTRYPOINT | Claude Code, em todo shell que ele roda |
CURSOR_AGENT, ou CURSOR_EXTENSION_HOST_ROLE=agent-exec | O agente do Cursor (CLI e editor) |
CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_CI, CODEX_THREAD_ID | OpenAI Codex CLI |
GEMINI_CLI | A ferramenta de shell do 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 e a maioria dos outros. CI=false ou CI=0 não conta. |
Algumas ficam de fora de propósito. CURSOR_TRACE_ID e REPL_ID são definidas em todo terminal
do Cursor e todo shell do Replit, inclusive os de uma pessoa. O aider roda comandos sem terminal,
então a verificação de pipe o pega de qualquer forma.
As cores só aparecem nas tabelas num terminal. NO_COLOR (qualquer valor), TERM=dumb e
--no-color as desligam. Um agente ou uma CI nunca recebe uma pergunta, mesmo com --human.
O contrato do JSON
-
O stdout traz só os dados. Uma lista é um array JSON com os próprios objetos do servidor, com os nomes de campo da API do painel sem alteração. Um item único é um objeto.
-
Indentado num terminal (com
--json), numa linha só nos outros casos. -
--followescreve um objeto JSON por linha (NDJSON), um por evento, até ser interrompido. -
Quando uma lista foi cortada, por
--limitou por páginas, o stderr recebe uma linha dizendo como obter o resto. Passenextcomo flags para o mesmo comando:{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVh..."} {"more":true,"next":"--page 1"} -
Uma falha escreve uma linha no stderr e sai com um código:
{"error":"This needs a recent sign-in","hint":"Run lyrelog login again, then retry within 10 minutes.","code":"reauth_required","status":403}errorehintsão para pessoas.codeé estável, para programas.statusé o status HTTP, quando o servidor respondeu.retry_afteré em segundos, quando o servidor pediu para esperar. -
O que não pode ser desfeito exige
--yes: revogar uma chave, apagar os dados de uma pessoa, remover alguém de uma organização, apagar uma visualização salva. Ninguém pode responder a uma pergunta, então sem--yeso comando para com o código de saída 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}}]e no stderr:
{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVhMzNlNC0yNmViLTQyMmUtYjkwNC05NjY0OWMwZTc4MzA"}Os horários são milissegundos Unix. Mais alguns exemplos:
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}]Os nomes de campo são os da API, então uma contagem de pessoas é players, seja qual for a
palavra que o projeto usa para elas.
Códigos de saída
Eles são estáveis: scripts e agentes podem tomar decisões com base neles.
| Código | code | Significado |
|---|---|---|
| 0 | Concluído | |
| 1 | error | Outra coisa falhou (o servidor, um arquivo) |
| 2 | usage | Um comando, uma flag ou um valor errado; ou falta --yes |
| 3 | not_signed_in | Sem login, ou a sessão terminou: lyrelog login |
| 4 | reauth_required | A ação exige ter entrado nos últimos 10 minutos: lyrelog login, depois tente de novo |
| 5 | forbidden | Com login, mas sem permissão (uma ação de proprietário) |
| 5 | browser_only | Só o painel faz isso: apagar a conta ou um projeto, mudar a forma como você entra. O erro diz qual é a página. Também quando um token de acesso tenta criar ou alterar tokens |
| 6 | not_found | Esse projeto, evento, chave ou pessoa não existe (ou não é seu) |
| 7 | refused | O servidor recusou a requisição como ela está (um 400 ou 409, por exemplo) |
| 8 | rate_limited | Requisições demais, ou o servidor está ocupado: espere retry_after |
| 9 | network | Não foi possível alcançar o servidor |
| 130 | interrupted | Ctrl-C |
Parar --follow com Ctrl-C o encerra normalmente, com 0.
Entrar
Um agente não consegue entrar sozinho. lyrelog login se recusa a rodar sob um agente ou uma 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"}Uma pessoa roda lyrelog login uma vez, num terminal daquele computador, e todo agente ali usa
esse login até ele terminar (veja Entrar). O agente age como essa
pessoa, com os projetos e o papel dela. Criar uma chave de servidor, de leitura ou de
administração também exige que essa pessoa tenha entrado nos últimos 10 minutos.
Numa CI, ou para um agente sem nenhuma pessoa por perto, use um token de acesso: uma pessoa cria
um com lyrelog tokens create logo depois de lyrelog login, ou na página da conta, e o define
como LYRELOG_TOKEN (veja Scripts e CI).
Um prompt para investigar um erro
Cole isto no Claude Code, no Cursor ou em outro agente de código, no repositório do app, depois
de rodar lyrelog login e lyrelog use <project> num terminal ali. Coloque o nome do erro no
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.Os agentes também leem esta documentação em Markdown: veja Usar com agentes de IA.