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:
--humanwrites tables, even into a pipe.--jsonwrites JSON, even at a terminal. They can't go together.- Otherwise it writes JSON when stdout isn't a terminal (
lyrelog errors | jq,> file.json), or when one of the variables below is set. - 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:
| Variable | Set by |
|---|---|
LYRELOG_AGENT | You: set it to any value to force agent mode anywhere |
AI_AGENT | The cross-tool convention: Claude Code sets it, Vercel's @vercel/detect-agent reads it |
AGENT | Amp (AGENT=amp), Goose (AGENT=goose); also 1 or true. Any other value is ignored: the name is too common |
CLAUDECODE, CLAUDE_CODE_ENTRYPOINT | Claude Code, in every shell it runs |
CURSOR_AGENT, or CURSOR_EXTENSION_HOST_ROLE=agent-exec | Cursor's agent (CLI and editor) |
CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_CI, CODEX_THREAD_ID | OpenAI Codex CLI |
GEMINI_CLI | Gemini CLI's shell tool |
OPENCODE=1, OPENCODE_CLIENT | opencode |
AMP_CURRENT_THREAD_ID | Amp |
AUGMENT_AGENT, ANTIGRAVITY_AGENT | Augment, Antigravity |
CI | GitHub 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. -
--followwrites one JSON object a line (NDJSON), one per event, until it's stopped. -
When a list was cut, by
--limitor by pages, stderr gets one line saying how to get the rest. Passnextas 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}errorandhintare for people.codeis stable, for programs.statusis the HTTP status, when the server answered.retry_afteris 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--yesit 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.
| Code | code | Meaning |
|---|---|---|
| 0 | Done | |
| 1 | error | Something else failed (the server, a file) |
| 2 | usage | A wrong command, flag or value; or --yes is needed |
| 3 | not_signed_in | Not signed in, or the session ended: lyrelog login |
| 4 | reauth_required | The action needs a sign-in from the last 10 minutes: lyrelog login, then retry |
| 5 | forbidden | Signed in, but not allowed (an owner's action) |
| 5 | browser_only | Only 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 |
| 6 | not_found | No such project, event, key or person (or not yours) |
| 7 | refused | The server refused the request as it is (a 400 or 409, say) |
| 8 | rate_limited | Too many requests, or the server is busy: wait retry_after |
| 9 | network | The server couldn't be reached |
| 130 | interrupted | Ctrl-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.