Référence de la CLI LogBrew : commandes et filtres

La CLI LogBrew open source lit la télémétrie et gère les données du compte depuis un terminal. Commencez par le guide Utiliser la CLI pour l’installation, la connexion et les tâches courantes.

Fonctionnement de la CLI

Dans un terminal, utilisez la sortie texte lisible. Utilisez --json dans les scripts et avec les agents de codage. La connexion au compte est nécessaire pour lire les données du compte. Avant de lancer une connexion, exécutez logbrew status --json. Une personne doit terminer l’autorisation dans le navigateur. Les clés d’ingestion de projet envoient la télémétrie. Elles ne remplacent pas la connexion au compte. La création de projets et de clés, les modifications du statut, de la priorité et du responsable des problèmes, les déploiements et les mises à jour du support modifient les données du compte. Avant de lancer l’une de ces opérations, vérifiez que l’action et la cible sont correctes. Exécutez logbrew --help pour voir toutes les commandes. Ajoutez --help à une commande, comme logbrew read logs --help, pour voir ses options. Exécutez logbrew help json pour les règles JSON.

Famille de commandes	Rôle
`login`, `whoami`, `me`, `logout`	Lancer la connexion, lire l’identité du compte ou fermer la session locale.
`status`, `health`, `doctor`, `version`, `examples`	Lire l’accès, l’état de préparation du projet, la version de la CLI ou des exemples pour démarrer.
`setup`	Lire les manifestes locaux et afficher un plan de configuration du SDK. Ne modifie aucun fichier et n’exécute pas la commande d’installation.
`projects`	Lire le catalogue des projets actifs.
`projects repositories`	Lire les dépôts connectés ou découvrir les composants d’un dépôt.
`projects create`, `projects keys create`	Créer un projet, ou créer une clé d’ingestion pour un projet existant.
`projects setup`	Enregistrer la configuration observée d’un projet existant.
`projects archive`, `projects delete`	Archiver un projet, ou le supprimer définitivement après confirmation.
`usage`, `account usage`	Lire l’utilisation, les limites, l’état des quotas et les dates de réinitialisation.
`mcp grants`, `mcp revoke`	Lister par nom les clients MCP connectés à votre compte, ou révoquer une connexion.
`read`	Lire les logs, problèmes, actions, versions, métriques, traces, ou un seul élément.
`explain`	Lire des preuves limitées pour un problème, un log, une action, une trace, un span, une métrique ou une version.
`investigate issue`	Lire les preuves de l’investigation d’un problème, ou vérifier un déploiement candidat.
`issues archive`, `issues resolve`, `issues reopen`	Définir le statut d’un seul problème, ou de 100 problèmes au plus dans un projet.
`issues priority`	Définir la priorité d’un seul problème, ou de 100 problèmes au plus dans un projet.
`issues assign`, `issues unassign`	Définir ou retirer le responsable (un compte ou une équipe) d’un seul problème, ou de 100 problèmes au plus dans un projet.
`issues assignees`	Lister les comptes et les équipes auxquels des problèmes peuvent être attribués dans un projet.
`issues owners`	Lister les propriétaires suggérés d’un problème.
`issues ownership`	Lire ou définir les règles de propriété et le fichier CODEOWNERS d’un projet.
`issues activity`	Lire l’historique des changements d’un problème.
`issues rule`, `logs rule`	Définir la règle de gravité d’un problème ou d’une signature de log.
`inbox`	Lire les problèmes que d’autres personnes vous ont attribués, à vous ou à vos équipes, ou les marquer comme lus.
`set issue`, `resolve`, `close`, `ignore`, `reopen`	Définir le statut d’un seul problème. `close` signifie `resolved`. `ignore` et `ignored` signifient `archived`.
`deploy`	Enregistrer un déploiement terminé.
`debug-artifacts`	Importer des fichiers de débogage natifs Apple ou Android, ou rechercher l’identité d’une image.
`analytics`	Lire la vue d’ensemble, les propriétés, les comparaisons, les parcours, les entonnoirs, la rétention ou le cycle de vie.
`support`	Créer, lire, fermer ou rouvrir des tickets de support, ou y répondre.
`watch`	Diffuser en direct les logs, problèmes ou actions.

Lire le rapport de diagnostic d’un projet

Utilisez un ID de projet issu de logbrew projects --json :

logbrew doctor --project "<project_id>" --json

