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 CLIagenteye, 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 :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) :
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 :
agenteye :
Remarque : Le SDK Python d’Observabilité Failproof AI utilise également le nom de distributionagenteye. Installer la CLI avecpipxouuv tool(plutôt quepip installdans un virtualenv partagé) évite les conflits entre les deux. Un simplepip install agenteyeconvient 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 :~/.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 :--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) :
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 erreurCERTIFICATE_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=1dans l’environnement de la CLI (la CLI respecte également la convention inter-outilsDO_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 sessionsest correct ;agenteye sessions --jsonest une erreur d’utilisation. Les options globales sont--json,--base-url,--org,--token,--insecure/--secure,--timeout,--quietet--no-color. --jsonaffiche 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--jsonreste propre pour être canalisée dansjqmê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--helppar commande, ainsi queagenteye query schemaetagenteye settings schemaspé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
--jsonou 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/-ypour 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 ;--allpagine automatiquement (par blocs de 200 lignes) jusqu’à--limit, donc un simple--alls’arrête toujours à 50. Pour un balayage complet, passez une limite explicite élevée :--all --limit 1000.--page-size Ncontrôle la taille des blocs par requête (max 200) ;--cursor <id>reprend à partir dunext_cursord’une page précédente. - Filtres temporels :
--sinceaccepte une fenêtre relative :15m,1h,6h,24h,7d, ouall(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 avecTet 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(surevents,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 (suralerts create/update,settings setetusers 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 bne 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.
(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.add → events: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 askutilise.

