CLI ant de Claude Platform: Guía oficial para desarrolladores

Qué se lanzó

La versión corta: Claude Platform ahora cuenta con una CLI de API oficial llamada ant.

El tweet de lanzamiento es útil porque explica para qué sirve el producto: llamadas a la API, Managed Agents, tuberías (pipelines) de shell y agentes de codificación. La documentación oficial de la CLI detalla la mecánica: inicio de sesión OAuth, API keys, perfiles de espacio de trabajo, cuerpos de solicitud en YAML y JSON, transformaciones GJSON, paginación automática, salida de depuración, autocompletado de shell y ayuda sobre recursos.

The new workflow shape:

terminal command
  -> ant resource action
  -> Claude API endpoint
  -> structured JSON/YAML/raw output
  -> shell pipeline, CI step, or Claude Code agent

Definición en una frase

La ant CLI is Anthropic's command-line interface for calling Claude API resources from a terminal.No es un reemplazo para los SDK de Python o TypeScript. Es una interfaz nativa de shell para explorar endpoints, crear scripts de recursos de API, canalizar salidas y permitir que Claude Code inspeccione el estado de la plataforma sin necesidad de código de integración personalizado.

Modelo mental: Cuatro piezas

Leer ant como un pequeño adaptador entre los flujos de trabajo de shell y la Claude Platform.

[credentials/profile]
        |
        v
[ant resource:subresource action] --flags < stdin.yaml
        |
        v
[Claude API resource]
        |
        v
[formatted output] --transform -> shell, CI, or Claude Code

• Credenciales: Inicio de sesión OAuth, API key, federación o perfil con nombre.
• Comandos: un resource action patrón, con recursos anidados separados por dos puntos.
• Entrada: flags, YAML/JSON por stdin, y @file referencias para contenido de archivos en línea.
• Salida: JSON, YAML, JSONL formateados, salida sin procesar, explorador interactivo y transformaciones GJSON.

Instalar y verificar

The CLI docs show install paths for Homebrew on macOS, curl on Linux/WSL, and Go. The least ambiguous official commands are Homebrew and Go, followed by the version check:

# macOS
brew install anthropics/tap/ant

# Go
go install github.com/anthropics/anthropic-cli/cmd/ant@latest

# Verify
ant --version

La documentación también indica que cada recurso de API expuesto aparece en la salida de ayuda local. ant --help, luego añade --help al recurso ant messages create --help.

Autenticación: OAuth, API Keys y perfiles

La documentación oficial divide la autenticación en desarrollo local y cargas de trabajo no interactivas. Para una máquina de desarrollador, ant auth login abre un flujo de OAuth basado en navegador contra la Claude Console. Para hosts remotos sin un navegador local, el --no-browser flag imprime una URL de autorización y te pide que pegues el código devuelto.

ant auth login
ant auth login --no-browser
ant auth login --workspace-id wrkspc_01...
ant auth login --profile platform-dev

ant auth status
ant auth logout
ant auth logout --all

El detalle importante del workspace: durante el inicio de sesión OAuth, eliges una organización y un workspace. El token está limitado a ese workspace. Para trabajar en varios workspaces, crea un perfil por cada uno y cambia de perfil explícitamente.

ant auth login --profile other-ws
ant profile activate other-ws

ant --profile other-ws models list
ANTHROPIC_PROFILE=other-ws ant models list

Para CI, contenedores y servidores, la documentación de la CLI desaconseja el inicio de sesión interactivo y recomienda Workload Identity Federation. Esto mantiene limpia la regla post-instalación: OAuth para tu máquina, federación para automatización y API keys cuando necesites explícitamente autenticación basada en claves.

Solicitud de extremo a extremo más pequeña

Una vez que ant está instalado y autenticado, la documentación comienza con la Messages API. Esta es la estructura mínima: modelo, max tokens y un mensaje de usuario.

ant messages create \
  --model claude-opus-4-8 \
  --max-tokens 1024 \
  --message '{role: user, content: "Hello, Claude"}'

