Opciones de autenticación de la CLI

La CLI ant admite varias fuentes de credenciales. El Inicio rápido cubre la ruta sencilla de un solo comando (ant auth login). Esta página cubre cada opción en detalle.

Inicio de sesión interactivo

ant auth login te permite llamar a la API sin crear ni administrar una clave de API. Abre un flujo OAuth basado en navegador contra la Claude Console y almacena las credenciales resultantes en $ANTHROPIC_CONFIG_DIR (consulta Directorio de configuración para conocer el valor predeterminado específico de cada sistema operativo). En un host remoto o en cualquier entorno sin un navegador local, pasa --no-browser para imprimir la URL de autorización y pega el código devuelto de vuelta en la terminal.

ant auth login

# En un host remoto sin navegador:
ant auth login --no-browser

# Vincula a un espacio de trabajo específico y omite el selector del navegador:
ant auth login --workspace-id wrkspc_01...

# Si el perfil con nombre que pasas con --profile no existe,
# se creará un nuevo perfil con ese nombre.
ant auth login --profile <profile-name>

Durante el flujo del navegador, seleccionas una organización y luego un workspace (espacio de trabajo). El token emitido está limitado a ese workspace, por lo que la CLI solo puede ver los recursos que le pertenecen. Pasa --workspace-id para vincularte directamente y omitir el selector. Para trabajar en más de un workspace, consulta Cambiar entre workspaces.

El inicio de sesión interactivo está pensado para el desarrollo local y la creación de scripts en tu propia máquina. Para cargas de trabajo no interactivas como CI, servidores y contenedores, usa Workload Identity Federation en su lugar.

El inicio de sesión escribe las credenciales en credentials/<profile>.json. El primer inicio de sesión para un perfil también crea configs/<profile>.json y lo establece como el perfil activo. Para eliminar las credenciales almacenadas, ejecuta ant auth logout, o ant auth logout --all para borrar todos los perfiles.

Acceso de administrador

De forma predeterminada, ant auth login solicita un token limitado a un workspace. Para administrar los recursos documentados en la página de la Admin API, solicita el alcance org:admin bajo un perfil dedicado:

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

# Imprime un token de portador para los encabezados Authorization:
ant auth print-credentials --profile admin --access-token

El alcance org:admin se otorga únicamente a los miembros de la organización con el rol de admin, owner o primary owner. El token emitido tiene acceso a toda la organización, y cualquier vinculación de workspace en el perfil no lo restringe. Mantén el perfil de administrador separado de tu perfil del día a día para que los comandos rutinarios nunca se ejecuten con acceso elevado.

Clave de API

La CLI también lee tu clave de API desde la variable de entorno ANTHROPIC_API_KEY. Obtén una clave en la Claude Console.

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

Para anular la clave en una sola invocación, pasa --api-key. Para apuntar a un host de API diferente, establece ANTHROPIC_BASE_URL o pasa --base-url.

Si estás usando una clave de API con alcance a múltiples workspaces, como una clave personal o de cuenta de servicio, debes especificar el workspace en el que ejecutar tu comando. Hazlo estableciendo una variable de entorno ANTHROPIC_WORKSPACE_ID, que la CLI lee automáticamente, o usando el flag --workspace-id. El valor debe ser un ID wrkspc_...; el literal default que los SDK aceptan en ANTHROPIC_WORKSPACE_ID para el intercambio de tokens federados no es válido aquí.

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

Verificar el estado de autenticación

ant auth status imprime la fuente de credenciales que la CLI seleccionó (variable de entorno de clave de API, inicio de sesión OAuth, federación o perfil), el perfil activo, el workspace al que está vinculado el token activo y las rutas del directorio de configuración. Úsalo para diagnosticar por qué una carga de trabajo eligió la credencial o el workspace incorrecto.

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)

Lee las filas (active) para ver qué fuente de credenciales y qué workspace prevalecieron. El comando informa el estado en lugar de realizar una comprobación de salud, así que no escribas scripts que dependan del código de salida. Para conocer el orden completo de las fuentes de credenciales, consulta Precedencia de credenciales.

Cambiar entre workspaces

Un token de inicio de sesión interactivo está vinculado a un único workspace. Para usar la CLI contra más de un workspace, inicia sesión en cada uno bajo su propio perfil con nombre y luego cambia entre ellos:

# 1. Crea el perfil (interactivo; elige el otro workspace en el
#    navegador, o pasa --workspace-id para omitir el selector):
# ant auth login --profile other-ws

# 2. Hazlo el predeterminado para los comandos siguientes:
ant profile activate other-ws

# 3. O selecciónalo para un solo comando sin cambiar el predeterminado:
ant --profile other-ws models list
ANTHROPIC_PROFILE=other-ws ant models list

Ejecuta ant auth status para confirmar qué perfil y qué workspace están activos.

Administrar perfiles

Los subcomandos ant profile inspeccionan y editan el estado de los perfiles directamente:

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

Las claves escribibles para ant profile set son workspace_id, base_url, organization_id, scope, client_id y console_url. Establecer workspace_id registra el workspace de destino en la configuración del perfil, pero no vuelve a vincular las credenciales que ya fueron emitidas; ejecuta ant auth login de nuevo bajo ese perfil para generar un token para el nuevo workspace.

Para el esquema del archivo de perfil y el bloque de federación, consulta Archivo de configuración de perfil. Para Workload Identity Federation, consulta la Descripción general de autenticación y la referencia de WIF.

Próximos pasos