Early AccessNur auf Einladung, und die SDKs sind noch nicht veröffentlicht.Einladung anfragen
Zum Inhalt springen
Docs

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:

  1. --human schreibt Tabellen, auch in eine Pipe. --json schreibt JSON, auch im Terminal. Beide zusammen gehen nicht.
  2. Andernfalls schreibt es JSON, wenn stdout kein Terminal ist (lyrelog errors | jq, > file.json) oder wenn eine der Variablen unten gesetzt ist.
  3. 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:

VariableGesetzt von
LYRELOG_AGENTDir: Setze sie auf einen beliebigen Wert, um den Agentenmodus überall zu erzwingen
AI_AGENTDer toolübergreifenden Konvention: Claude Code setzt sie, @vercel/detect-agent von Vercel liest sie
AGENTAmp (AGENT=amp), Goose (AGENT=goose); außerdem 1 oder true. Jeder andere Wert wird ignoriert: Der Name ist zu verbreitet
CLAUDECODE, CLAUDE_CODE_ENTRYPOINTClaude Code, in jeder Shell, die es startet
CURSOR_AGENT oder CURSOR_EXTENSION_HOST_ROLE=agent-execDem Agenten von Cursor (CLI und Editor)
CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_CI, CODEX_THREAD_IDOpenAI Codex CLI
GEMINI_CLIDem Shell-Tool von Gemini CLI
OPENCODE=1, OPENCODE_CLIENTopencode
AMP_CURRENT_THREAD_IDAmp
AUGMENT_AGENT, ANTIGRAVITY_AGENTAugment, Antigravity
CIGitHub 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.

  • --follow schreibt ein JSON-Objekt pro Zeile (NDJSON), eines pro Event, bis es gestoppt wird.

  • Wenn eine Liste gekürzt wurde, durch --limit oder durch Seiten, bekommt stderr eine Zeile, die sagt, wie du den Rest bekommst. Übergib next als 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}

    error und hint sind für Menschen. code ist stabil, für Programme. status ist der HTTP-Status, wenn der Server geantwortet hat. retry_after ist 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 --yes mit 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.

CodecodeBedeutung
0Fertig
1errorEtwas anderes ist fehlgeschlagen (der Server, eine Datei)
2usageEin falscher Befehl, ein falsches Flag oder ein falscher Wert; oder --yes ist nötig
3not_signed_inNicht angemeldet oder die Session ist abgelaufen: lyrelog login
4reauth_requiredDie Aktion braucht eine Anmeldung aus den letzten 10 Minuten: lyrelog login, dann erneut versuchen
5forbiddenAngemeldet, aber nicht erlaubt (eine Aktion für Inhaber)
5browser_onlyDas 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
6not_foundProjekt, Event, Schlüssel oder Person nicht gefunden (oder sie gehören nicht dir)
7refusedDer Server hat die Anfrage so, wie sie ist, abgelehnt (etwa mit 400 oder 409)
8rate_limitedZu viele Anfragen oder der Server ist ausgelastet: retry_after abwarten
9networkDer Server war nicht erreichbar
130interruptedCtrl-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.