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 (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 agentes, sesiones, despliegues y entornos) 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 sobrescribir el valor predeterminado (por ejemplo, para optar por una versión de esquema diferente).

ant models list
ant messages create --model claude-opus-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 por defecto el explorador interactivo cuando escriben en una terminal, y JSON con formato legible cuando se redirigen mediante pipe. Sobrescribe cualquiera de los valores predeterminados con --format:

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

type: model
id: claude-opus-5
display_name: Claude Opus 5
created_at: "2026-07-24T00: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 que fluye limpiamente hacia head, grep y los filtros de --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 listado y recuperación 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 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"}
{"id": "agent_011CYkVwfaEt...", "name": "Coffee Making Assistant", "model": "claude-opus-5"}
{"id": "agent_011CYixHhtUP...", "name": "Coding Assistant", "model": "claude-opus-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}' \
  --transform id --raw-output)

printf '%s\n' "$AGENT_ID"

agent_011CYm1BLqPXpQRk5khsSXrs

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, redirige un documento por stdin para cuerpos anidados o multilínea, y usa referencias @file para incorporar el contenido de archivos en cualquier campo de cadena o binario.

Flags

Los campos escalares se corresponden directamente con flags. Los campos estructurados aceptan una sintaxis relajada 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}' \
  --tool '{type: agent_toolset_20260401}' \
  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'

Stdin

Redirige 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 precedencia. 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 multilínea. 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-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}' \
  --system @./prompts/researcher.txt

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

ant messages create \
  --model claude-opus-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."}
  ]}' \
  --transform 'content.#(type=="text").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 al inicio 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: 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.

Próximos pasos