Early accessBy invitation, and the SDKs aren't published yet.Ask for an invitation
Skip to Content
Docs

For agents and scripts

When the CLI writes JSON, what the JSON looks like, its exit codes, and a prompt for a coding agent to investigate an error.

The command-line tool is made to be run by programs as much as by people. Under a coding agent, in CI or in a pipe, it writes JSON and nothing else: no colours, no spinner, no questions. A coding agent can then search events, read errors and follow a person through a session as easily as you can in the dashboard.

JSON or tables

Each run decides once, in this order:

  1. --human writes tables, even into a pipe. --json writes JSON, even at a terminal. They can't go together.
  2. Otherwise it writes JSON when stdout isn't a terminal (lyrelog errors | jq, > file.json), or when one of the variables below is set.
  3. Otherwise, at a terminal, it writes tables.

Agents often run commands in a pseudo-terminal, so the terminal check alone isn't enough. These variables count:

VariableSet by
LYRELOG_AGENTYou: set it to any value to force agent mode anywhere
AI_AGENTThe cross-tool convention: Claude Code sets it, Vercel's @vercel/detect-agent reads it
AGENTAmp (AGENT=amp), Goose (AGENT=goose); also 1 or true. Any other value is ignored: the name is too common
CLAUDECODE, CLAUDE_CODE_ENTRYPOINTClaude Code, in every shell it runs
CURSOR_AGENT, or CURSOR_EXTENSION_HOST_ROLE=agent-execCursor's agent (CLI and editor)
CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_CI, CODEX_THREAD_IDOpenAI Codex CLI
GEMINI_CLIGemini CLI's shell tool
OPENCODE=1, OPENCODE_CLIENTopencode
AMP_CURRENT_THREAD_IDAmp
AUGMENT_AGENT, ANTIGRAVITY_AGENTAugment, Antigravity
CIGitHub Actions, GitLab CI, CircleCI, Buildkite and most others. CI=false or CI=0 doesn't count.

Some are left out on purpose. CURSOR_TRACE_ID and REPL_ID are set in every Cursor terminal and Replit shell, including a person's. aider runs commands without a terminal, so the pipe check catches it anyway.

Colours appear only in tables at a terminal. NO_COLOR (any value), TERM=dumb and --no-color turn them off. An agent or CI is never asked a question, even with --human.

The JSON contract

  • stdout carries only the data. A list is a JSON array of the server's own objects, with the dashboard API's field names unchanged. One thing is an object.

  • Indented at a terminal (with --json), one line otherwise.

  • --follow writes one JSON object a line (NDJSON), one per event, until it's stopped.

  • When a list was cut, by --limit or by pages, stderr gets one line saying how to get the rest. Pass next as flags to the same command:

    {"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVh..."}
    {"more":true,"next":"--page 1"}
  • A failure writes one line to stderr and exits with a code:

    {"error":"This needs a recent sign-in","hint":"Run lyrelog login again, then retry within 10 minutes.","code":"reauth_required","status":403}

    error and hint are for people. code is stable, for programs. status is the HTTP status, when the server answered. retry_after is in seconds, when the server asked to wait.

  • Something that can't be undone needs --yes: revoking a key, deleting a person's data, removing someone from an organization, deleting a saved view. Nobody can answer a question, so without --yes it stops with exit code 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}}]

and on stderr:

{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVhMzNlNC0yNmViLTQyMmUtYjkwNC05NjY0OWMwZTc4MzA"}

Times are Unix milliseconds. Some more:

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}]

Field names are the API's, so a count of people is players whatever the project calls them.

Exit codes

They're stable: scripts and agents can branch on them.

CodecodeMeaning
0Done
1errorSomething else failed (the server, a file)
2usageA wrong command, flag or value; or --yes is needed
3not_signed_inNot signed in, or the session ended: lyrelog login
4reauth_requiredThe action needs a sign-in from the last 10 minutes: lyrelog login, then retry
5forbiddenSigned in, but not allowed (an owner's action)
5browser_onlyOnly the dashboard does this: deleting the account or a project, changing how you sign in. The error names the page. Also an access token trying to make or change tokens
6not_foundNo such project, event, key or person (or not yours)
7refusedThe server refused the request as it is (a 400 or 409, say)
8rate_limitedToo many requests, or the server is busy: wait retry_after
9networkThe server couldn't be reached
130interruptedCtrl-C

Stopping --follow with Ctrl-C ends it normally, with 0.

Signing in

An agent can't sign in by itself. lyrelog login refuses to run under an agent or 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"}

A person runs lyrelog login once, in a terminal on that computer, and every agent there uses that sign-in until it ends (see Sign in). The agent acts as that person, with their projects and their role. Creating a server, read or admin key also needs that person to have signed in within the last 10 minutes.

In CI, or for an agent with no person around, use an access token: a person makes one with lyrelog tokens create right after lyrelog login, or on the account page, and sets it as LYRELOG_TOKEN (see Scripts and CI).

A prompt to investigate an error

Paste this into Claude Code, Cursor or another coding agent, in the repository of the app, after you've run lyrelog login and lyrelog use <project> in a terminal there. Put the error's name in place of 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.

Agents also read these docs as Markdown: see Use with AI agents.