La commande lit l’état du projet et un log récent. Elle ne crée pas de projet, ne modifie pas de clé et n’enregistre pas de configuration. Le rapport contient status, checks et next. Chaque vérification contient check, status et next. Les vérifications sont api, auth, project, ingest_key, setup, telemetry et logs. Le code de sortie 0 signifie que la CLI a écrit un rapport. Il ne signifie pas que le projet est prêt. Lisez le status du rapport et chaque vérification. Une vérification not_checked n’a pas réussi.

`status` du rapport	Signification et étape suivante
`auth_invalid`	L’accès au compte est manquant ou invalide. Une personne exécute `logbrew login`.
`project_missing`	Ce compte n’a pas accès au projet. Utilisez un ID issu de `logbrew projects --json`.
`api_unreachable`	La requête à l’API n’a pas abouti. Examinez la connexion réseau, puis relancez la commande.
`check_failed`	Une requête a échoué ou sa réponse était invalide. Relancez la commande sans rien changer. Si elle échoue encore, signalez un problème.
`needs_ingest_key`	Le projet n’a pas de clé d’ingestion active. Ne créez une clé qu’avec l’autorisation de modifier le projet.
`needs_setup`	La configuration du SDK est nécessaire. Suivez le démarrage rapide.
`needs_telemetry`	La configuration a commencé, mais LogBrew n’a aucune télémétrie pour le projet. Envoyez un signal de test.
`ready`	Le projet a une clé active et de la télémétrie. Lisez le signal utile à votre tâche.

Quand la lecture du projet réussit, la vérification logs vaut visible, empty, unavailable, error ou invalid_response. Cette vérification ne modifie pas le status du rapport. Un résultat de logs vide n’indique rien sur les autres signaux. Une lecture échouée n’est pas un résultat vide. Utilisez next comme indication de correction. Il n’autorise pas à modifier l’état du compte ou du projet.

Exemple : accès au compte manquant

Sans identifiants de compte, la commande n’envoie aucune requête à l’API. Elle écrit ce rapport sur la sortie standard et quitte avec le code 0 :

{
  "checks": [
    { "check": "api", "next": "run the API reachability check first", "status": "not_checked" },
    { "check": "auth", "next": "run logbrew login", "status": "missing" },
    { "check": "project", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "ingest_key", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "setup", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "telemetry", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "logs", "next": "resolve the prior check first", "status": "not_checked" }
  ],
  "next": "run logbrew login",
  "status": "auth_invalid"
}

Ce rapport est différent du diagnostic de projet par l’API. Il ne contient pas les champs d’API state, setup_status ni next_action.

Filtres

Filtre	Commandes
`--project <project_id>`	logs, issues, actions, releases, metrics, traces, trace
`--release <release>`	logs, issues, actions, releases, metrics, traces, trace
`--environment <environment>`	logs, issues, actions, releases, metrics, traces, trace
`--service <service_name>`	logs, issues, actions, releases, metrics, traces
`--since 24h`	logs, issues, actions, releases, metrics, traces, analytics
`--until <RFC3339>`	logs, issues, actions, releases, metrics, traces, analytics
`--limit 100`	logs, issues, actions, releases, metrics, traces
`--severity error`	logs, watch
`--search checkout`	logs
`--trace <trace_id>`	logs
`--status unresolved`	issues (`unresolved`, `resolved`, `archived`)
`--priority high`	issues (`high`, `medium`, `low`)
`--assignee me`	issues (`me`, `none`, `my_teams`, un ID d’utilisateur ou `team:<team_id>`)
`--status error`	traces (`error`, `ok`)
`--min-duration-ms <milliseconds>`	traces
`--name <name>`	actions, metrics
`--user <distinct_id>`	actions

--since accepte une durée comme 24h ou 7d, ou un horodatage RFC 3339. --until accepte un horodatage RFC 3339. C’est une heure de fin exclue, qui doit être postérieure à --since. La lecture d’un seul problème par ID n’accepte pas --until. La gravité d’un log vaut info, warning, error ou critical. Le statut d’un problème est son état dans le workflow, pas sa gravité. --status ignored est un ancien nom de --status archived. --status open signifie unresolved, et --status closed signifie resolved. --assignee none sélectionne les problèmes sans responsable, et --assignee my_teams sélectionne les problèmes de vos équipes. Toute autre valeur de --assignee échoue avec invalid_assignee. La CLI accepte aussi ces alias : --project-id, --env, --service-name, --trace-id, --distinct-id, et --level pour --severity. Utilisez les noms du tableau dans les nouveaux scripts. Cette commande lit les erreurs d’une journée :

