Für Agenten und Skripte
Wann die CLI JSON schreibt, wie das JSON aussieht, ihre Exit-Codes und ein Prompt, mit dem ein Coding-Agent einen Fehler untersucht.
Das Kommandozeilen-Tool ist dafür gemacht, von Programmen genauso ausgeführt zu werden wie von Menschen. Unter einem Coding-Agenten, in CI oder in einer Pipe schreibt es JSON und sonst nichts: keine Farben, keinen Spinner, keine Rückfragen. Ein Coding-Agent kann dann Events durchsuchen, Fehler lesen und eine Person durch eine Session verfolgen, so einfach wie du im Dashboard.
JSON oder Tabellen
Jeder Aufruf entscheidet einmal, in dieser Reihenfolge:
--humanschreibt Tabellen, auch in eine Pipe.--jsonschreibt JSON, auch im Terminal. Beide zusammen gehen nicht.- Andernfalls schreibt es JSON, wenn stdout kein Terminal ist (
lyrelog errors | jq,> file.json) oder wenn eine der Variablen unten gesetzt ist. - Andernfalls schreibt es im Terminal Tabellen.
Agenten führen Befehle oft in einem Pseudo-Terminal aus, daher reicht die Terminal-Prüfung allein nicht. Diese Variablen zählen:
| Variable | Gesetzt von |
|---|---|
LYRELOG_AGENT | Dir: Setze sie auf einen beliebigen Wert, um den Agentenmodus überall zu erzwingen |
AI_AGENT | Der toolübergreifenden Konvention: Claude Code setzt sie, @vercel/detect-agent von Vercel liest sie |
AGENT | Amp (AGENT=amp), Goose (AGENT=goose); außerdem 1 oder true. Jeder andere Wert wird ignoriert: Der Name ist zu verbreitet |
CLAUDECODE, CLAUDE_CODE_ENTRYPOINT | Claude Code, in jeder Shell, die es startet |
CURSOR_AGENT oder CURSOR_EXTENSION_HOST_ROLE=agent-exec | Dem Agenten von Cursor (CLI und Editor) |
CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_CI, CODEX_THREAD_ID | OpenAI Codex CLI |
GEMINI_CLI | Dem Shell-Tool von 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 und den meisten anderen. CI=false oder CI=0 zählt nicht. |
Manche fehlen absichtlich. CURSOR_TRACE_ID und REPL_ID sind in jedem Cursor-Terminal und
jeder Replit-Shell gesetzt, auch in denen eines Menschen. aider führt Befehle ohne Terminal aus,
also greift ohnehin die Pipe-Prüfung.
Farben erscheinen nur in Tabellen im Terminal. NO_COLOR (beliebiger Wert), TERM=dumb und
--no-color schalten sie ab. Einem Agenten oder CI wird nie eine Frage gestellt, auch nicht mit
--human.
Der JSON-Vertrag
-
stdout enthält nur die Daten. Eine Liste ist ein JSON-Array der Objekte des Servers, mit den unveränderten Feldnamen der Dashboard-API. Ein einzelnes Element ist ein Objekt.
-
Im Terminal eingerückt (mit
--json), sonst in einer Zeile. -
--followschreibt ein JSON-Objekt pro Zeile (NDJSON), eines pro Event, bis es gestoppt wird. -
Wenn eine Liste gekürzt wurde, durch
--limitoder durch Seiten, bekommt stderr eine Zeile, die sagt, wie du den Rest bekommst. Übergibnextals Flags an denselben Befehl:{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVh..."} {"more":true,"next":"--page 1"} -
Ein Fehlschlag schreibt eine Zeile auf stderr und endet mit einem Code:
{"error":"This needs a recent sign-in","hint":"Run lyrelog login again, then retry within 10 minutes.","code":"reauth_required","status":403}errorundhintsind für Menschen.codeist stabil, für Programme.statusist der HTTP-Status, wenn der Server geantwortet hat.retry_afterist in Sekunden, wenn der Server um Warten gebeten hat. -
Was sich nicht rückgängig machen lässt, braucht
--yes: einen Schlüssel widerrufen, die Daten einer Person löschen, jemanden aus einer Organisation entfernen, eine gespeicherte Ansicht löschen. Niemand kann eine Frage beantworten, also bricht es ohne--yesmit Exit-Code 2 ab.
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}}]und auf stderr:
{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVhMzNlNC0yNmViLTQyMmUtYjkwNC05NjY0OWMwZTc4MzA"}Zeiten sind Unix-Millisekunden. Noch ein paar Beispiele:
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}]Die Feldnamen sind die der API, eine Zahl von Personen heißt also players, egal wie das Projekt
sie nennt.
Exit-Codes
Sie sind stabil: Skripte und Agenten können danach verzweigen.
| Code | code | Bedeutung |
|---|---|---|
| 0 | Fertig | |
| 1 | error | Etwas anderes ist fehlgeschlagen (der Server, eine Datei) |
| 2 | usage | Ein falscher Befehl, ein falsches Flag oder ein falscher Wert; oder --yes ist nötig |
| 3 | not_signed_in | Nicht angemeldet oder die Session ist abgelaufen: lyrelog login |
| 4 | reauth_required | Die Aktion braucht eine Anmeldung aus den letzten 10 Minuten: lyrelog login, dann erneut versuchen |
| 5 | forbidden | Angemeldet, aber nicht erlaubt (eine Aktion für Inhaber) |
| 5 | browser_only | Das geht nur im Dashboard: das Konto oder ein Projekt löschen, ändern, wie du dich anmeldest. Der Fehler nennt die Seite. Ebenso, wenn ein Access Token Tokens erstellen oder ändern will |
| 6 | not_found | Projekt, Event, Schlüssel oder Person nicht gefunden (oder sie gehören nicht dir) |
| 7 | refused | Der Server hat die Anfrage so, wie sie ist, abgelehnt (etwa mit 400 oder 409) |
| 8 | rate_limited | Zu viele Anfragen oder der Server ist ausgelastet: retry_after abwarten |
| 9 | network | Der Server war nicht erreichbar |
| 130 | interrupted | Ctrl-C |
Stoppst du --follow mit Ctrl-C, endet es normal, mit 0.
Anmelden
Ein Agent kann sich nicht selbst anmelden. lyrelog login verweigert die Ausführung unter einem
Agenten oder in 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"}Ein Mensch führt lyrelog login einmal in einem Terminal auf diesem Computer aus, und jeder
Agent dort nutzt diese Anmeldung, bis sie endet (siehe Anmelden). Der
Agent handelt als diese Person, mit ihren Projekten und ihrer Rolle. Für einen Server-, Lese-
oder Admin-Schlüssel muss sich diese Person außerdem in den letzten 10 Minuten angemeldet haben.
In CI oder für einen Agenten ohne Menschen in der Nähe verwendest du einen Access Token: Ein
Mensch erstellt ihn mit lyrelog tokens create direkt nach lyrelog login oder auf der
Kontoseite und setzt ihn als LYRELOG_TOKEN (siehe Skripte und CI).
Ein Prompt, um einen Fehler zu untersuchen
Füge das in Claude Code, Cursor oder einen anderen Coding-Agenten im Repository der App ein,
nachdem du dort in einem Terminal lyrelog login und lyrelog use <project> ausgeführt hast.
Setze den Namen des Fehlers anstelle von cloud_save_failed ein.
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.Agenten lesen diese Docs auch als Markdown: siehe Mit KI-Agenten verwenden.