供 agent 和脚本使用
CLI 何时输出 JSON、JSON 的格式、退出码,以及一段让编程 agent 排查错误的提示词。
命令行工具既为人设计,也同样为程序设计。在编程 agent 中、在 CI 中或在管道中运行时,它只输出 JSON:没有颜色,没有加载动画, 也不会提问。这样,编程 agent 就能像你在控制台中一样方便地搜索事件、查看错误,以及跟着某个用户把一个会话从头看到尾。
JSON 还是表格
每次运行只判断一次,顺序如下:
--human输出表格,即使输出到管道。--json输出 JSON,即使在终端中。两者不能同时使用。- 否则,当 stdout 不是终端时(
lyrelog errors | jq、> file.json),或者设置了下列某个变量时,输出 JSON。 - 否则,在终端中输出表格。
agent 常常在伪终端中运行命令,所以只检查是否为终端是不够的。下列变量都会被识别:
| 变量 | 由谁设置 |
|---|---|
LYRELOG_AGENT | 你自己:设为任意值,就能在任何地方强制使用 agent 模式 |
AI_AGENT | 跨工具的约定:Claude Code 会设置它,Vercel 的 @vercel/detect-agent 会读取它 |
AGENT | Amp(AGENT=amp)、Goose(AGENT=goose);也可以是 1 或 true。其他值会被忽略:这个名字太常见了 |
CLAUDECODE、CLAUDE_CODE_ENTRYPOINT | Claude Code,在它运行的每个 shell 中 |
CURSOR_AGENT,或 CURSOR_EXTENSION_HOST_ROLE=agent-exec | Cursor 的 agent(CLI 和编辑器) |
CODEX_SANDBOX、CODEX_SANDBOX_NETWORK_DISABLED、CODEX_CI、CODEX_THREAD_ID | OpenAI Codex CLI |
GEMINI_CLI | Gemini CLI 的 shell 工具 |
OPENCODE=1、OPENCODE_CLIENT | opencode |
AMP_CURRENT_THREAD_ID | Amp |
AUGMENT_AGENT、ANTIGRAVITY_AGENT | Augment、Antigravity |
CI | GitHub Actions、GitLab CI、CircleCI、Buildkite 以及大多数其他 CI。CI=false 或 CI=0 不算。 |
有些变量是特意不纳入的。CURSOR_TRACE_ID 和 REPL_ID 会出现在每个 Cursor 终端和 Replit shell 中,包括人使用的终端。
aider 运行命令时不带终端,所以管道检查本来就能识别它。
颜色只出现在终端中的表格里。NO_COLOR(任意值)、TERM=dumb 和 --no-color 可以关闭颜色。agent 或 CI 永远不会被提问,
即使使用了 --human。
JSON 约定
-
stdout 只输出数据。 列表是由服务器原始对象组成的 JSON 数组,字段名与控制台 API 完全一致。单个结果则是一个对象。
-
在终端中(使用
--json时)会缩进,其他情况下输出为一行。 -
--follow每行输出一个 JSON 对象(NDJSON),每个事件一个,直到被停止。 -
当列表被截断时(因为
--limit或分页),stderr 会输出一行,说明如何获取其余部分。把next作为参数传给同一条命令:{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVh..."} {"more":true,"next":"--page 1"} -
失败时会向 stderr 输出一行,并以某个退出码退出:
{"error":"This needs a recent sign-in","hint":"Run lyrelog login again, then retry within 10 minutes.","code":"reauth_required","status":403}error和hint是给人看的。code是稳定的,供程序使用。status是 HTTP 状态码(服务器有响应时)。retry_after以秒为单位(服务器要求等待时)。 -
无法撤销的操作需要
--yes:吊销密钥、删除某个用户的数据、把某人移出组织、删除已保存的视图。没有人能回答提问, 所以不加--yes时,命令会以退出码 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}}]stderr 上则输出:
{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVhMzNlNC0yNmViLTQyMmUtYjkwNC05NjY0OWMwZTc4MzA"}时间均为 Unix 毫秒时间戳。更多示例:
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}]字段名沿用 API 的命名,所以无论项目怎么称呼用户,用户数的字段都是 players。
退出码
退出码是稳定的:脚本和 agent 可以据此分支处理。
| 退出码 | code | 含义 |
|---|---|---|
| 0 | 成功 | |
| 1 | error | 其他失败(服务器、文件) |
| 2 | usage | 命令、参数或取值有误;或者需要 --yes |
| 3 | not_signed_in | 未登录,或会话已结束:运行 lyrelog login |
| 4 | reauth_required | 该操作需要最近 10 分钟内的登录:运行 lyrelog login,然后重试 |
| 5 | forbidden | 已登录,但没有权限(所有者才能执行的操作) |
| 5 | browser_only | 只能在控制台中进行:删除账户或项目、更改登录方式。错误信息会指明对应的页面。访问令牌试图创建或更改令牌时也是这个退出码 |
| 6 | not_found | 没有这样的项目、事件、密钥或用户(或者不属于你) |
| 7 | refused | 服务器拒绝了这个请求(例如 400 或 409) |
| 8 | rate_limited | 请求过多,或服务器繁忙:等待 retry_after |
| 9 | network | 无法连接服务器 |
| 130 | interrupted | Ctrl-C |
用 Ctrl-C 停止 --follow 属于正常结束,退出码为 0。
登录
agent 无法自己登录。lyrelog login 拒绝在 agent 或 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"}由人在那台电脑的终端里运行一次 lyrelog login,之后那里的每个 agent 都会使用这个登录,直到它结束(参见登录)。
agent 以那个人的身份操作,拥有那个人的项目和角色。创建服务器密钥、只读密钥或管理密钥,还要求那个人在最近 10 分钟内登录过。
在 CI 中,或者对于身边没有人的 agent,请使用访问令牌:由人在运行 lyrelog login 之后立即用 lyrelog tokens create 创建一个,
或者在账户页面中创建,并把它设为 LYRELOG_TOKEN(参见脚本和 CI)。
排查错误的提示词
先在应用代码仓库的终端中运行 lyrelog login 和 lyrelog use <project>,然后把下面这段提示词粘贴到该仓库中的 Claude Code、Cursor
或其他编程 agent 中。把 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.agent 也可以读取这些文档的 Markdown 版本:参见与 AI agent 一起使用。