La documentación muestra la respuesta como el objeto completo de la API: ID del modelo, ID del mensaje, rol del asistente, array de contenido, motivo de parada y uso. La CLI imprime ese objeto con formato legible cuando stdout es una terminal.

Estructura de comandos

Los comandos siguen una forma resource action . Los recursos anidados usan dos puntos, y los recursos beta residen bajo beta:. La documentación clasifica a agents, sessions, deployments, environments y skills como recursos beta.

ant <resource>[:<subresource>] <action> [flags]

ant models list
ant messages create --model claude-opus-4-8 --max-tokens 1024 ...
ant beta:agents retrieve --agent-id agent_01...
ant beta:sessions:events list --session-id session_01...

El prefijo beta es importante porque esos comandos envían automáticamente el header apropiado para ese recurso. La documentación indica usar anthropic-beta solo cuando necesites anular la versión del esquema por defecto. --betaFormatos de salida y transformaciones GJSON

La salida es donde

Output is where ant se convierte en algo más que un simple envoltorio de conveniencia para curl. autoLa documentación enumera jsonAntigravity, jsonlGemini, yamlChrome, prettyMCP, rawAgent-First, exploree IDE. Los endpoints de lista se paginan automáticamente y la salida de la lista puede transmitirse limpiamente a comandos de shell.

El lenguaje de transformación es GJSON. Para los endpoints de lista, la transformación se ejecuta sobre cada elemento, no sobre el envoltorio completo. Es por eso que este patrón puede imprimir un resumen de agente por línea:

ant beta:agents list \
  --transform "{id,name,model}" \
  --format jsonl

Mi enfoque práctico: usa --format jsonl cuando el siguiente comando sea una herramienta de shell, y usa --transform id --raw-output cuando necesites un ID de recurso para el siguiente ant invocación.

Pasar cuerpos de solicitud sin JSON escrito a mano

La documentación de la CLI describe tres modos de entrada: flags, stdin y referencias a archivos. Los campos escalares se asignan a flags. Los campos estructurados aceptan una sintaxis flexible similar a YAML o JSON estricto. Los cuerpos de solicitud completos pueden enviarse a través de stdin como JSON o YAML.

ant beta:agents create <<'YAML'
name: Research Agent
model: claude-opus-4-8
system: |
  You are a research assistant. Cite sources for every claim.
tools:
  - type: agent_toolset_20260401
YAML

Para el contenido de archivos, la documentación utiliza @path. Esto permite incluir un archivo de prompt en un campo de cadena, o enviar un PDF a la Messages API, donde la CLI detecta y codifica automáticamente archivos binarios en base64.

ant beta:agents create \
  --name "Researcher" \
  --model '{id: claude-sonnet-4-6}' \
  --system @./prompts/researcher.txt

ant messages create \
  --model claude-opus-4-8 \
  --max-tokens 1024 \
  --message '{role: user, content: [
    {type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}},
    {type: text, text: "Extract the text from this scanned document."}
  ]}' \
  --transform 'content.0.text' --raw-output

Control de versiones de recursos de la API

El detalle de lanzamiento más importante para los equipos de plataforma no es la llamada de una línea a Messages. Es la sección de la documentación sobre cómo mantener los recursos de la API en archivos YAML. El ejemplo cubre un Managed Agent, un entorno, una sesión, un evento de usuario y un listado de eventos de sesión.

# summarizer.agent.yaml
name: Summarizer
model: claude-sonnet-4-6
system: |
  You are a helpful assistant that writes concise summaries.
tools:
  - type: agent_toolset_20260401

ant beta:agents create < summarizer.agent.yaml
ant beta:agents update --agent-id agent_011... --version 1 < summarizer.agent.yaml

# summarizer.environment.yaml
name: summarizer-env
config:
  type: cloud
  networking:
    type: unrestricted

ant beta:environments create < summarizer.environment.yaml

ant beta:sessions create \
  --agent agent_011CYm1BLqPXpQRk5khsSXrs \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "Summarization task"

