> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Recettes CLI pour agents

> Documentation des recettes CLI AgentEye pour agents.

Récupérez les données de sessions, d'événements et d'évaluations (et déclenchez des réévaluations) directement depuis un script ou un agent de code, avec du JSON propre sur stdout qui s'enchaîne directement avec `jq`. Ces recettes transforment les données d'observabilité d'AgentEye en quelque chose qu'un utilisateur de terminal ou un agent de code IA (Claude Code, Cursor) peut interroger et automatiser, sans passer par le tableau de bord.

Les patterns ci-dessous sont prêts à copier-coller pour le CLI AgentEye (`agenteye`). Pour l'installation, l'authentification et la liste complète des options, consultez [CLI](/fr/agenteye/cli) ; lancez `agenteye -h` ou `agenteye <command> -h` pour l'aide intégrée.

## Règles d'or

1. **Les options globales se placent *avant* la commande.** `agenteye --json sessions` est correct ; `agenteye sessions --json` ne l'est pas. Les options globales sont `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`.
2. **Passez `--json` dès que vous analysez la sortie.** Les données vont sur **stdout** en JSON ; les statuts humains et les erreurs vont sur **stderr**, ce qui permet à stdout de rester propre pour être redirigé vers `jq`.
3. **Branchez-vous sur le code de sortie**, pas sur le texte de stderr : `0` ok · `2` arguments invalides · `3` impossible de joindre le tableau de bord · `4` non connecté ou session expirée · `5` permission manquante.
4. **Explorez avec `-h`.** Chaque commande documente ses filtres, formats de valeurs et structure JSON.

## Configuration initiale

```bash theme={null}
export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # pour ne pas répéter --base-url
agenteye login --email you@example.com                       # collez le code reçu par e-mail ; valable ~24h
```

## Vérifier l'authentification avant d'agir

`whoami` ne retourne jamais d'erreur pour une session manquante ou expirée ; il rapporte `logged_in:false` à la place, ce qui permet à un agent de tester l'état d'authentification en toute sécurité. (Il peut quand même sortir avec un code non nul si aucune URL de base n'est définie ou si le tableau de bord est inaccessible.)

```bash theme={null}
if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then
  echo "Non authentifié. Lancez : agenteye login" >&2; exit 1
fi
```

## Trouver les sessions en échec ou mal notées

```bash theme={null}
# sessions des dernières 24h dont l'évaluation est en erreur
agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'

# évaluations avec un score helpfulness <= 0.5, pour un agent donné
agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
  | jq '.evaluations[] | {session_id, scores}'
```

Le filtrage par score s'applique à **`evals`**, pas à `sessions`. `--score KEY:MIN..MAX` est répétable et combiné en AND ; chaque borne est optionnelle (`..0.5` signifie ≤ 0.5, `0.9..` signifie ≥ 0.9). Vous pouvez passer jusqu'à 20 filtres de score par requête ; au-delà, la réponse est HTTP 400. `sessions` partage les filtres `--env`, `--status`, `--agent-id`, `--session-id` et de plage temporelle avec `evals`, mais n'a pas de `--score`.

## Lire une session de bout en bout

Il n'existe pas de commande unique `session show` — combinez le journal d'événements avec l'évaluation de la session :

```bash theme={null}
# dernière évaluation de la session (statut + scores)
agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'

# tous les événements de l'exécution (augmentez --limit pour un parcours complet)
agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'

# uniquement les appels d'outils dans une session
agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'
```

## Tout récupérer (pagination)

Les résultats sont triés du plus récent au plus ancien et paginés par curseur.

```bash theme={null}
# en une seule fois : récupère jusqu'à 500 lignes en pages de 200
agenteye --json events --session-id run-001 --limit 500 --all > events.json

# pagination manuelle : réinjecter next_cursor
page=$(agenteye --json events --limit 100)
cursor=$(echo "$page" | jq -r '.next_cursor // empty')
[ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor"
```

## Réduire la sortie avec --fields

Restreignez les clés (dans le tableau et avec `--json`) pour limiter ce qu'un agent doit lire.

```bash theme={null}
agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]'
agenteye --json events --session-id run-001 --fields ts,event_type --all
```

