CLI - FailproofAI

La CLI AgentEye (agenteye) est un client terminal pour votre déploiement AgentEye. Elle interroge vos données (sessions, journaux d’événements, évaluations) et administre l’organisation (clés API, utilisateurs, paramètres, alertes, incidents, requêtes sauvegardées) — tout ce que fait le tableau de bord, depuis un script ou un agent de codage. Chaque commande accepte un indicateur --json, ce qui la rend aussi bien adaptée à une utilisation humaine en ligne de commande qu’à un agent de codage (Claude Code, Cursor) qui l’exécute et analyse le résultat.

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 envoie les événements au serveur. Consultez Installation du collecteur pour le collecteur.

Installation

La CLI est publiée sur PyPI public sous le nom agenteye. Comme le SDK Python AgentEye utilise également le nom de distribution agenteye, installez la CLI dans un environnement isolé (pipx ou uv tool) pour éviter tout conflit dans un même virtualenv :

pipx install agenteye
# ou
uv tool install agenteye

Un simple pip install agenteye fonctionne également si vous n’installez pas le SDK Python dans le même environnement. La CLI nécessite Python 3.10+ et n’a pas besoin de jeton GitHub ; c’est un paquet public. La commande installée est agenteye :

agenteye --version
agenteye --help

Authentification

La CLI s’authentifie auprès du tableau de bord via un code à usage unique envoyé par e-mail :

agenteye login --email you@example.com
# Un code à 6 chiffres vous est envoyé par e-mail ; collez-le à l'invite.

Le jeton de session est stocké dans ~/.agenteye/cli.json (accessible uniquement par vous, mode 0600) et est valide 24 heures par défaut. À expiration, relancez agenteye login.

agenteye whoami     # affiche l'utilisateur actuel, l'organisation active et les permissions
agenteye logout     # révoque la session et efface le jeton stocké

whoami ne génère jamais d’erreur en cas de session manquante ou expirée — il indique logged_in: false à la place, ce qui permet à un script ou agent de vérifier l’état d’authentification sans risque (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 (contactez votre administrateur AgentEye), 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 son 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 :

agenteye login --org acme           # s'authentifier et définir le tenant actif en une étape
agenteye orgs list                  # les organisations auxquelles vous avez accès (l'active est signalée)
agenteye orgs switch globex         # changer l'organisation par défaut sauvegardée
agenteye --org globex sessions      # substitution pour une seule commande

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 n’en choisissez pas, la CLI les liste et vous demande de relancer avec --org <slug>. L’organisation active est transmise au tableau de bord à chaque requête, et vos permissions sont résolues par organisation — agenteye whoami affiche l’organisation active, vos permissions dans celle-ci, ainsi que toutes vos appartenances.

Configuration

Paramètre	Indicateur	Variable d’environnement	Valeur par défaut
URL de base du tableau de bord	`--base-url`	`AGENTEYE_DASHBOARD_URL`	requis (aucune valeur par défaut)
Organisation/tenant actif	`--org`	`AGENTEYE_ORG`	choisi à la connexion ; sauvegardé dans `~/.agenteye/cli.json`
Jeton de session	`--token`	`AGENTEYE_CLI_TOKEN`	depuis `~/.agenteye/cli.json`
Sortie JSON	`--json`	`AGENTEYE_CLI_JSON`	désactivé
Ignorer la vérification TLS	`--insecure` / `--secure`	`AGENTEYE_INSECURE`	désactivé (sauvegardé à la connexion)
Délai d’attente des requêtes (secondes)	`--timeout`	—	30
Désactiver la télémétrie d’utilisation	(aucun)	`AGENTEYE_ANALYTICS_DISABLED` (ou `DO_NOT_TRACK`)	désactivé (télémétrie activée)

L’ordre de résolution est indicateur → 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 première login) :

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com

Le répertoire de configuration respecte AGENTEYE_HOME (la même convention utilisée par le SDK et le collecteur) ; s’il est défini, cli.json se trouve dans $AGENTEYE_HOME/cli.json.

TLS auto-signé ou interne