Ese patrón convierte los recursos de la plataforma en archivos que puedes revisar, almacenar en un repositorio y actualizar desde CI. La CLI no elimina la necesidad de gobernanza, pero hace que el modelo de objetos operativos sea visible para los scripts de shell.

Usa ant desde Claude Code

El tweet de lanzamiento dice que ant es bien comprendido por los agentes de codificación, y la documentación de la CLI hace explícito el comportamiento de Claude Code: con ant instalado y autenticado, Claude Code puede ejecutar comandos, analizar la salida estructurada y razonar sobre los resultados.

Prompts the docs say are now reasonable:

"List my recent agent sessions and summarize which ones errored."
"Upload every PDF in ./reports to the Files API and print the resulting IDs."
"Pull the events for session session_01... and tell me where the agent got stuck."

La implicación práctica: Claude Code ya no necesita un script a medida para entender muchos recursos de Claude Platform. Instala ant, autentícalo en el workspace correcto y Claude Code obtendrá una superficie de comandos estructurada que puede utilizar.

Lo que entendí mal al leer el lanzamiento

Mi primera suposición errónea fue que ant era solo un envoltorio más bonito de la Messages API. La documentación deja claro el objetivo más amplio: operaciones de recursos de la API, Managed Agents en beta, entornos, sesiones, archivos, perfiles, transformaciones y la transferencia a Claude Code.

La segunda suposición errónea fue que el cambio de perfil siempre prevalece. No es así. Si ANTHROPIC_API_KEY está presente, la documentación indica que se omiten los perfiles. Eso es lo primero que comprobaría cuando un comando llega al workspace equivocado.

La tercera suposición errónea fue que --format raw y --raw-output son lo mismo. --raw-output con jq -r para cadenas de texto. --format raw imprime los bytes de respuesta sin procesar y se comporta de manera diferente en los endpoints de lista.

Depuración y autocompletado de shell

Para depurar, añade --debug. La documentación indica que imprime la solicitud HTTP exacta y la respuesta en stderr, con las API keys redactadas. Para inspeccionar errores, usa --format-error y --transform-error para filtrar las respuestas de error.

ant --debug beta:agents list

ant beta:agents retrieve --agent-id bogus \
  --transform-error error.message --format-error yaml 2>&1

La documentación también menciona que los scripts de autocompletado vienen incluidos para bash, zsh, fish y PowerShell. Esto es importante porque el árbol de comandos es extenso. El autocompletado reduce errores en nombres de recursos beta, recursos anidados y flags específicos de cada endpoint.

El veredicto

Evítala si necesitas integración de aplicaciones tipadas, abstracciones de SDK de larga duración o comportamiento en tiempo de ejecución integrado dentro de un servicio. La CLI es más potente en el límite entre un desarrollador, una terminal, los recursos de la plataforma y un agente capaz de leer salidas de comandos estructuradas.

FAQ

Glosario

ant

La herramienta de línea de comandos de Anthropic para los recursos de la API de Claude Platform.

Messages API

El endpoint de la API de Claude utilizado para enviar mensajes al modelo y recibir respuestas del asistente.

Agente gestionado

Un recurso de agente de la plataforma Claude configurado con modelo, system prompt, herramientas y comportamiento en tiempo de ejecución.

Workspace

Un ámbito de Claude Console que controla a qué recursos de la API pueden acceder las credenciales.

Profile

Una configuración de CLI con nombre utilizada para cambiar entre credenciales, workspace y ajustes relacionados.

GJSON

Una sintaxis de ruta utilizada por --transform para extraer o remodelar respuestas JSON.

JSONL

JSON delimitado por nuevas líneas, útil cuando cada elemento listado debe transmitirse como una sola línea.

Workload Identity Federation

Una ruta de autenticación no interactiva que la documentación recomienda para CI, servidores y contenedores.

Todas las fuentes y enlaces oficiales

Según la restricción de lanzamiento para esta publicación, no se utilizaron sitios comunitarios, hilos de Reddit, comentarios de Hacker News, publicaciones de blogs no oficiales ni tutoriales de terceros.