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 :
--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.- 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. - 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 :
| Variable | Définie par |
|---|---|
LYRELOG_AGENT | Vous : donnez-lui n'importe quelle valeur pour forcer le mode agent partout |
AI_AGENT | La convention commune aux outils : Claude Code la définit, @vercel/detect-agent de Vercel la lit |
AGENT | Amp (AGENT=amp), Goose (AGENT=goose) ; aussi 1 ou true. Toute autre valeur est ignorée : le nom est trop courant |
CLAUDECODE, CLAUDE_CODE_ENTRYPOINT | Claude Code, dans chaque shell qu'il lance |
CURSOR_AGENT, ou CURSOR_EXTENSION_HOST_ROLE=agent-exec | L'agent de Cursor (CLI et éditeur) |
CODEX_SANDBOX, CODEX_SANDBOX_NETWORK_DISABLED, CODEX_CI, CODEX_THREAD_ID | OpenAI Codex CLI |
GEMINI_CLI | L'outil shell de 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 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
--limitou par pages, stderr reçoit une ligne qui dit comment obtenir la suite. Passeznextcomme 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}errorethints'adressent aux personnes.codeest stable, pour les programmes.statusest le statut HTTP, quand le serveur a répondu.retry_afterest 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.
| Code | code | Signification |
|---|---|---|
| 0 | Terminé | |
| 1 | error | Autre chose a échoué (le serveur, un fichier) |
| 2 | usage | Commande, option ou valeur incorrecte ; ou il faut --yes |
| 3 | not_signed_in | Non connecté, ou la session s'est terminée : lyrelog login |
| 4 | reauth_required | L'action demande une connexion datant de moins de 10 minutes : lyrelog login, puis réessayez |
| 5 | forbidden | Connecté, mais pas autorisé (une action de propriétaire) |
| 5 | browser_only | Seul 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 |
| 6 | not_found | Projet, événement, clé ou personne introuvable (ou qui n'est pas à vous) |
| 7 | refused | Le serveur a refusé la requête en l'état (un 400 ou un 409, par exemple) |
| 8 | rate_limited | Trop de requêtes, ou le serveur est occupé : attendez retry_after |
| 9 | network | Le serveur était injoignable |
| 130 | interrupted | Ctrl-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.