Skip to main content
Pilotez toute l’Observabilité Failproof AI depuis le terminal ou un script : sans aller-retours vers le tableau de bord. La CLI agenteye interroge vos données (sessions, journaux d’événements, évaluations) et administre votre organisation (clés API, utilisateurs, paramètres, alertes, incidents, requêtes sauvegardées), afin que vous puissiez automatiser une vérification, intégrer l’Observabilité dans votre CI ou permettre à un agent de code d’inspecter la production. Chaque commande prend en charge un flag --json, ce qui la rend tout aussi utile à la ligne de commande ou pour un agent de code (Claude Code, Cursor) qui exécute des commandes shell et analyse les résultats. Avec un seul binaire, vous pouvez :
  • Lire vos données : sessions, events, evals, errors (filtrage par heure, agent, environnement, score).
  • Gérer votre organisation : keys, users, settings, alerts, incidents.
  • Lancer des analyses : SQL sauvegardé et exécuteur de requêtes ad hoc (query).
  • Interroger l’assistant IA : le même analyste en lecture seule que vous utilisez dans le tableau de bord (agent).
Remarque : Il s’agit de la CLI agenteye, un outil distinct du démon collecteur (agenteye-collector). La CLI communique avec votre tableau de bord ; le collecteur achemine les événements vers le serveur.

Démarrage rapide

De zéro à votre premier résultat en quatre lignes. Pointez la CLI vers votre tableau de bord, connectez-vous, confirmez votre identité, puis récupérez les exécutions du dernier jour :
Cette dernière commande affiche un objet JSON des sessions les plus récentes (les plus récentes en premier, limité à 50 par défaut). Canalisez-le dans jq pour le découper, ou supprimez --json pour un tableau encadré et colorisé. Chaque ligne contient le statut de l’exécution et, si un évaluateur l’a scorée, ses scores de métriques (abrégés ici) :
Le reste de cette page explique chaque élément : l’installation en isolation, la connexion, la configuration, les conventions globales partagées par toutes les commandes, et la référence complète des commandes.

Installation

La CLI est un paquet PyPI public nommé agenteye. Installez-le dans un environnement isolé afin qu’il dispose toujours de ses propres dépendances :
Python 3.10+ est requis. La commande installée est agenteye :
Remarque : Le SDK Python d’Observabilité Failproof AI utilise également le nom de distribution agenteye. Installer la CLI avec pipx ou uv tool (plutôt que pip install dans un virtualenv partagé) évite les conflits entre les deux. Un simple pip install agenteye convient uniquement si le SDK n’est pas installé dans le même environnement.

Authentification

La CLI s’authentifie auprès du tableau de bord avec un code à usage unique envoyé par e-mail :
Le jeton de session est stocké dans ~/.agenteye/cli.json (lisible uniquement par vous, mode 0600) et est valide pendant 24 heures par défaut. Lorsqu’il expire, relancez agenteye login.
whoami ne génère jamais d’erreur en cas de session manquante ou expirée ; il renvoie logged_in: false à la place, afin qu’un script ou un agent puisse sonder l’état d’authentification en toute sécurité (il peut tout de même retourner un code non nul si aucune URL de base n’est définie ou si le tableau de bord est inaccessible). Prérequis : votre e-mail doit être autorisé à se connecter au tableau de bord (demandez à votre administrateur d’Observabilité Failproof AI), et le tableau de bord doit être accessible à son URL de base (voir Configuration). Si vous demandez un code et qu’il n’arrive pas, votre e-mail n’est probablement pas encore activé pour l’accès au tableau de bord.

Choisir votre organisation (multi-tenant)

Si votre compte appartient à plusieurs organisations, choisissez l’organisation active lors de la connexion ; elle est sauvegardée et utilisée pour toutes les commandes ultérieures :
Si vous n’appartenez qu’à une seule organisation, elle est sélectionnée automatiquement et vous pouvez ignorer --org entièrement. Si vous appartenez à plusieurs et que vous n’en choisissez pas une, la CLI les liste et vous demande de relancer avec --org <slug>. L’org active est transmise au tableau de bord à chaque requête, et vos permissions sont résolues par organisation ; agenteye whoami affiche l’org active, vos permissions en son sein, et toutes vos appartenances.

Configuration

