Die Claude-Kommandozeile einrichten

TL;DR

Die CLI und die SDKs lösen Zugangsdaten in einer festen Reihenfolge auf. Der mit Abstand häufigste Fehler: Ein vergessener exportierter ANTHROPIC_API_KEY überschreibt jedes Profil stillschweigend — und ein leer gesetzter tut es auch. Ihre Anfragen laufen dann gegen die Organisation dieses Schlüssels, ohne dass irgendwo eine Warnung erscheint.

Installation

# macOS
brew install anthropics/tap/ant
xattr -d com.apple.quarantine "$(brew --prefix)/bin/ant"

# Aus Quellcode, Go 1.22 oder neuer
go install github.com/anthropics/anthropic-cli/cmd/ant@latest

Der zweite Befehl auf macOS ist nötig, weil das Betriebssystem heruntergeladene Programme sonst blockiert.

Anmeldung ohne festen Schlüssel

ant auth login

Das öffnet den Browser, tauscht ein kurzlebiges Token und legt ein Profil unter ~/.config/anthropic/ ab. Danach funktionieren sowohl die CLI als auch die SDKs ohne gesetzte Umgebungsvariable:

import anthropic
client = anthropic.Anthropic()      # nimmt das Profil automatisch

Auf einem entfernten Rechner ohne Browser:

ant auth login --no-browser

Für nicht interaktive Umgebungen — CI, Server, Container — ist die interaktive Anmeldung nicht gedacht. Dort nehmen Sie Workload Identity Federation.

Die Auflösungsreihenfolge

Erster Treffer gewinnt:

1. ANTHROPIC_API_KEY
2. ANTHROPIC_AUTH_TOKEN
3. Das über ANTHROPIC_PROFILE gewählte oder aktive Profil
4. Umgebungsvariablen für Workload Identity Federation
5. Das Standardprofil auf der Platte

Die Falle

Profile werden nur berücksichtigt, wenn kein API-Schlüssel gesetzt ist.

Ein vergessener exportierter ANTHROPIC_API_KEY — aus einer alten Shell-Sitzung, einer .zshrc, einer Projektdatei — überschreibt lautlos jedes Profil. Die Anfragen laufen dann gegen die Organisation und den Arbeitsbereich dieses Schlüssels.

Und die Verschärfung, die man kennen muss: Ein leer gesetzter Schlüssel gewinnt ebenfalls. ANTHROPIC_API_KEY="" belegt seinen Platz in der Reihenfolge und authentifiziert mit einem leeren Wert. Sie müssen die Variable wirklich aufheben, nicht leeren.

ant auth status                    # zeigt, welche Quelle gewonnen hat
unset ANTHROPIC_API_KEY            # nicht auf "" setzen

# Für einen einzelnen Befehl:
env -u ANTHROPIC_API_KEY ant models list

ant auth status ist der erste Befehl bei jedem Authentifizierungsproblem. Er meldet Quelle und aktives Profil — nutzen Sie ihn allerdings nicht als Zustandsprüfung in einem Skript; er berichtet nur.

Dieselbe Verschattung gibt es in umgekehrter Richtung mit Claude Code: Nach ant auth login kann Claude Code einen Konflikt zwischen Profil und eigener Anmeldung melden. Entscheiden Sie sich für eines.

Profile je Arbeitsbereich

Ein Anmeldetoken ist an eine Organisation und einen Arbeitsbereich gebunden, und die API zeigt nur Ressourcen dieses Arbeitsbereichs.

Wenn ein Agent, eine Sitzung oder eine Datei "verschwunden" ist, ist das fast immer die Ursache: Das Token gehört zu einem anderen Arbeitsbereich als dem, in dem die Ressource angelegt wurde.

ant auth login --profile produktion
ant auth login --profile test --workspace-id wrkspc_01...

ant profile list
ant profile activate produktion
ant --profile test models list          # einmalig

Zwei Punkte, die Zeit kosten, wenn man sie nicht weiß: ant profile set bearbeitet nur die Konfiguration und bindet bereits ausgestellte Zugangsdaten nicht neu — dafür ist eine erneute Anmeldung unter diesem Profil nötig. Und Erneuerungstoken laufen irgendwann endgültig ab; wenn ein zuvor funktionierendes Profil plötzlich scheitert, melden Sie sich neu an, bevor Sie irgendetwas anderes untersuchen.

Zugangsdaten weiterreichen

Für curl oder ein Skript:

curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: oauth-2025-04-20" \
  -H "content-type: application/json" \
  -d '{"model":"claude-opus-5","max_tokens":1024,
       "messages":[{"role":"user","content":"Hallo"}]}'

Drei Dinge, die dabei schiefgehen:

--access-token ist Pflicht. Ohne die Option gibt der Befehl das gesamte Zugangsdaten-JSON aus — in einer Kopfzeile ergibt das eine leere Antwort oder einen Protokollfehler.

OAuth-Token gehören auf Authorization: Bearer, nicht auf x-api-key. Der Wechsel von einem API-Schlüssel ist eine Änderung der Kopfzeile, kein Austausch des Werts.

Die Kopfzeile anthropic-beta: oauth-2025-04-20 wird gebraucht. Bei manchen Endpunkten geht es ohne, beim Nachrichten-Endpunkt nicht — setzen Sie sie immer.

Für eine .env-Ausgabe:

set -a; eval "$(ant auth print-credentials --env)"; set +a

Achtung: Wenn danach sowohl ANTHROPIC_API_KEY als auch ANTHROPIC_AUTH_TOKEN gesetzt sind, senden die SDKs beide Kopfzeilen und die API lehnt ab. Vorher aufheben.

Was die CLI praktisch besser kann als curl

# Nackte Kennung für die Weiterverarbeitung
AGENT_ID=$(ant beta:agents create < agent.yaml --transform id -r)

# Dateiinhalt einbetten
ant messages create --model claude-opus-5 --max-tokens 1024 \
  --message '{role: user, content: "@./CLAUDE.md"}' \
  --transform 'content.0.text' -r

# Volle Anfrage und Antwort zur Fehlersuche
ant beta:agents list --debug

--transform nimmt einen Pfadausdruck und wirkt bei Listen-Endpunkten je Element, nicht auf die Hülle. -r gibt Zeichenketten ohne Anführungszeichen aus. @ bettet Dateiinhalte in jedes Zeichenkettenfeld ein.

Der eigentliche Wert liegt darin, Agenten und Umgebungen als versionierte YAML-Dateien zu führen und aus der Versionsverwaltung anzuwenden — die Systematik steht im Beitrag zu Managed Agents.

Häufig gestellte Fragen

Warum wird mein Profil ignoriert?

Weil vermutlich ein ANTHROPIC_API_KEY gesetzt ist. Profile werden nur berücksichtigt, wenn kein API-Schlüssel vorliegt — und ein auf einen leeren Wert gesetzter Schlüssel belegt seinen Platz in der Reihenfolge trotzdem. Heben Sie die Variable auf, statt sie zu leeren, und prüfen Sie mit ant auth status, welche Quelle gewonnen hat.

Brauche ich einen API-Schlüssel für die SDKs?

Nein. Nach ant auth login nimmt der leere Konstruktor der SDKs das abgelegte Profil automatisch auf, ohne dass eine Umgebungsvariable gesetzt sein muss. Skripte, die ANTHROPIC_API_KEY direkt auslesen, funktionieren dann allerdings nicht — die brauchen entweder den Schlüssel oder die weitergereichten Zugangsdaten.

Warum finde ich meine Agenten oder Sitzungen nicht?

Fast immer, weil das Token zu einem anderen Arbeitsbereich gehört als dem, in dem die Ressource angelegt wurde. Ein Anmeldetoken ist an genau eine Organisation und einen Arbeitsbereich gebunden, und die API zeigt nur dessen Ressourcen. ant auth status zeigt den aktiven Arbeitsbereich.

Wie reiche ich Zugangsdaten an curl weiter?

Mit ant auth print-credentials --access-token und der Kopfzeile Authorization: Bearer, ergänzt um anthropic-beta: oauth-2025-04-20. Die Option --access-token ist Pflicht — ohne sie gibt der Befehl das gesamte Zugangsdaten-JSON aus, was in einer Kopfzeile nicht funktioniert.

Eignet sich die interaktive Anmeldung für CI?

Nein, sie ist für die Entwicklung am eigenen Rechner gedacht. Für nicht interaktive Umgebungen wie CI-Läufe, Server und Container nutzen Sie Workload Identity Federation, die von den SDKs automatisch erkannt wird, sobald die entsprechenden Umgebungsvariablen gesetzt sind.

Der nächste Schritt

Führen Sie ant auth status aus, bevor Sie irgendein Authentifizierungsproblem untersuchen. In den meisten Fällen steht die Antwort dort — und in den meisten dieser Fälle heißt sie: Ein alter API-Schlüssel überschreibt Ihr Profil. Bei der Einrichtung helfen wir gern.