logbrew read logs --severity error \
  --since 2026-10-01T00:00:00Z --until 2026-10-02T00:00:00Z --json

L’ID du projet sélectionne le projet. Le nom du service sélectionne un composant de ce projet. Mettez entre guillemets les valeurs qui contiennent des espaces :

logbrew read logs --project "<project_id>" \
  --service checkout-api --since 24h \
  --severity error --search "checkout failed" --json

Pour un texte de recherche qui commence par un tiret, placez -- avant le texte :

logbrew logs --json -- --timeout

Sélectionner une occurrence d’un problème

Un problème regroupe des occurrences correspondantes. Lisez le problème pour obtenir son statut, son nombre d’occurrences et les dates de première et de dernière occurrence :

logbrew read issue "<issue_id>" --json

Utilisez explain issue ou investigate issue pour les preuves d’une occurrence. Sans --occurrence, LogBrew sélectionne l’occurrence recommandée. Ce n’est pas toujours la plus récente. Pour lire la plus récente :

logbrew explain issue "<issue_id>" --occurrence latest --json

--occurrence accepte aussi recommended, first ou un ID d’occurrence renvoyé par LogBrew. Ces commandes refusent les filtres de projet, de version, d’environnement et de temps. Avant de comparer des preuves, lisez l’horodatage de l’occurrence sélectionnée. Consultez Investiguer un problème pour les champs de preuves.

Modifier le statut et la priorité des problèmes

Pour modifier un seul problème, utilisez son ID :

logbrew issues archive "<issue_id>" --json
logbrew issues priority high "<issue_id>" --json

archive définit archived, resolve définit resolved et reopen définit unresolved. La priorité vaut high, medium ou low. Une priorité que vous définissez reste fixe. Sinon, la priorité suit la gravité du problème. Pour modifier plusieurs problèmes, ajoutez --project. Tous les problèmes doivent appartenir à ce projet. Une commande modifie 100 problèmes au plus :

logbrew issues resolve "<issue_id_1>" "<issue_id_2>" \
  --project "<project_id>" --json

Le résultat contient une entrée par problème. Chaque entrée vaut updated, unchanged ou not_found. Un problème unchanged avait déjà la valeur demandée. Vous pouvez relancer la même commande après une panne réseau. Ces commandes ne demandent pas de confirmation. Vérifiez d’abord les ID des problèmes. Les lectures et modifications de problèmes affichent archived au lieu de ignored, ainsi que la priority, la priority_source et l’assignee de chaque problème. Consultez la réponse d’un problème.

Attribuer des problèmes

Un problème a au plus un responsable : un compte ou une équipe. Listez les comptes et les équipes auxquels vous pouvez attribuer des problèmes dans un projet :

logbrew issues assignees --project "<project_id>" --json

Attribuez un problème à un compte, à vous-même avec me, ou à une équipe :

logbrew issues assign "<user_id>" "<issue_id>" --json
logbrew issues assign me "<issue_id>" --json
logbrew issues assign "team:<team_id>" "<issue_id>" --json

Retirez l’attribution :

logbrew issues unassign "<issue_id>" --json

Ajoutez --project pour modifier jusqu’à 100 problèmes de ce projet, comme pour le statut et la priorité. Un compte doit pouvoir lire le projet, et une équipe doit appartenir à l’organisation du projet. Pour trouver les problèmes qui vous sont attribués, à vous ou à vos équipes :

logbrew read issues --project "<project_id>" --assignee my_teams \
  --status unresolved --json

La sortie texte affiche le nom du responsable, ou team #<slug> pour une équipe. Si le compte n’a pas de nom, elle affiche l’adresse e-mail, puis l’ID de l’utilisateur. Un problème sans responsable affiche unassigned.

Propriétaires, historique et boîte de réception

logbrew issues owners "<issue_id>" --json
logbrew issues ownership --project "<project_id>" --json
logbrew issues ownership set --project "<project_id>" \
  --rules ownership.txt --codeowners .github/CODEOWNERS --json
logbrew issues activity "<issue_id>" --limit 50 --json
logbrew inbox --json
logbrew inbox read --json

issues owners liste les propriétaires suggérés et les preuves vérifiées. issues ownership set envoie des fichiers locaux de 128 Kio au plus chacun. Un fichier vide efface son texte. issues activity et inbox acceptent --limit de 1 à 200, ainsi que --cursor-time avec --cursor-id issus de next_cursor. Consultez Trouver le propriétaire d’un problème.

