Opzioni di autenticazione della CLI

La CLI ant supporta diverse fonti di credenziali. La Guida rapida copre il percorso ideale 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 "API key" (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 incolla il codice restituito nel terminale.

ant auth login

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

# Associa a un workspace specifico e salta il selettore del browser:
ant auth login --workspace-id wrkspc_01...

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

Durante il flusso nel 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 associarti 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 admin, owner o primary owner. Il token emesso ha accesso a livello di intera organizzazione e qualsiasi associazione a un workspace nel profilo non lo limita. 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

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 con ambito su 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_...; il valore letterale default che gli SDK accettano in ANTHROPIC_WORKSPACE_ID per lo scambio di token federato non è valido qui.

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

Verificare lo stato dell'autenticazione

ant auth status stampa la fonte di 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 quale workspace hanno prevalso. Il comando riporta lo stato anziché eseguire un controllo di integrità, quindi non basare gli script sul codice 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, effettua il login a ciascuno sotto il proprio profilo denominato, quindi passa dall'uno all'altro:

# 1. Crea il profilo (interattivo; scegli l'altro workspace nel
#    browser, oppure passa --workspace-id per saltare la selezione):
# 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 quale workspace sono attivi.

Gestire i profili

I sottocomandi ant profile ispezionano e modificano direttamente lo stato dei profili:

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 nuovamente 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.

Passaggi successivi