Uso de la CLI

Esta página cubre la mecánica de entrada y salida de la CLI ant que se aplica a todos los endpoints. Para instalar y autenticarte, consulta el Inicio rápido. Para encadenar comandos y controlar versiones de recursos, consulta Scripting y automatización con la CLI.

Estructura de comandos

Los comandos siguen un patrón resource action. Los recursos anidados usan dos puntos:

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

Ejecuta ant --help para ver la lista completa de recursos, o agrega --help a cualquier subcomando para ver sus flags.

Los recursos en beta (incluidos agents, sessions, deployments y environments) se encuentran bajo el prefijo beta:. Los comandos de este espacio de nombres envían automáticamente el encabezado anthropic-beta apropiado para ese recurso, por lo que no necesitas pasarlo tú mismo. Usa --beta <header> solo para anular el valor predeterminado (por ejemplo, para optar por una versión de esquema diferente).

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

Flags globales

Formatos de salida

auto imprime JSON con formato legible y es el valor predeterminado para los comandos que crean o modifican recursos. Los comandos de listado y recuperación usan de forma predeterminada el explorador interactivo cuando escriben en una terminal, y JSON con formato legible cuando se canalizan. Anula cualquiera de los dos valores predeterminados con --format:

ant models retrieve --model-id claude-opus-5-5 --format yaml

type: model
id: claude-opus-5-5
display_name: Claude Opus 5.5
created_at: "2026-09-22T00:00:00Z"
...

Los endpoints de listado se paginan automáticamente. En los formatos predeterminados, cada elemento se escribe por separado (un objeto JSON compacto por línea en el modo jsonl, un flujo de documentos YAML en el modo yaml), lo que se canaliza limpiamente hacia head, grep y filtros --transform.

Explorador interactivo

El explorador es una TUI con plegado y búsqueda para navegar respuestas grandes. Las teclas de flecha expanden y contraen nodos, / busca y q sale. Los comandos de listado y recuperación lo abren de forma predeterminada cuando están conectados a una terminal. Pasa --format explore para abrirlo explícitamente:

ant models list --format explore

Transformar la salida con GJSON

Usa --transform para reestructurar las respuestas antes de imprimirlas. La expresión es una ruta GJSON. Para los endpoints de listado, la transformación se ejecuta sobre cada elemento individualmente, no sobre el envoltorio:

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

{"id": "agent_011CYm1BLqPX...", "name": "Docs CLI Test Agent", "model": "claude-opus-5-5"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-opus-5-5"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-5-5"}

Extraer un escalar

Para capturar un solo campo como una cadena sin comillas (por ejemplo, el ID de un recurso recién creado), combina --transform con --raw-output. El resultado se imprime sin comillas JSON y está listo para asignarse a una variable de shell:

AGENT_ID=$(ant beta:agents create \
  --name "My Agent" \
  --model '{id: claude-opus-5-5}' \
  --transform id --raw-output)

Pasar cuerpos de solicitud

El mecanismo de entrada adecuado depende de la forma de los datos: usa flags para campos escalares y valores estructurados cortos, canaliza un documento por stdin para cuerpos anidados o de varias líneas, y usa referencias @file para incorporar el contenido de archivos en cualquier campo de cadena o binario.

Flags

Los campos escalares se asignan directamente a flags. Los campos estructurados aceptan una sintaxis flexible similar a YAML (claves sin comillas, comillas opcionales alrededor de las cadenas) o JSON estricto:

ant beta:sessions create \
  --agent '{type: agent, id: agent_011CYm1BLqPXpQRk5khsSXrs, version: 1}' \
  --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
  --title "CLI docs test session"

Los flags repetibles construyen arreglos. Cada --tool o --event agrega un elemento:

ant beta:agents create \
  --name "Research Agent" \
  --model '{id: claude-opus-5-5}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'

Stdin

Canaliza un documento JSON o YAML a stdin para proporcionar el cuerpo completo de la solicitud. Los campos de stdin se combinan con los flags, y los flags tienen prioridad. Aquí version es el token de bloqueo optimista devuelto por un retrieve anterior, y $AGENT_ID se capturó como en Extraer un escalar:

echo '{"description": "Updated test agent.", "version": 1}' | \
  ant beta:agents update --agent-id "$AGENT_ID"

Los heredocs funcionan de la misma manera y son convenientes para YAML de varias líneas. Pon el delimitador entre comillas (como en <<'YAML') para desactivar la expansión de variables dentro del cuerpo.

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

Referencias a archivos

Los flags que aceptan una ruta de archivo, como --file en el comando de carga, aceptan una ruta simple:

ant files upload --file ./report.pdf

Para insertar el contenido de un archivo en un campo con valor de cadena, antepón @ a la ruta:

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

Dentro de valores de flags estructurados, pon la ruta entre comillas. Para enviar un PDF a la Messages API:

ant messages create \
  --model claude-opus-5-5 \
  --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."}
  ]}'

La CLI detecta el tipo de archivo y codifica automáticamente los archivos binarios en base64. Para forzar una codificación específica, usa @file:// para texto plano o @data:// para base64. Escapa un @ inicial literal con una barra invertida (\@username).

Depuración

Agrega --debug a cualquier comando para imprimir la solicitud y respuesta HTTP exactas (encabezados y cuerpo) en stderr. Las claves de API se ocultan.

ant --debug beta:agents list

GET /v1/agents?beta=true HTTP/1.1
Host: api.anthropic.com
Anthropic-Beta: managed-agents-2026-04-01
Anthropic-Version: 2026-10-21
Authorization: Bearer <REDACTED>
...

Recursos disponibles

Todos los recursos de la API que expone la CLI están documentados en la referencia de la API. Para obtener un listado local, ejecuta ant --help y agrega --help a cualquier subcomando para ver sus flags y parámetros.

Próximos pasos