Accès anticipéSur invitation, et les SDK ne sont pas encore publiés.Demander une invitation
Aller au contenu
Docs

Pour les agents et les scripts

Quand le CLI écrit du JSON, à quoi ressemble ce JSON, ses codes de sortie, et un prompt pour qu'un agent de code enquête sur une erreur.

L'outil en ligne de commande est fait pour être lancé par des programmes autant que par des personnes. Sous un agent de code, en CI ou dans un pipe, il écrit du JSON et rien d'autre : pas de couleurs, pas de spinner, pas de questions. Un agent de code peut alors chercher des événements, lire des erreurs et suivre une personne au fil d'une session aussi facilement que vous dans le tableau de bord.

JSON ou tableaux

Chaque exécution décide une fois, dans cet ordre :

  1. --human écrit des tableaux, même dans un pipe. --json écrit du JSON, même dans un terminal. Les deux ne peuvent pas aller ensemble.
  2. Sinon, il écrit du JSON quand stdout n'est pas un terminal (lyrelog errors | jq, > file.json), ou quand l'une des variables ci-dessous est définie.
  3. Sinon, dans un terminal, il écrit des tableaux.

Les agents lancent souvent les commandes dans un pseudo-terminal : vérifier le terminal ne suffit donc pas. Ces variables comptent :

VariableDéfinie par
LYRELOG_AGENTVous : donnez-lui n'importe quelle valeur pour forcer le mode agent partout
AI_AGENTLa convention commune aux outils : Claude Code la définit, @vercel/detect-agent de Vercel la lit
AGENTAmp (AGENT=amp), Goose (AGENT=goose) ; aussi 1 ou true. Toute autre valeur est ignorée : le nom est trop courant
CLAUDECODE, CLAUDE_CODE_ENTRYPOINTClaude Code, dans chaque shell qu'il lance
CURSOR_AGENT, ou CURSOR_EXTENSION_HOST_ROLE=agent-execL'agent de Cursor (CLI et éditeur)
CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_CI, CODEX_THREAD_IDOpenAI Codex CLI
GEMINI_CLIL'outil shell de Gemini CLI
OPENCODE=1, OPENCODE_CLIENTopencode
AMP_CURRENT_THREAD_IDAmp
AUGMENT_AGENT, ANTIGRAVITY_AGENTAugment, Antigravity
CIGitHub Actions, GitLab CI, CircleCI, Buildkite et la plupart des autres. CI=false ou CI=0 ne compte pas.

Certaines sont écartées volontairement. CURSOR_TRACE_ID et REPL_ID sont définies dans chaque terminal Cursor et chaque shell Replit, y compris ceux d'une personne. aider lance les commandes sans terminal : la vérification du pipe le détecte de toute façon.

Les couleurs n'apparaissent que dans les tableaux, dans un terminal. NO_COLOR (n'importe quelle valeur), TERM=dumb et --no-color les désactivent. On ne pose jamais de question à un agent ni à une CI, même avec --human.

Le contrat JSON

  • stdout ne porte que les données. Une liste est un tableau JSON des objets tels que le serveur les renvoie, avec les noms de champs de l'API du tableau de bord inchangés. Un élément seul est un objet.

  • Indenté dans un terminal (avec --json), sur une ligne sinon.

  • --follow écrit un objet JSON par ligne (NDJSON), un par événement, jusqu'à ce qu'on l'arrête.

  • Quand une liste a été coupée, par --limit ou par pages, stderr reçoit une ligne qui dit comment obtenir la suite. Passez next comme options à la même commande :

    {"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVh..."}
    {"more":true,"next":"--page 1"}
  • Un échec écrit une ligne sur stderr et se termine avec un code :

    {"error":"This needs a recent sign-in","hint":"Run lyrelog login again, then retry within 10 minutes.","code":"reauth_required","status":403}

    error et hint s'adressent aux personnes. code est stable, pour les programmes. status est le statut HTTP, quand le serveur a répondu. retry_after est en secondes, quand le serveur a demandé d'attendre.

  • Ce qui est irréversible exige --yes : révoquer une clé, supprimer les données d'une personne, retirer quelqu'un d'une organisation, supprimer une vue enregistrée. Personne ne peut répondre à une question : sans --yes, la commande s'arrête avec le code de sortie 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}}]

et sur stderr :

{"more":true,"next":"--cursor MTc5NTE2NzAwNzQ4NTphZGVhMzNlNC0yNmViLTQyMmUtYjkwNC05NjY0OWMwZTc4MzA"}

Les heures sont en millisecondes Unix. Quelques autres exemples :

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}]

Les noms de champs sont ceux de l'API : un nombre de personnes s'appelle players, quel que soit le mot choisi par le projet.

Codes de sortie

Ils sont stables : scripts et agents peuvent s'appuyer dessus.

CodecodeSignification
0Terminé
1errorAutre chose a échoué (le serveur, un fichier)
2usageCommande, option ou valeur incorrecte ; ou il faut --yes
3not_signed_inNon connecté, ou la session s'est terminée : lyrelog login
4reauth_requiredL'action demande une connexion datant de moins de 10 minutes : lyrelog login, puis réessayez
5forbiddenConnecté, mais pas autorisé (une action de propriétaire)
5browser_onlySeul le tableau de bord le permet : supprimer le compte ou un projet, changer votre façon de vous connecter. L'erreur nomme la page. Aussi quand un jeton d'accès essaie de créer ou de modifier des jetons
6not_foundProjet, événement, clé ou personne introuvable (ou qui n'est pas à vous)
7refusedLe serveur a refusé la requête en l'état (un 400 ou un 409, par exemple)
8rate_limitedTrop de requêtes, ou le serveur est occupé : attendez retry_after
9networkLe serveur était injoignable
130interruptedCtrl-C

Arrêter --follow avec Ctrl-C le termine normalement, avec 0.

Se connecter

Un agent ne peut pas se connecter tout seul. lyrelog login refuse de s'exécuter sous un agent ou en 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"}

Une personne lance lyrelog login une fois, dans un terminal de cet ordinateur, et tous les agents de cet ordinateur utilisent cette connexion jusqu'à ce qu'elle se termine (voir Se connecter). L'agent agit au nom de cette personne, avec ses projets et son rôle. Pour créer une clé serveur, de lecture ou d'administration, il faut en plus que cette personne se soit connectée dans les 10 dernières minutes.

En CI, ou pour un agent sans personne sous la main, utilisez un jeton d'accès : une personne en crée un avec lyrelog tokens create juste après lyrelog login, ou sur la page du compte, et le définit comme LYRELOG_TOKEN (voir Scripts et CI).

Un prompt pour enquêter sur une erreur

Collez ceci dans Claude Code, Cursor ou un autre agent de code, dans le dépôt de l'app, après avoir lancé lyrelog login et lyrelog use <project> dans un terminal sur cette machine. Mettez le nom de l'erreur à la place de 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.

Les agents lisent aussi cette documentation en Markdown : voir Utiliser avec des agents IA.