Si votre tableau de bord est servi en HTTPS avec un certificat auto-signé ou interne (par exemple, un nom d’hôte de répartiteur de charge brut), la vérification TLS le rejette avec une erreur CERTIFICATE_VERIFY_FAILED. Passez --insecure pour ignorer la vérification du certificat :

agenteye --base-url https://agenteye.internal --insecure login

--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 l’indicateur. Passez --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. L’ignorance de 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é

La CLI envoie des analyses d’utilisation anonymes au service d’analyse d’Exosphere (PostHog) : quelles commandes sont exécutées (p. ex. sessions, keys create), si elles ont réussi, et combien de temps elles ont pris. Ce signal d’utilisation informe les décisions sur les fonctionnalités à prioriser.

Aucune donnée d’agent, de session ou d’événement ne quitte jamais votre infrastructure. Seule l’utilisation de la CLI est rapportée : le nom de la commande et de la sous-commande (p. ex. keys create), les noms des indicateurs utilisés (jamais leurs valeurs), le statut de succès/sortie, et la durée — plus un événement par action pour les mutations (p. ex. api_key_created, query_run) ne portant que des noms/énumérations statiques et des comptages grossiers. Votre URL de tableau de bord, jeton de session, e-mail, slug d’organisation, identifiants de ressources, SQL, secrets de clés et filtres de requêtes ne sont jamais envoyés. Les opérateurs sont identifiés uniquement par un identifiant interne opaque, jamais par e-mail.
La télémétrie est activée par défaut. Pour la désactiver, définissez AGENTEYE_ANALYTICS_DISABLED=1 dans l’environnement de la CLI (la CLI respecte également la convention cross-outil DO_NOT_TRACK=1).
La CLI envoie directement à PostHog (https://us.i.posthog.com). La machine exécutant la CLI doit avoir un accès sortant vers cet hôte ; si elle est bloquée, la télémétrie ne fait rien silencieusement (l’envoi est limité dans le temps pour ne jamais retarder ni interrompre une commande) et la CLI n’est pas affectée.

Options globales et conventions

Lisez ceci une fois ; cela s’applique à toutes les commandes.

Les options globales se placent 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 humaines, les avertissements et les erreurs vont sur stderr, de sorte qu’une capture stdout --json reste propre pour être transmise à jq même quand une ligne de statut est affichée. Sans --json, vous obtenez une vue encadrée et colorisée pour les yeux humains.
Découverte 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’y a pas de surface machine-readable 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 une confirmation dans un terminal interactif, mais ignorent automatiquement cette invite sous --json ou quand stdin n’est pas un TTY — les scripts et les agents ne restent donc jamais bloqués. Passez --yes/-y pour l’ignorer explicitement. Comme l’invite ne se déclenche pas pour un agent, celui-ci doit confirmer les actions destructives avec l’humain au préalable.
Pagination : les résultats sont les plus récents en premier et paginés par curseur. --limit N (alias -n) limite les lignes et vaut 50 par défaut ; --all pagine automatiquement (par blocs de 200 lignes) jusqu’à --limit — ainsi 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 le bloc par requête (max 200) ; --cursor <id> reprend depuis le next_cursor d’une page précédente.
Filtres de temps : --since prend une fenêtre relative — 15m, 1h, 6h, 24h, 7d, 30d, ou all (les préréglages du tableau de bord). --from/--to prennent des horodatages UTC ISO-8601 explicites avec T et un fuseau horaire (p. ex. 2026-06-01T00:00:00Z) pour une plage personnalisée et remplacent --since ; une valeur séparée par un espace 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 valide — un moyen simple de découvrir les noms de champs.
--file payload.json (ou --file - pour lire stdin) fournit un corps de requête JSON complet quand une ressource a une forme complexe — sur alerts create/update, settings set, et users create/update. Le SQL de requête sauvegardée utilise plutôt --sql @file.sql.
Les filtres multi-valeurs sont séparés par des virgules → correspondance en tant qu’ensemble (union au sein d’un filtre, ET entre les filtres) : --event-type tool_use,tool_result. Les options Click ne sont pas variadiques, donc --add a b échoue — utilisez --add a,b, répétez l’indicateur (--add a --add b), ou utilisez des guillemets (--add "a b").

Référence des commandes

La CLI dispose de 18 commandes de niveau supérieur. 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 indicateurs et la forme JSON de chaque commande.

agenteye login --email you@example.com [--org acme]   # code à usage unique par e-mail ; sauvegarde la session
agenteye logout                                       # efface la session sauvegardée sur cette machine
agenteye whoami                                       # utilisateur actuel, organisation active, permissions
agenteye version                                      # affiche la version de la CLI (identique à --version)
agenteye help                                         # aide de niveau supérieur (identique à --help)

orgs inspecte et change le tenant actif :

agenteye orgs list        # vos organisations + votre rôle dans chacune (l'active est signalée)
agenteye orgs switch acme # changer l'organisation active sauvegardée (omettez le slug pour choisir depuis une liste sur un TTY)
agenteye orgs current     # carte d'identité de l'organisation active
agenteye orgs perms       # vos permissions dans l'organisation active, groupées par ressource

Observation (lecture seule) — `events` · `sessions` · `evals` · `errors` · `list`

Aucune de ces commandes ne nécessite de confirmation. Filtres partagés : --session-id, --agent-id, --env (pas --environment), et la plage de temps (--since / --from / --to).

# events (alias : la piste brute par étape) — les plus récents en premier
agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all --limit 1000
agenteye --json events --since 1h --search timeout --all | jq '.events[].payload'

# sessions — une ligne par exécution d'agent (temps/env/agent/session/statut ; pas de filtrage par score)
agenteye --json sessions --since 24h --status error
agenteye --json sessions --agent-id checkout-bot --env prod --all --limit 1000

# evals — résultats d'évaluation + scores ; --score filtre par métrique, --aggregate regroupe
agenteye --json evals --score helpfulness:0.5..0.8 --score tool_efficiency:..0.3
agenteye --json evals --aggregate --since 7d --env prod        # répartition des statuts + stats de score par clé

# errors — événements en erreur ; --aggregate pour les comptages/sessions/agents/dernière occurrence
agenteye --json errors --since 24h --aggregate
agenteye --json errors --since 24h --error-type timeout --all --limit 1000

# list — découvrir les valeurs de filtre valides avant de filtrer
agenteye list envs        # aussi : agents event_types score_filters models hooks triggers tools error_types

--score KEY:MIN..MAX (sur evals, pas sessions) est répétable et combiné en 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 retourne l’objet score complet plutôt que le résumé. Pour lire une session de bout en bout, combinez la piste d’événements avec son évaluation :

agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'
agenteye --json evals  --session-id run-001                       # ses scores + statut

Gestion (soumise aux permissions) — `keys` · `users` · `settings` · `alerts` · `incidents`

keys — Clés API. Le secret est généré localement, envoyé au serveur (qui ne stocke qu’un hachage), et affiché une seule fois lors de la création/régénération — capturez-le immédiatement. Avec --json, il n’apparaît que dans le champ key. Référencées par nom.

agenteye keys list                                   # clés actives d'abord, puis révoquées
agenteye keys show ci-bot
agenteye keys create ci-bot --add events:read.add    # limitez aux scopes nécessaires ; affiche le secret UNE SEULE FOIS
agenteye keys create ops --permission-set standard --remove queries:run   # initialisez un préréglage, puis affinez
agenteye keys update ci-bot --add evaluations:read --yes
agenteye keys regenerate ci-bot --yes                # faire tourner le secret (l'ancien cesse de fonctionner)
agenteye keys disable ci-bot --yes                   # révoquer

Les permissions fonctionnent comme (permission-set ∪ --add) − --remove. Les jetons sont slug:action (p. ex. events:read) ou slug:action.action pour en développer plusieurs sur une ressource (events:read.add → events:read, events:add). Préréglages : 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 identifiant UUID est également accepté).