L’ordre de résolution est flag → variable d’environnement → fichier de configuration. Il n’y a pas de valeur par défaut ; vous devez pointer la CLI vers votre tableau de bord, soit par commande (--base-url https://agenteye.example.com), soit une fois via l’environnement (elle est également sauvegardée après votre premier login) :
Le répertoire de configuration respecte AGENTEYE_HOME (la même convention utilisée par le SDK et le collecteur) ; si défini, cli.json se trouve dans $AGENTEYE_HOME/cli.json.

TLS auto-signé ou interne

Si votre tableau de bord est servi via HTTPS avec un certificat auto-signé ou interne (par exemple, un nom d’hôte de load-balancer brut), la vérification TLS le rejettera avec une erreur CERTIFICATE_VERIFY_FAILED. Utilisez --insecure pour ignorer la vérification du certificat :
--insecure est sauvegardé dans cli.json lors de la connexion, de sorte que les commandes ultérieures ignorent automatiquement la vérification ; vous n’avez pas à répéter le flag. Utilisez --secure pour un appel vérifié ponctuel, ou pour réactiver la vérification lors de votre prochaine connexion. La CLI affiche un avertissement sur stderr avant toute commande qui contacte le tableau de bord avec la vérification désactivée. Ignorer la vérification supprime la protection contre les attaques de type man-in-the-middle ; assurez-vous de faire confiance au chemin réseau vers votre tableau de bord (VPN, sous-réseau privé, etc.) avant de vous en remettre à cette option.

Télémétrie et confidentialité

Remarque : La CLI fournie n’envoie aucune télémétrie d’utilisation aujourd’hui. Un interrupteur maître est activé, de sorte que rien n’est transmis quelle que soit votre configuration. La section ci-dessous décrit la fonctionnalité de désactivation pour le cas où la télémétrie serait un jour activée.
Même si elle était activée, la télémétrie se limiterait à des analyses d’utilisation anonymes, jamais à vos données d’agent, de session ou d’événement :
  • Aucune donnée d’agent, de session ou d’événement ne quitte jamais votre infrastructure. Seule l’utilisation de la CLI serait rapportée : le nom de la commande et de la sous-commande (ex. keys create), les noms des flags utilisés (jamais leurs valeurs), le statut de succès/sortie, et la durée, ainsi qu’un événement par action pour les mutations (ex. api_key_created, query_run) ne comportant que des noms/enums statiques et des comptages grossiers. Votre URL de tableau de bord, jeton de session, e-mail, slug d’org, identifiants de ressources, SQL, secrets de clés et filtres de requêtes ne seraient jamais envoyés. Les opérateurs ne seraient identifiés que par un identifiant interne opaque, jamais par e-mail.
  • Désactivez à l’avance en définissant AGENTEYE_ANALYTICS_DISABLED=1 dans l’environnement de la CLI (la CLI respecte également la convention inter-outils DO_NOT_TRACK=1). Cela prend effet dès que la télémétrie serait activée, de sorte qu’un environnement soucieux de la confidentialité peut rester désactivé en permanence.
  • Si la télémétrie était activée, la CLI enverrait directement à PostHog (https://us.i.posthog.com) ; une machine avec cet hôte bloqué n’enverrait rien silencieusement et la CLI ne serait pas affectée.

Options globales et conventions

Lisez ceci une fois ; cela s’applique à chaque commande.
  • Les options globales vont AVANT la commande. agenteye --json sessions est correct ; agenteye sessions --json est une erreur d’utilisation. Les options globales sont --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet et --no-color.
  • --json affiche du JSON pur sur stdout, et rien d’autre. Les lignes de statut humain, les avertissements et les erreurs vont sur stderr, de sorte qu’une capture stdout avec --json reste propre pour être canalisée dans jq même lorsqu’une ligne de statut est affichée. Sans --json, vous obtenez une vue encadrée et colorisée pour les yeux humains.
  • Explorez avec --help. Chaque commande et sous-commande dispose de --help (et de l’alias -h) : agenteye -h, agenteye sessions -h, agenteye keys create -h. L’aide de niveau supérieur liste également les codes de sortie et les options globales. Il n’existe pas de surface lisible par machine globale ; utilisez --help par commande, ainsi que agenteye query schema et agenteye settings schema spécifiques au domaine pour ces deux registres.
  • Les confirmations sont ignorées automatiquement pour les scripts et les agents. Les commandes de création/mise à jour/suppression demandent “êtes-vous sûr ?” dans un terminal interactif, mais ignorent automatiquement cette invite sous --json ou lorsque stdin n’est pas un TTY (un TTY est une session de terminal interactive ; un pipe ou un runner CI ne l’est pas), de sorte que les scripts et les agents ne se bloquent jamais. Utilisez --yes/-y pour l’ignorer explicitement. Comme l’invite ne se déclenchera pas pour un agent, un agent devrait confirmer les actions destructrices avec l’humain en amont.
  • Pagination : les résultats sont classés du plus récent au plus ancien et paginés par curseur (chaque page retourne un jeton à utiliser pour récupérer la suivante). --limit N (alias -n) plafonne les lignes et vaut 50 par défaut ; --all pagine automatiquement (par blocs de 200 lignes) jusqu’à --limit, donc un simple --all s’arrête toujours à 50. Pour un balayage complet, passez une limite explicite élevée : --all --limit 1000. --page-size N contrôle la taille des blocs par requête (max 200) ; --cursor <id> reprend à partir du next_cursor d’une page précédente.
  • Filtres temporels : --since accepte une fenêtre relative : 15m, 1h, 6h, 24h, 7d, ou all (les présélections du tableau de bord). Pour une plage plus longue ou personnalisée (par exemple les 30 derniers jours), utilisez --from/--to : des horodatages UTC ISO-8601 explicites avec T et un fuseau horaire (ex. 2026-06-01T00:00:00Z) qui remplacent --since. Une valeur séparée par des espaces ou sans fuseau horaire est une erreur d’utilisation.
  • --fields a,b,c (sur events, sessions, evals, errors) restreint la sortie à ces clés, aussi bien pour le tableau que pour --json. Les noms inconnus sont rejetés avec la liste des noms valides, un moyen pratique de découvrir les noms de champs.
  • --file payload.json (ou --file - pour lire depuis stdin) fournit un corps de requête JSON complet lorsqu’une ressource a une forme complexe (sur alerts create/update, settings set et users create/update). Le SQL de requête sauvegardée utilise --sql @file.sql à la place.
  • Les filtres multi-valeurs sont séparés par des virgules → correspondance sous forme d’ensemble (union dans un filtre, ET entre filtres) : --event-type tool_use,tool_result. Les options Click ne sont pas variadiques, donc --add a b ne fonctionne pas. Utilisez --add a,b, répétez le flag (--add a --add b), ou mettez entre guillemets (--add "a b").

Référence des commandes

Les 5 commandes que vous utiliserez le plus

La plupart du travail quotidien passe par quelques commandes de lecture. Commencez ici, puis explorez la surface complète ci-dessous si nécessaire :

Tout ce que la CLI peut faire

La surface complète suit. La CLI dispose de 18 commandes de premier niveau. Toutes les commandes de lecture acceptent --json et les options globales ci-dessus ; exécutez agenteye <commande> -h (ou <commande> <sous-commande> -h) pour la liste exhaustive des flags et la structure JSON de n’importe quelle commande.

Identité : login · logout · whoami · orgs · version · help

orgs inspecte et change le tenant actif :

Observer (lecture seule) : events · sessions · evals · errors · list

Aucune de ces commandes n’a besoin de confirmation. Filtres partagés : --session-id, --agent-id, --env (pas --environment), et la plage temporelle (--since / --from / --to).
--score KEY:MIN..MAX (sur evals, pas sessions) est répétable et combiné par ET ; chaque borne est optionnelle (..0.5 signifie ≤ 0,5, 0.9.. signifie ≥ 0,9). Jusqu’à 20 filtres de score par requête. evals --scores-full est un flag d’affichage pour le tableau humain uniquement ; il affiche chaque paire de scores au lieu des premiers plus un comptage +N. Il n’a aucun effet sous --json, qui retourne toujours l’objet de score complet. Pour lire une session de bout en bout, combinez la trace d’événements avec son évaluation :

Gérer (soumis aux permissions) : keys · users · settings · alerts · incidents

keys : clés API. Le secret est généré localement, envoyé au serveur (qui n’en stocke qu’un hash), et affiché une seule fois lors de la création/regénération ; capturez-le à ce moment-là. Avec --json, il apparaît uniquement dans le champ key. Référencé par nom.
Les permissions fonctionnent comme (permission-set ∪ --add) − --remove. Les jetons sont slug:action (ex. events:read) ou slug:action.action pour développer plusieurs actions sur une ressource (events:read.addevents:read, events:add). Presets : read-only, standard, admin. Les permissions réservées aux humains (keys:update) ne peuvent pas être accordées à une clé. users : membres de l’organisation, référencés par e-mail (un id UUID est également accepté).
settings : un registre fixe (vous lisez et modifiez les clés existantes ; vous ne pouvez pas en créer de nouvelles).
alerts : définitions d’alertes, référencées par nom. create prend un NOM positionnel plus des flags ou un corps JSON complet via --file.
incidents : incidents d’alerte, référencés par id (ids courts acceptés). show affiche le journal d’activité complet ; lisez-le avant d’agir.

Analyses et assistant : query · agent

query : SQL sauvegardé contre votre entrepôt d’analyses plus un exécuteur ad hoc. Les requêtes sauvegardées sont référencées par nom ; le SQL est validé côté serveur (SELECT/WITH uniquement, délai d’expiration des instructions, plafond de lignes).
agent : communique avec l’assistant IA intégré (le même analyste en lecture seule que vous pouvez utiliser dans le tableau de bord). Les conversations sont référencées par un chat-id court (résolution par préfixe).

Codes de sortie

Ces codes rendent la CLI sûre à scripter : un agent de code peut brancher sur un 4 pour vous inviter à vous ré-authentifier, ou sur un 5 pour signaler la permission manquante. Voir Recettes CLI pour les agents pour les modèles de gestion des codes de sortie et les structures de sortie JSON.

Prochaines étapes

  • Recettes CLI pour les agents : modèles de requêtes à copier-coller, one-liners jq, projections --fields, gestion des codes de sortie et structures de sortie JSON, écrits pour les agents de code qui pilotent la CLI.
  • Compétence CLI pour agent : packagée cette CLI comme une compétence installable Claude Code / Codex afin qu’un agent de code pilote l’Observabilité Failproof AI à partir de requêtes en langage naturel.
  • Clés API : le modèle de permissions derrière keys create --add ….
  • Assistant IA : activation de l’assistant qu’agent ask utilise.