Die CLI verwenden

Diese Seite behandelt die Ein- und Ausgabemechanismen der ant-CLI, die für jeden Endpunkt gelten. Informationen zur Installation und Authentifizierung findest du im Schnellstart. Wie du Befehle verkettest und Ressourcen versionierst, erfährst du unter CLI-Skripting und -Automatisierung.

Befehlsstruktur

Befehle folgen dem Muster resource action. Verschachtelte Ressourcen verwenden Doppelpunkte:

ant <resource>[:<subresource>] <action> [flags]

Führe ant --help aus, um die vollständige Ressourcenliste zu erhalten, oder hänge --help an einen beliebigen Unterbefehl an, um dessen Flags anzuzeigen.

Ressourcen in der Beta (darunter Agents, Sessions, Deployments und Environments) befinden sich unter dem Präfix beta:. Befehle in diesem Namespace senden automatisch den passenden anthropic-beta-Header für die jeweilige Ressource, sodass du ihn nicht selbst übergeben musst. Verwende --beta <header> nur, um den Standard zu überschreiben (zum Beispiel, um eine andere Schemaversion zu aktivieren).

ant models list
ant messages create --model claude-opus-5-5 --max-tokens 1024 ...
ant beta:agents retrieve --agent-id agent_01...
ant beta:sessions:events list --session-id session_01...

Globale Flags

Ausgabeformate

auto gibt JSON formatiert aus und ist der Standard für Befehle, die Ressourcen erstellen oder ändern. List- und Retrieve-Befehle verwenden standardmäßig den interaktiven Explorer, wenn sie in ein Terminal schreiben, und formatiertes JSON, wenn die Ausgabe per Pipe weitergeleitet wird. Überschreibe beide Standards mit --format:

ant models retrieve --model-id claude-opus-5-5 --format yaml

type: model
id: claude-opus-5-5
display_name: Claude Opus 5.5
created_at: "2026-09-22T00:00:00Z"
...

List-Endpunkte paginieren automatisch. In den Standardformaten wird jedes Element separat geschrieben (ein kompaktes JSON-Objekt pro Zeile im jsonl-Modus, ein Stream von YAML-Dokumenten im yaml-Modus), was sich sauber in head, grep und --transform-Filter streamen lässt.

Interaktiver Explorer

Der Explorer ist eine TUI mit Ein-/Ausklappen und Suche zum Durchsuchen großer Antworten. Mit den Pfeiltasten klappst du Knoten auf und zu, / startet die Suche, q beendet ihn. List- und Retrieve-Befehle öffnen ihn standardmäßig, wenn sie mit einem Terminal verbunden sind. Übergib --format explore, um ihn explizit zu öffnen:

ant models list --format explore

Ausgabe mit GJSON transformieren

Verwende --transform, um Antworten vor der Ausgabe umzuformen. Der Ausdruck ist ein GJSON-Pfad. Bei List-Endpunkten wird die Transformation auf jedes Element einzeln angewendet, nicht auf den Umschlag:

ant beta:agents list \
  --transform "{id,name,model}" \
  --format jsonl

{"id": "agent_011CYm1BLqPX...", "name": "Docs CLI Test Agent", "model": "claude-opus-5-5"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-opus-5-5"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-5-5"}

Einen Skalar extrahieren

Um ein einzelnes Feld als String ohne Anführungszeichen zu erfassen (zum Beispiel die ID einer neu erstellten Ressource), kombiniere --transform mit --raw-output. Das Ergebnis wird ohne JSON-Anführungszeichen ausgegeben und kann direkt einer Shell-Variablen zugewiesen werden:

AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-opus-5-5}' \
  --transform id --raw-output)

Request-Bodys übergeben

Der richtige Eingabemechanismus hängt von der Form der Daten ab: Verwende Flags für skalare Felder und kurze strukturierte Werte, leite ein stdin-Dokument für verschachtelte oder mehrzeilige Bodys per Pipe weiter und verwende @file-Referenzen, um Dateiinhalte in ein beliebiges String- oder Binärfeld zu laden.

Flags

Skalare Felder werden direkt auf Flags abgebildet. Strukturierte Felder akzeptieren eine gelockerte, YAML-ähnliche Syntax (Schlüssel ohne Anführungszeichen, optionale Anführungszeichen um Strings) oder striktes JSON:

ant beta:sessions create \
  --agent '{type: agent, id: agent_011CYm1BLqPXpQRk5khsSXrs, version: 1}' \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "CLI docs test session"

Wiederholbare Flags erzeugen Arrays. Jedes --tool oder --event hängt ein Element an:

ant beta:agents create \
  --name "Research Agent" \
  --model '{id: claude-opus-5-5}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'

Stdin

Leite ein JSON- oder YAML-Dokument per Pipe an stdin weiter, um den vollständigen Request-Body bereitzustellen. Felder aus stdin werden mit Flags zusammengeführt, wobei Flags Vorrang haben. Hier ist version das Token für optimistisches Locking, das von einem früheren retrieve zurückgegeben wurde, und $AGENT_ID wurde wie unter Einen Skalar extrahieren erfasst:

echo '{"description": "Updated test agent.", "version": 1}' | \
  ant beta:agents update --agent-id "$AGENT_ID"

Heredocs funktionieren auf die gleiche Weise und sind praktisch für mehrzeiliges YAML. Setze das Trennzeichen in Anführungszeichen (wie in <<'YAML'), um die Variablenexpansion innerhalb des Bodys zu deaktivieren.

ant beta:agents create <<'YAML'
name: Research Agent
model: claude-opus-5-5
system: |
  You are a research assistant. Cite sources for every claim.
tools:
  - type: agent_toolset_20260401
YAML

Dateireferenzen

Flags, die einen Dateipfad erwarten, wie --file beim Upload-Befehl, akzeptieren einen einfachen Pfad:

ant files upload --file ./report.pdf

Um den Inhalt einer Datei in ein Feld mit String-Wert einzufügen, stelle dem Pfad ein @ voran:

ant beta:agents create \
  --name "Researcher" --model '{id: claude-opus-5-5}' \
  --system @./prompts/researcher.txt

Setze den Pfad innerhalb strukturierter Flag-Werte in Anführungszeichen. So sendest du ein PDF an die Messages API:

ant messages create \
  --model claude-opus-5-5 \
  --max-tokens 1024 \
  --message '{role: user, content: [
    {type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}},
    {type: text, text: "Extract the text from this scanned document."}
  ]}'

Die CLI erkennt den Dateityp und kodiert Binärdateien automatisch als base64. Um eine bestimmte Kodierung zu erzwingen, verwende @file:// für Klartext oder @data:// für base64. Maskiere ein wörtliches führendes @ mit einem Backslash (\@username).

Debugging

Füge --debug zu einem beliebigen Befehl hinzu, um den exakten HTTP-Request und die Response (Header und Body) auf stderr auszugeben. API-Keys werden geschwärzt.

ant --debug beta:agents list

GET /v1/agents?beta=true HTTP/1.1
Host: api.anthropic.com
Anthropic-Beta: managed-agents-2026-04-01
Anthropic-Version: 2026-10-21
Authorization: Bearer <REDACTED>
...

Verfügbare Ressourcen

Jede API-Ressource, die die CLI bereitstellt, ist in der API-Referenz dokumentiert. Für eine lokale Auflistung führe ant --help aus und hänge --help an einen beliebigen Unterbefehl an, um dessen Flags und Parameter anzuzeigen.

Nächste Schritte