Les noms de champs inconnus sont rejetés (sortie `2`) avec la liste valide, un moyen pratique de découvrir les noms de champs.

## Découvrir les valeurs de filtre valides

```bash theme={null}
agenteye --json list envs | jq -r '.values[]'           # valeurs pour --env
agenteye --json list tools | jq -r '.values[]'          # noms d'outils ; aussi agents, models, event_types, …
agenteye --json list score_filters | jq -r '.values[]'  # KEY valide pour --score KEY:MIN..MAX
```

## Choisir son organisation (multi-tenant)

Si vous appartenez à plusieurs organisations, choisissez le tenant actif à la connexion (il est sauvegardé) :

```bash theme={null}
agenteye login --org acme --email you@corp.com   # définir le tenant en même temps que la connexion
agenteye --json orgs list | jq -r '.orgs[].org_slug'
agenteye --org globex --json sessions --since 24h   # remplacement pour une seule commande
```

Une connexion multi-org sans `--org` sort avec un code non nul et affiche les organisations parmi lesquelles choisir.

## Créer une clé API pour le SDK/collecteur

```bash theme={null}
# le secret est affiché UNE SEULE FOIS — avec --json, c'est le champ .key
key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
agenteye keys regenerate ci-bot --yes    # rotation ; agenteye keys disable ci-bot --yes pour révoquer
```

## Exécuter une requête sauvegardée ou ad hoc

```bash theme={null}
agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
agenteye --json query run errs --arg prod | jq '.rows'   # une requête sauvegardée + un $1 positionnel
```

## Gérer un incident sans interaction

```bash theme={null}
id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id')
agenteye incidents ack "$id"
agenteye incidents assign "$id" --assignee you@corp.com
agenteye incidents resolve "$id" --yes
```

> Les mutations ignorent automatiquement leur invite de confirmation sous `--json` ou lorsque stdin n'est pas un TTY, de sorte que les agents ne restent jamais bloqués ; passez `--yes`/`-y` pour l'ignorer explicitement ailleurs.

## Gestion des codes de sortie dans un script

```bash theme={null}
out=$(agenteye --json sessions --since 1h) || code=$?
case "${code:-0}" in
  0) echo "$out" | jq '.sessions | length' ;;
  4) echo "Session expirée - lancez 'agenteye login'." >&2 ;;
  5) echo "Permission manquante (demandez à un admin evaluations:read)." >&2 ;;
  3) echo "Tableau de bord inaccessible - vérifiez l'URL." >&2 ;;
  *) echo "Erreur inattendue (sortie ${code})." >&2 ;;
esac
```

## Structures de sortie JSON

| Commande                         | JSON sur stdout (avec `--json`)                                                                                                               |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `whoami`                         | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` ou `{"logged_in": false}` |
| `orgs list`                      | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}`                                                            |
| `events`                         | `{"events": [...], "next_cursor": <cursor or null>}`                                                                                          |
| `evals`                          | `{"evaluations": [...], "next_cursor": <cursor or null>}`                                                                                     |
| `sessions`                       | `{"sessions": [...], "next_cursor": <cursor or null>}`                                                                                        |
| `errors`                         | `{"errors": [...], "next_cursor": <cursor or null>}`                                                                                          |
| `list <kind>`                    | `{"kind", "values": [...]}`                                                                                                                   |
| `keys list` / `keys create`      | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key` affiché une seule fois)                                                 |
| `query run`                      | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}`                                                                              |
| `users list` / `settings list`   | `{"users": [...]}` / `{"settings": [...]}`                                                                                                    |
| `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}`                                                                                                  |
| create/update/delete (tous)      | l'objet ressource, ou `{"deleted": true, "id"}` pour les suppressions                                                                         |
| échec (tous, avec `--json`)      | `{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` sur stdout                                                            |

* Chaque élément **event** (`events`) : `id, session_id, agent_id, event_type, ts, payload, environment`.
* Chaque élément **evaluation** (`evals`) : `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`.
* Chaque élément **session** (`sessions`) : `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`.

Le `--fields` de chaque commande accepte uniquement les noms de champs de ses propres éléments — l'ensemble diffère entre `sessions` et `evals`, donc un nom valide pour l'un peut être rejeté par l'autre.