エージェントとスクリプト向け
CLI が JSON を出力する条件、JSON の形、終了コード、そしてコーディングエージェントにエラーを調査させるためのプロンプト。
コマンドラインツールは、人間だけでなくプログラムから実行されることも想定して作られています。コーディングエージェントや CI から実行したときと、パイプの中では、JSON だけを出力します。色もスピナーも質問もありません。そのため、コーディングエージェントも、あなたがダッシュボードで行うのと同じように、イベントの検索、エラーの確認、セッション内での 1 人のユーザーの追跡を簡単に行えます。
JSON かテーブルか
実行のたびに、次の順で一度だけ決まります。
--humanはパイプに渡すときでもテーブルを出力します。--jsonはターミナルでも JSON を出力します。両方は同時に指定できません。- それ以外の場合、stdout がターミナルでないとき(
lyrelog errors | jq、> file.json)、または下の変数のいずれかが設定されているときは JSON を出力します。 - どちらでもなく、ターミナルで実行しているときは、テーブルを出力します。
エージェントは疑似ターミナルでコマンドを実行することが多いので、ターミナルかどうかの判定だけでは足りません。次の変数を判定に使います。
| 変数 | 設定するもの |
|---|---|
LYRELOG_AGENT | あなた:任意の値を設定すると、どこでもエージェントモードになります |
AI_AGENT | ツール横断の慣習:Claude Code が設定し、Vercel の @vercel/detect-agent が読みます |
AGENT | Amp(AGENT=amp)、Goose(AGENT=goose)。1 や true も有効です。名前がありふれているため、ほかの値は無視します |
CLAUDECODE, CLAUDE_CODE_ENTRYPOINT | Claude Code(実行するすべてのシェルで) |
CURSOR_AGENT、または CURSOR_EXTENSION_HOST_ROLE=agent-exec | Cursor のエージェント(CLI とエディター) |
CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_CI, CODEX_THREAD_ID | OpenAI Codex CLI |
GEMINI_CLI | 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 など、ほとんどの CI。CI=false や CI=0 は数えません。 |
意図的に除外しているものもあります。CURSOR_TRACE_ID と REPL_ID は、人間が使うものも含め、すべての Cursor のターミナルと Replit のシェルで設定されるからです。aider はターミナルなしでコマンドを実行するので、いずれにせよパイプの判定で捕捉されます。
色が付くのは、ターミナルでのテーブル表示だけです。NO_COLOR(任意の値)、TERM=dumb、--no-color で色をオフにできます。エージェントや CI に質問することは、--human を指定しても決してありません。
JSON の取り決め
-
stdout にはデータだけが出力されます。 一覧は、サーバー自身のオブジェクトの JSON 配列で、フィールド名はダッシュボードの API のままです。1 件のものはオブジェクトです。
-
ターミナルでは(
--json指定時)インデント付き、それ以外では 1 行です。 -
--followは 1 行に 1 つの JSON オブジェクトを出力します(NDJSON)。止めるまで、イベントごとに 1 つです。 -
一覧が
--limitやページで途中で切れたときは、stderr に続きの取り方を示す 1 行が出力されます。nextをフラグとして同じコマンドに渡してください。{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVh..."} {"more":true,"next":"--page 1"} -
失敗すると stderr に 1 行が出力され、終了コードとともに終了します。
{"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 になります。
終了コード
終了コードは変わらないので、スクリプトやエージェントはこれで分岐できます。
| コード | 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 |
--follow を Ctrl-C で止めた場合は、正常終了として 0 で終わります。
サインイン
エージェントは自分ではサインインできません。lyrelog login は、エージェントや 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 を実行すれば、そこにいるすべてのエージェントが、セッションが終わるまでそのサインインを使います(サインインを参照)。エージェントはその人として、その人のプロジェクトとロールで動きます。サーバーキー、読み取りキー、管理キーを作るには、さらにその人が過去 10 分以内にサインインしている必要があります。
CI や、人間がそばにいないエージェントでは、アクセストークンを使います。人間が lyrelog login の直後に lyrelog tokens create で、またはアカウントページで作成し、LYRELOG_TOKEN に設定します(スクリプトと CIを参照)。
エラーを調査させるプロンプト
アプリのリポジトリで、ターミナルから lyrelog login と lyrelog use <project> を実行したあと、これを Claude Code、Cursor などのコーディングエージェントに貼り付けてください。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.エージェントはこのドキュメントを Markdown としても読めます。AI エージェントと使うを参照してください。