Uso de la CLI

Esta página cubre la mecánica de entrada y salida de la CLI ant que aplica a todos los endpoints. Para la instalación y autenticación, consulta el Quickstart. 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 de recurso acción. 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, environments y skills) se encuentran bajo el prefijo beta:. Los comandos en 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-4-8 --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 comandos que crean o modifican recursos. Los comandos de listar y recuperar usan por defecto el explorador interactivo cuando escriben a una terminal, y JSON con formato legible cuando se redirigen mediante pipe. Anula cualquiera de estos valores predeterminados con --format:

ant models retrieve --model-id claude-opus-4-8 --format yaml

type: model
id: claude-opus-4-8
display_name: Claude Opus 4.8
created_at: "2026-02-04T00:00:00Z"
...

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

Explorador interactivo

El explorador es una TUI de plegado y búsqueda para navegar respuestas grandes. Las teclas de flecha expanden y contraen nodos, / busca, q sale. Los comandos de listar y recuperar lo abren por defecto 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 endpoints de listado, la transformación se ejecuta contra cada elemento individualmente, no contra el envelope:

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

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

Extraer un escalar

Para capturar un solo campo como un string 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-sonnet-4-6}' \
  --transform id --raw-output)

printf '%s\n' "$AGENT_ID"

agent_011CYm1BLqPXpQRk5khsSXrs

Pasar cuerpos de solicitud

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

Flags

Los campos escalares se mapean directamente a flags. Los campos estructurados aceptan una sintaxis relajada similar a YAML (claves sin comillas, comillas opcionales alrededor de strings) 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 arrays. Cada --tool o --event agrega un elemento:

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

Stdin

Envía un documento JSON o YAML a stdin mediante pipe 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 deshabilitar la expansión de variables dentro del cuerpo.

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

Referencias a archivos

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

ant beta:files upload --file ./report.pdf

Para insertar el contenido de un archivo en un campo de tipo string, antepone @ a la ruta:

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

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

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

La CLI detecta el tipo de archivo y codifica los archivos binarios como base64 automáticamente. Para forzar una codificación específica, usa @file:// para texto plano o @data:// para base64. Escapa un @ literal inicial 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 redactan.

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: 2023-06-01
X-Api-Key: <REDACTED>
...

Recursos disponibles

Cada recurso de la API que expone la CLI está documentado en la referencia de la API. Para un listado local, ejecuta ant --help, y agrega --help a cualquier subcomando para ver sus flags y parámetros.