Acesso antecipadoSó por convite, e os SDKs ainda não foram publicados.Pedir um convite
Ir para o conteúdo
Docs

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:

  1. --human escreve tabelas, mesmo num pipe. --json escreve JSON, mesmo num terminal. Os dois não podem ser usados juntos.
  2. 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.
  3. 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ávelDefinida por
LYRELOG_AGENTVocê: defina com qualquer valor para forçar o modo agente em qualquer lugar
AI_AGENTA convenção entre ferramentas: o Claude Code a define, o @vercel/detect-agent da Vercel a lê
AGENTAmp (AGENT=amp), Goose (AGENT=goose); também 1 ou true. Qualquer outro valor é ignorado: o nome é comum demais
CLAUDECODE, CLAUDE_CODE_ENTRYPOINTClaude Code, em todo shell que ele roda
CURSOR_AGENT, ou CURSOR_EXTENSION_HOST_ROLE=agent-execO agente do Cursor (CLI e editor)
CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_CI, CODEX_THREAD_IDOpenAI Codex CLI
GEMINI_CLIA ferramenta de shell do Gemini CLI
OPENCODE=1, OPENCODE_CLIENTopencode
AMP_CURRENT_THREAD_IDAmp
AUGMENT_AGENT, ANTIGRAVITY_AGENTAugment, Antigravity
CIGitHub 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.

  • --follow escreve um objeto JSON por linha (NDJSON), um por evento, até ser interrompido.

  • Quando uma lista foi cortada, por --limit ou por páginas, o stderr recebe uma linha dizendo como obter o resto. Passe next como 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}

    error e hint sã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 --yes o 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ódigocodeSignificado
0Concluído
1errorOutra coisa falhou (o servidor, um arquivo)
2usageUm comando, uma flag ou um valor errado; ou falta --yes
3not_signed_inSem login, ou a sessão terminou: lyrelog login
4reauth_requiredA ação exige ter entrado nos últimos 10 minutos: lyrelog login, depois tente de novo
5forbiddenCom login, mas sem permissão (uma ação de proprietário)
5browser_onlySó 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
6not_foundEsse projeto, evento, chave ou pessoa não existe (ou não é seu)
7refusedO servidor recusou a requisição como ela está (um 400 ou 409, por exemplo)
8rate_limitedRequisições demais, ou o servidor está ocupado: espere retry_after
9networkNão foi possível alcançar o servidor
130interruptedCtrl-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.