Opções de autenticação da CLI

A CLI ant oferece suporte a várias fontes de credenciais. O Guia de início rápido cobre o caminho feliz de um único comando (ant auth login). Esta página cobre todas as opções em detalhes.

Login interativo

ant auth login permite que você chame a API sem criar ou gerenciar uma "API key" (chave de API). Ele abre um fluxo OAuth baseado em navegador no Claude Console e armazena as credenciais resultantes em $ANTHROPIC_CONFIG_DIR (consulte Diretório de configuração para o padrão específico de cada sistema operacional). Em um host remoto ou em qualquer ambiente sem um navegador local, passe --no-browser para imprimir a URL de autorização e cole o código retornado de volta no terminal.

ant auth login

# Em um host remoto sem navegador:
ant auth login --no-browser

# Vincule a um workspace específico e pule o seletor do navegador:
ant auth login --workspace-id wrkspc_01...

# Se o perfil nomeado que você passar com --profile não existir,
# um novo perfil nomeado será criado com esse nome.
ant auth login --profile <profile-name>

Durante o fluxo no navegador, você seleciona uma organização e, em seguida, um workspace. O token emitido tem escopo restrito a esse workspace, portanto a CLI só pode ver os recursos que pertencem a ele. Passe --workspace-id para vincular diretamente e pular o seletor. Para trabalhar em mais de um workspace, consulte Alternar entre workspaces.

O login interativo é destinado ao desenvolvimento local e à criação de scripts na sua própria máquina. Para cargas de trabalho não interativas, como CI, servidores e contêineres, use Workload Identity Federation.

O login grava as credenciais em credentials/<profile>.json. O primeiro login de um perfil também cria configs/<profile>.json e o define como o perfil ativo. Para remover as credenciais armazenadas, execute ant auth logout, ou ant auth logout --all para limpar todos os perfis.

Acesso de administrador

Por padrão, ant auth login solicita um token com escopo de workspace. Para gerenciar os recursos documentados na página da Admin API, solicite o escopo org:admin em um perfil dedicado:

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

# Imprima um bearer token para cabeçalhos Authorization:
ant auth print-credentials --profile admin --access-token

O escopo org:admin é concedido apenas a membros da organização com a função de admin, owner ou primary owner. O token emitido tem acesso a toda a organização, e qualquer vínculo de workspace no perfil não o restringe. Mantenha o perfil de administrador separado do seu perfil do dia a dia para que comandos de rotina nunca sejam executados com acesso elevado.

Chave de API

A CLI também lê sua chave de API da variável de ambiente ANTHROPIC_API_KEY. Obtenha uma chave no Claude Console.

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

Para substituir a chave em uma única invocação, passe --api-key. Para apontar para um host de API diferente, defina ANTHROPIC_BASE_URL ou passe --base-url.

Se você estiver usando uma chave de API com escopo para vários workspaces, como uma chave pessoal ou de conta de serviço, você deve especificar o workspace no qual executar seu comando. Faça isso definindo uma variável de ambiente ANTHROPIC_WORKSPACE_ID, que a CLI lê automaticamente, ou usando a flag --workspace-id. O valor deve ser um ID wrkspc_...; o literal default que os SDKs aceitam em ANTHROPIC_WORKSPACE_ID para a troca de token federado não é válido aqui.

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

Verificar o status da autenticação

ant auth status imprime a fonte de credencial que a CLI selecionou (variável de ambiente de chave de API, login OAuth, federação ou perfil), o perfil ativo, o workspace ao qual o token ativo está vinculado e os caminhos do diretório de configuração. Use-o para diagnosticar por que uma carga de trabalho escolheu a credencial ou o workspace errado.

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)

Leia as linhas (active) para ver qual fonte de credencial e qual workspace prevaleceram. O comando relata o status em vez de realizar uma verificação de integridade, portanto não crie scripts baseados no status de saída. Para a ordem completa das fontes de credenciais, consulte Precedência de credenciais.

Alternar entre workspaces

Um token de login interativo está vinculado a um único workspace. Para usar a CLI em mais de um workspace, faça login em cada um com seu próprio perfil nomeado e, em seguida, alterne entre eles:

# 1. Crie o perfil (interativo; escolha o outro workspace no
#    navegador ou passe --workspace-id para pular o seletor):
# ant auth login --profile other-ws

# 2. Torne-o o padrão para os comandos subsequentes:
ant profile activate other-ws

# 3. Ou selecione-o para um único comando sem alterar o padrão:
ant --profile other-ws models list
ANTHROPIC_PROFILE=other-ws ant models list

Execute ant auth status para confirmar qual perfil e qual workspace estão ativos.

Gerenciar perfis

Os subcomandos ant profile inspecionam e editam o estado dos perfis diretamente:

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

As chaves graváveis para ant profile set são workspace_id, base_url, organization_id, scope, client_id e console_url. Definir workspace_id registra o workspace de destino na configuração do perfil, mas não revincula credenciais que já foram emitidas; execute ant auth login novamente nesse perfil para emitir um token para o novo workspace.

Para o esquema do arquivo de perfil e o bloco de federação, consulte Arquivo de configuração de perfil. Para Workload Identity Federation, consulte a Visão geral de autenticação e a referência de WIF.

Próximos passos