agenteye users list [--active-only]
agenteye users show dev@corp.com
agenteye users create dev@corp.com --permission-set standard
agenteye users update dev@corp.com --add alerts:write --remove queries:delete   # prédit + confirme
agenteye users disable dev@corp.com --yes            # protections de rôle/auto-protection activées
agenteye users enable dev@corp.com

settings — un registre fixe (vous lisez et modifiez les clés existantes ; vous ne pouvez pas en créer de nouvelles).

agenteye settings list                               # clé · valeur · type · mise à jour (secrets masqués)
agenteye settings schema                             # ce que chaque clé accepte (type · plage · description)
agenteye settings set session_ttl_secs --value 86400 --yes

alerts — définitions d’alertes, référencées par nom. create prend un NOM positionnel plus des indicateurs ou un corps JSON complet via --file.

agenteye alerts list
agenteye alerts show high-errors
agenteye alerts create high-errors --file alert.json          # NOM requis (positionnel)
agenteye alerts update high-errors --severity critical --yes
agenteye alerts test high-errors --yes                        # déclencher une notification de test
agenteye alerts delete high-errors --yes

incidents — incidents d’alerte, référencés par identifiant (les identifiants courts sont acceptés). show affiche le journal d’activité complet — lisez-le avant d’agir.

agenteye incidents list --state firing                # aussi : acknowledged, resolved
agenteye incidents count
agenteye incidents show <id>
agenteye incidents ack <id>
agenteye incidents assign <id> you@corp.com           # le responsable doit être un opérateur
agenteye incidents resolve <id> --yes
agenteye incidents open --alert-id <id> --severity critical    # ouvrir manuellement contre une alerte
agenteye incidents comment-add <id> "root cause: upstream 5xx"
agenteye incidents comment-list <id> ; agenteye incidents comment-delete <id> <comment-id>
agenteye incidents subscribe <id> ; agenteye incidents unsubscribe <id> ; agenteye incidents subscribers <id>

