Die CLI verwenden

Diese Seite behandelt die Ein- und Ausgabemechanismen der ant CLI, die für jeden Endpunkt gelten. Zur Installation und Authentifizierung siehe den Schnellstart. Um Befehle zu verketten und Ressourcen unter Versionskontrolle zu stellen, siehe 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 und Environments) befinden sich unter dem Präfix beta:. Befehle in diesem Namespace senden automatisch den passenden anthropic-beta-Header für diese Ressource, sodass du ihn nicht selbst übergeben musst. Verwende --beta <header> nur, um den Standardwert zu überschreiben (zum Beispiel, um eine andere Schema-Version zu wählen).

ant models list
ant messages create --model claude-opus-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 (pretty-printed) 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 weitergeleitet (gepiped) wird. Überschreibe beide Standardwerte mit --format:

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

type: model
id: claude-opus-5
display_name: Claude Opus 5
created_at: "2026-07-24T00: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 Auf- und Zuklappen 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 Umschlag (Envelope):

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

{"id": "agent_011CYm1BLqPX...", "name": "Docs CLI Test Agent", "model": "claude-opus-5"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-opus-5"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-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}' \
  --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, leite ein stdin-Dokument für verschachtelte oder mehrzeilige Bodies weiter und verwende @file-Referenzen, um Dateiinhalte in ein beliebiges String- oder Binärfeld zu übernehmen.

Flags

Skalare Felder werden direkt auf Flags abgebildet. Strukturierte Felder akzeptieren eine lockere 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 bauen Arrays auf. Jedes --tool oder --event hängt ein Element an:

ant beta:agents create \
  --name "Research Agent" \
  --model '{id: claude-opus-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 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 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 genauso und sind praktisch für mehrzeiliges YAML. Setze den Begrenzer 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
system: |
  You are a research assistant. Cite sources for every claim.
tools:
  - type: agent_toolset_20260401
YAML

Dateireferenzen

Flags, die einen Dateipfad entgegennehmen, 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 einzubetten, stelle dem Pfad ein @ voran:

ant beta:agents create \
  --name "Researcher" --model '{id: claude-opus-5}' \
  --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-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."}
  ]}' \
  --transform 'content.#(type=="text").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. 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 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.

Nächste Schritte