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 la instalación y autenticación, 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, 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-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 canalizan. Anula 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 se 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 se transmite 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 colapsan nodos, / busca, 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 contra cada elemento individualmente, no contra 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 correcto 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 tipo string o binario.



Flags

Los campos escalares se asignan 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 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

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 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 beta:files upload --file ./report.pdf

Para incorporar el contenido de un archivo en un campo de tipo string, 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 @ 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 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 la CLI expone 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