> ## 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.

# CLI-Rezepte für Agenten

> AgentEye CLI-Rezepte für die Agenten-Dokumentation.

Sitzungs-, Ereignis- und Evaluierungsdaten direkt aus einem Skript oder Coding-Agenten abrufen (und Neubewertungen auslösen) – mit sauberem JSON auf stdout, das sich direkt in `jq` pipen lässt. Diese Rezepte machen AgentEyes Observability-Daten für Terminal-Nutzer oder KI-Coding-Agenten (Claude Code, Cursor) abfragbar und automatisierbar, ohne durch das Dashboard zu klicken.

Die folgenden Muster sind kopierbereit für die AgentEye CLI (`agenteye`). Informationen zur Installation, Authentifizierung und der vollständigen Optionsliste findest du unter [CLI](/de/agenteye/cli); führe `agenteye -h` oder `agenteye <command> -h` für die eingebaute Hilfe aus.

## Grundregeln

1. **Globale Optionen kommen *vor* dem Befehl.** `agenteye --json sessions` ist korrekt; `agenteye sessions --json` ist es nicht. Die globalen Optionen sind `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`.
2. **`--json` übergeben, wenn du die Ausgabe parst.** Daten gehen als JSON an **stdout**; menschenlesbare Status- und Fehlermeldungen gehen an **stderr**, sodass stdout sauber in `jq` gepipet werden kann.
3. **Verzweige anhand des Exit-Codes**, nicht anhand des stderr-Texts: `0` ok · `2` ungültige Argumente · `3` Dashboard nicht erreichbar · `4` nicht eingeloggt oder abgelaufen · `5` fehlende Berechtigung.
4. **Mit `-h` erkunden.** Jeder Befehl dokumentiert seine Filter, Wertformate und die JSON-Struktur.

## Einmalige Einrichtung

```bash theme={null}
export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # damit du --base-url nicht wiederholen musst
agenteye login --email you@example.com                       # per E-Mail gesendeten Code einfügen; gültig ~24h
```

## Auth prüfen, bevor Arbeit erledigt wird

`whoami` gibt bei einer fehlenden oder abgelaufenen Sitzung keinen Fehler aus; stattdessen meldet es `logged_in:false`, sodass ein Agent den Auth-Status sicher abfragen kann. (Es kann trotzdem mit einem Exit-Code ungleich null enden, wenn keine Basis-URL gesetzt oder das Dashboard nicht erreichbar ist.)

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

## Fehlgeschlagene oder niedrig bewertete Sitzungen finden

```bash theme={null}
# Sitzungen der letzten 24h, deren Evaluierung fehlgeschlagen ist
agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'

# Evaluierungen mit <= 0.5 bei Hilfsbereitschaft, für einen Agenten
agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
  | jq '.evaluations[] | {session_id, scores}'
```

Score-Filterung liegt bei **`evals`**, nicht bei `sessions`. `--score KEY:MIN..MAX` ist wiederholbar und wird mit UND verknüpft; beide Grenzen sind optional (`..0.5` bedeutet ≤ 0,5; `0.9..` bedeutet ≥ 0,9). Pro Anfrage können bis zu 20 Score-Filter übergeben werden; mehr ergibt HTTP 400. `sessions` teilt die Filter `--env`, `--status`, `--agent-id`, `--session-id` und Zeitbereich mit `evals`, hat aber kein `--score`.

## Eine Sitzung von Anfang bis Ende lesen

Es gibt keinen einzelnen Befehl `session show` – kombiniere den Ereignisverlauf mit der Evaluierung der Sitzung:

```bash theme={null}
# die neueste Evaluierung der Sitzung (Status + Scores)
agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'

# alle Ereignisse im Durchlauf (--limit für einen vollständigen Sweep erhöhen)
agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'

# nur die Tool-Aufrufe in einer Sitzung
agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'
```

## Alles abrufen (Paginierung)

Ergebnisse sind neueste zuerst und cursor-paginiert.

