Verwendung der CLI

Diese Seite behandelt die Eingabe- und Ausgabemechanismen der ant CLI, die für alle Endpunkte gelten. Informationen zur Installation und Authentifizierung findest du im Quickstart. Informationen zum Verketten von Befehlen und zur Versionskontrolle von Ressourcen findest du unter CLI-Scripting und Automatisierung.

Befehlsstruktur

Befehle folgen einem resource action-Muster. 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-Phase (einschließlich Agents, Sessions, Deployments, Environments und Skills) befinden sich unter dem Präfix beta:. Befehle in diesem Namespace senden automatisch den entsprechenden anthropic-beta-Header für diese Ressource, sodass du ihn nicht selbst übergeben musst. Verwende --beta <header> nur, um den Standard zu überschreiben (zum Beispiel, um eine andere Schema-Version zu aktivieren).

ant models list
ant messages create --model claude-opus-4-8 --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 sie gepipet werden. Überschreibe beide Standards mit --format:

ant models retrieve --model-id claude-opus-4-8 --format yaml

type: model
id: claude-opus-4-8
display_name: Claude Opus 4.8
created_at: "2026-02-04T00: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 zum Ein- und Ausklappen sowie Durchsuchen großer Antworten. Pfeiltasten klappen Knoten auf und zu, / sucht, q beendet. 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 Envelope:

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

{"id": "agent_011CYm1BLqPX...", "name": "Docs CLI Test Agent", "model": "claude-sonnet-4-6"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-sonnet-4-6"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-4-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-Variable zugewiesen werden:

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

printf '%s\n' "$AGENT_ID"

agent_011CYm1BLqPXpQRk5khsSXrs

Request-Bodies übergeben

Der richtige Eingabemechanismus hängt von der Form der Daten ab: Verwende Flags für skalare Felder und kurze strukturierte Werte, pipe ein stdin-Dokument für verschachtelte oder mehrzeilige Bodies und verwende @file-Referenzen, um Dateiinhalte in ein beliebiges String- oder Binärfeld einzufügen.

Flags

Skalare Felder werden direkt auf Flags abgebildet. Strukturierte Felder akzeptieren eine entspannte YAML-ähnliche Syntax (Keys 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 bauen Arrays auf. Jedes --tool oder --event fügt ein Element hinzu:

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

Stdin

Pipe ein JSON- oder YAML-Dokument nach stdin, um den vollständigen Request-Body bereitzustellen. Felder aus stdin werden mit Flags zusammengeführt, wobei Flags Vorrang haben. Hier ist version das Optimistic-Locking-Token, das von einem früheren retrieve zurückgegeben wurde, und $AGENT_ID wurde wie in 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 den Delimiter 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-4-8
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 beta:files upload --file ./report.pdf

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

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

Innerhalb strukturierter Flag-Werte setze den Pfad in Anführungszeichen. Um ein PDF an die Messages API zu senden:

ant messages create \
  --model claude-opus-4-8 \
  --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."}
  ]}' \
  --transform 'content.0.text' --raw-output

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. Escape ein literales führendes @ mit einem Backslash (\@username).

Debugging

Füge --debug zu einem beliebigen Befehl hinzu, um die exakte HTTP-Anfrage und -Antwort (Header und Body) auf stderr auszugeben. API-Keys werden unkenntlich gemacht.

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: 2023-06-01
X-Api-Key: <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.