Définir des règles de gravité

logbrew issues rule "<issue_id>" warning --json
logbrew logs rule "<log_id>" info --ignore --json

La gravité vaut info, warning, error, critical ou source. source rétablit l’affichage de la gravité capturée. --ignore masque les logs correspondants dans la liste de logs par défaut. Sans --ignore, la règle les affiche.

Lire la page suivante

Les logs, problèmes, actions, métriques et traces acceptent la pagination par curseur. Les versions ne l’acceptent pas. Utilisez --pagination cursor pour la première page :

logbrew read logs --project "<project_id>" --since 24h \
  --pagination cursor --limit 100 --json

La réponse contient logs et next_cursor. Un next_cursor non nul contient time et id. Envoyez-les avec --cursor-time et --cursor-id :

logbrew read logs --project "<project_id>" --since 24h \
  --pagination cursor --limit 100 \
  --cursor-time "<returned_time>" \
  --cursor-id "<returned_id>" --json

Gardez les mêmes filtres et la même limite sur chaque page. Arrêtez-vous quand next_cursor vaut null. Utilisez le curseur, pas le nombre de lignes, pour savoir s’il reste des pages. La dernière page peut être vide :

{
  "logs": [],
  "next_cursor": null
}

Les problèmes, actions et métriques utilisent la même forme, avec issues, actions ou metrics à la place de logs.

Suivi en direct

logbrew watch --json diffuse en direct les logs, problèmes et actions. Ajoutez logs, issues ou actions pour diffuser un seul type. tail, follow et stream sont des alias de watch. Le suivi ne prend pas en charge les traces ni les spans. Le suivi nécessite --json. Sans cette option, la commande écrit watch streams JSON for agents et quitte avec le code 1. Dans les événements de problèmes du suivi, un problème archivé apparaît comme ignored, sans priorité. Lisez le problème pour obtenir son statut et sa priorité actuels. Le suivi accepte uniquement --severity, comme --severity error,critical. logbrew watch actions n’accepte pas --severity. La CLI applique ce filtre après avoir reçu les événements. Il ne réduit pas ce que le serveur envoie. Le suivi n’a pas de filtre de projet, de version, d’environnement ni de temps. Pour ces filtres, utilisez une commande read. Après une déconnexion temporaire, la CLI attend, puis se reconnecte.

Lire les résultats et les erreurs

Placez --json avant ou après la commande. Lisez le code de sortie avant d’utiliser la sortie. N’analysez pas la sortie lisible par un humain : elle peut changer d’une version à l’autre.

Code de sortie	Signification
`0`	Succès. Le JSON est sur la sortie standard.
`1`	La commande a échoué pendant son exécution, par exemple à cause d’une erreur d’API ou de réseau.
`2`	La CLI a refusé la commande avant son exécution.

En cas de succès, la sortie garde la forme de la réponse de l’API. Ce peut être un tableau ou un objet. Sans pagination par curseur, une lecture de logs renvoie un tableau. Un tableau vide signifie qu’aucun log ne correspond. Ce n’est pas une erreur. Les erreurs vont sur la sortie d’erreur standard. L’exception est debug-artifacts --json, qui écrit les erreurs sur la sortie standard. Une erreur JSON contient ok, error, message et next. Utilisez error comme code d’échec stable. Examinez next avant d’exécuter la commande qu’il suggère. Par exemple, logbrew watch traces --json quitte avec le code 2 et écrit :

{
  "ok": false,
  "error": "unknown_resource",
  "message": "unknown resource: traces",
  "next": "use logbrew traces for recent traces, or logbrew trace <trace_id> for one trace"
}

logbrew read logs --limit 0 --json quitte avec le code 2 et écrit :

{
  "ok": false,
  "error": "invalid_limit",
  "message": "invalid limit: 0",
  "next": "use --limit with a positive whole number"
}

Corrigez la valeur et relancez la commande. Une commande refusée n’est pas un résultat vide. Consultez Erreurs de l’API pour les erreurs HTTP et l’API de télémétrie pour les requêtes directes à l’API.

​Fonctionnement de la CLI

​Lire le rapport de diagnostic d’un projet

​Exemple : accès au compte manquant

​Filtres

​Sélectionner une occurrence d’un problème

​Modifier le statut et la priorité des problèmes

​Attribuer des problèmes

​Propriétaires, historique et boîte de réception

​Définir des règles de gravité

​Lire la page suivante

​Suivi en direct

​Lire les résultats et les erreurs