```bash theme={null}
# Einmalig: bis zu 500 Zeilen in 200-Zeilen-Seiten abrufen
agenteye --json events --session-id run-001 --limit 500 --all > events.json

# Manuelles Blättern: next_cursor zurückführen
page=$(agenteye --json events --limit 100)
cursor=$(echo "$page" | jq -r '.next_cursor // empty')
[ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor"
```

## Ausgabe mit --fields einschränken

Schlüssel (sowohl in der Tabelle als auch bei `--json`) einschränken, um zu reduzieren, was ein Agent lesen muss.

```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
```

Unbekannte Feldnamen werden abgelehnt (Exit `2`) und die gültige Liste wird ausgegeben – eine einfache Methode, um Feldnamen zu erkunden.

## Gültige Filterwerte entdecken

```bash theme={null}
agenteye --json list envs | jq -r '.values[]'           # Werte für --env
agenteye --json list tools | jq -r '.values[]'          # Tool-Namen; auch agents, models, event_types, …
agenteye --json list score_filters | jq -r '.values[]'  # gültiger KEY für --score KEY:MIN..MAX
```

## Organisation auswählen (Multi-Tenant)

Wenn du mehr als einer Organisation angehörst, wähle den aktiven Mandanten beim Login (er wird gespeichert):

```bash theme={null}
agenteye login --org acme --email you@corp.com   # Mandant im selben Schritt wie Login setzen
agenteye --json orgs list | jq -r '.orgs[].org_slug'
agenteye --org globex --json sessions --since 24h   # für einen Befehl überschreiben
```

Ein Multi-Org-Login ohne `--org` endet mit einem Exit-Code ungleich null und gibt die zur Auswahl stehenden Organisationen aus.

## API-Schlüssel für das SDK/den Collector bereitstellen

```bash theme={null}
# Das Secret wird EINMALIG ausgegeben — mit --json ist es das .key-Feld
key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
agenteye keys regenerate ci-bot --yes    # rotieren; agenteye keys disable ci-bot --yes zum Widerrufen
```

## Eine gespeicherte oder Ad-hoc-Abfrage ausführen

```bash theme={null}
agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
agenteye --json query run errs --arg prod | jq '.rows'   # eine gespeicherte Abfrage + ein positionaler $1
```

## Einen Vorfall nicht-interaktiv triagieren

```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
```

> Mutationen überspringen ihre Bestätigungsabfrage automatisch bei `--json` oder wenn stdin kein TTY ist, sodass Agenten nie hängen bleiben; übergib `--yes`/`-y`, um sie anderswo explizit zu überspringen.

## Exit-Code-Behandlung in einem Skript

```bash theme={null}
out=$(agenteye --json sessions --since 1h) || code=$?
case "${code:-0}" in
  0) echo "$out" | jq '.sessions | length' ;;
  4) echo "Session expired - run 'agenteye login'." >&2 ;;
  5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;;
  3) echo "Dashboard unreachable - check the URL." >&2 ;;
  *) echo "Unexpected error (exit ${code})." >&2 ;;
esac
```

## JSON-Ausgabestrukturen

| Befehl                           | stdout JSON (mit `--json`)                                                                                                                      |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `whoami`                         | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` oder `{"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` wird einmalig angezeigt)                                                  |
| `query run`                      | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}`                                                                                |
| `users list` / `settings list`   | `{"users": [...]}` / `{"settings": [...]}`                                                                                                      |
| `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}`                                                                                                    |
| create/update/delete (beliebig)  | das Ressourcenobjekt oder `{"deleted": true, "id"}` bei Löschvorgängen                                                                          |
| Fehler (beliebig, mit `--json`)  | `{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` auf stdout                                                              |

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

Das `--fields`-Argument jedes Befehls akzeptiert genau die Feldnamen des jeweiligen Elements – der Satz unterscheidet sich zwischen `sessions` und `evals`, sodass ein für eines gültiger Name vom anderen abgelehnt werden kann.