Analytique et assistant — `query` · `agent`

query — SQL ClickHouse sauvegardé 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, limite de lignes).

agenteye query schema [TABLE]                         # structure des colonnes des vues analytiques
agenteye query run --sql "select count(*) from analytics.events"
agenteye query run errs --arg prod --limit 100        # exécuter une requête sauvegardée + un $1 positionnel
agenteye query list ; agenteye query show errs
agenteye query create errs --sql @errs.sql --description "errored events (24h)"
agenteye query update errs --sql @errs.sql --yes ; agenteye query delete errs --yes

agent — l’assistant intégré du tableau de bord (le même analyste en lecture seule avec lequel vous pouvez discuter dans le tableau de bord). Les conversations sont référencées par un identifiant court (résolution par préfixe).

agenteye agent health                                 # l'assistant est-il configuré/accessible
agenteye agent models                                 # modèles que vous pouvez passer à --model (le défaut est indiqué)
agenteye agent ask "which agents errored most in the last day?"    # démarre une conversation ; affiche son identifiant court
agenteye agent ask --chat <short-id> "and which tools did they call?"   # continuer cette conversation
agenteye agent chats ; agenteye agent show <short-id>
agenteye agent rename <short-id> --title "error triage" ; agenteye agent delete <short-id>

Codes de sortie

Code	Signification
0	Succès
1	Erreur inattendue (p. ex. le tableau de bord a retourné un 5xx)
2	Erreur d’utilisation (arguments invalides, commande/indicateur inconnu, collision de noms)
3	Impossible d’atteindre le tableau de bord
4	Non connecté ou session expirée ; exécutez `agenteye login`
5	Authentifié, mais votre compte n’a pas la permission requise (le message la nomme)
6	La ressource demandée est introuvable (p. ex. identifiant de session ou d’incident inconnu)

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

Voir aussi

Recettes CLI pour agents — motifs de requêtes prêts à l’emploi, commandes jq en une ligne, projections --fields, gestion des codes de sortie et formes de sortie JSON, écrits pour les agents de codage pilotant la CLI.
Compétence CLI AgentEye — packager cette CLI comme une compétence installable Claude Code / Codex pour qu’un agent de codage pilote AgentEye depuis des 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.

​Installation

​Authentification

​Choisir son organisation (multi-tenant)

​Configuration

​TLS auto-signé ou interne

​Télémétrie et confidentialité

​Options globales et conventions

​Référence des commandes

​Identité — login · logout · whoami · orgs · version · help

​Observation (lecture seule) — events · sessions · evals · errors · list

​Gestion (soumise aux permissions) — keys · users · settings · alerts · incidents

​Analytique et assistant — query · agent

​Codes de sortie

​Voir aussi