Opzioni di autenticazione della CLI

La CLI ant supporta diverse fonti di credenziali. La Guida rapida copre il percorso più semplice con un solo comando (ant auth login). Questa pagina copre ogni opzione in modo completo.

Login interattivo

ant auth login ti consente di chiamare l'API senza creare o gestire una chiave API. Apre un flusso OAuth basato su browser verso la Claude Console e memorizza le credenziali risultanti in $ANTHROPIC_CONFIG_DIR (consulta Directory di configurazione per il valore predefinito specifico del sistema operativo). Su un host remoto o in qualsiasi ambiente senza un browser locale, passa --no-browser per stampare l'URL di autorizzazione e incollare il codice restituito nel terminale.

ant auth login

# Su un host remoto senza browser:
ant auth login --no-browser

# Associa a uno spazio di lavoro specifico e salta il selettore del browser:
ant auth login --workspace-id wrkspc_01...

# Se il profilo con nome che passi con --profile non esiste,
# verrà creato un nuovo profilo con quel nome.
ant auth login --profile <profile-name>

Durante il flusso del browser, selezioni un'organizzazione e poi un workspace. Il token emesso è limitato a quel workspace, quindi la CLI può vedere solo le risorse che gli appartengono. Passa --workspace-id per effettuare il binding direttamente e saltare il selettore. Per lavorare in più di un workspace, consulta Passare da un workspace all'altro.

Il login interattivo è pensato per lo sviluppo locale e lo scripting sulla tua macchina. Per carichi di lavoro non interattivi come CI, server e container, usa invece Workload Identity Federation.

Il login scrive le credenziali in credentials/<profile>.json. Il primo login per un profilo crea anche configs/<profile>.json e lo imposta come profilo attivo. Per rimuovere le credenziali memorizzate, esegui ant auth logout, oppure ant auth logout --all per cancellare ogni profilo.

Accesso amministratore

Per impostazione predefinita, ant auth login richiede un token limitato al workspace. Per gestire le risorse documentate nella pagina Admin API, richiedi lo scope org:admin sotto un profilo dedicato:

ant auth login --profile admin --scope "org:admin"

# Stampa un bearer token per gli header Authorization:
ant auth print-credentials --profile admin --access-token

Lo scope org:admin viene concesso solo ai membri dell'organizzazione con il ruolo di amministratore, proprietario o proprietario principale. Il token emesso ha accesso a livello di organizzazione, e qualsiasi binding del workspace sul profilo non lo vincola. Mantieni il profilo amministratore separato dal tuo profilo quotidiano in modo che i comandi di routine non vengano mai eseguiti con accesso elevato.

Chiave API

La CLI legge anche la tua chiave API dalla variabile d'ambiente ANTHROPIC_API_KEY. Ottieni una chiave dalla Claude Console.

echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.zshrc
source ~/.zshrc

echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.bashrc
source ~/.bashrc

setx ANTHROPIC_API_KEY "sk-ant-api03-..."

Per sovrascrivere la chiave per una singola invocazione, passa --api-key. Per puntare a un host API diverso, imposta ANTHROPIC_BASE_URL o passa --base-url.

Se stai usando una chiave API limitata a più workspace, come una chiave personale o di account di servizio, devi specificare il workspace in cui eseguire il comando. Fallo impostando una variabile d'ambiente ANTHROPIC_WORKSPACE_ID, che la CLI legge automaticamente, oppure usando il flag --workspace-id. Il valore deve essere un ID wrkspc_....

ant messages create \
  --workspace-id wrkspc_01... \
  --model claude-opus-5-5 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

Verifica lo stato di autenticazione

ant auth status stampa la fonte delle credenziali selezionata dalla CLI (variabile d'ambiente della chiave API, login OAuth, federazione o profilo), il profilo attivo, il workspace a cui è associato il token attivo e i percorsi della directory di configurazione. Usalo per diagnosticare perché un carico di lavoro ha scelto la credenziale o il workspace sbagliato.

ant auth status

Active profile:  default
Config dir:      ~/.config/anthropic
Profile config:  ~/.config/anthropic/configs/default.json
Credentials:     ~/.config/anthropic/credentials/default.json

Credentials
  (active) * Profile (user_oauth) [via active_config]       sk-ant-oat01-EXA...
...

Workspace
  (active) * Workspace                                      wrkspc_01... (Engineering)

Leggi le righe (active) per vedere quale fonte di credenziali e workspace ha prevalso. Il comando riporta lo stato anziché eseguire un controllo di integrità, quindi non creare script basati sullo stato di uscita. Per l'ordinamento completo delle fonti di credenziali, consulta Precedenza delle credenziali.

Passare da un workspace all'altro

Un token di login interattivo è associato a un singolo workspace. Per usare la CLI con più di un workspace, accedi a ciascuno sotto il proprio profilo con nome, quindi passa da uno all'altro:

# 1. Crea il profilo (interattivo; seleziona l'altro workspace nel
#    browser, oppure passa --workspace-id per saltare il selettore):
# ant auth login --profile other-ws

# 2. Rendilo il predefinito per i comandi successivi:
ant profile activate other-ws

# 3. Oppure selezionalo per un singolo comando senza cambiare il predefinito:
ant --profile other-ws models list
ANTHROPIC_PROFILE=other-ws ant models list

Esegui ant auth status per confermare quale profilo e workspace sono attivi.

Gestire i profili

I sottocomandi ant profile ispezionano e modificano direttamente lo stato del profilo:

ant profile list
ant profile get --profile other-ws
ant profile set workspace_id wrkspc_01... --profile other-ws

Le chiavi scrivibili per ant profile set sono workspace_id, base_url, organization_id, scope, client_id e console_url. Impostare workspace_id registra il workspace di destinazione nella configurazione del profilo ma non riassocia le credenziali già emesse; esegui di nuovo ant auth login sotto quel profilo per generare un token per il nuovo workspace.

Per lo schema del file di profilo e il blocco di federazione, consulta File di configurazione del profilo. Per Workload Identity Federation, consulta la Panoramica dell'autenticazione e il riferimento WIF.

Prossimi passi