--- title: Uso de la CLI url: https://platform.claude.com/docs/es/cli-sdks-libraries/cli/using description: Estructura de comandos, formatos de salida, transformaciones GJSON, cuerpos de solicitud y depuración para la CLI ant. --- 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](https://platform.claude.com/docs/es/cli-sdks-libraries/cli/quickstart). Para encadenar comandos y controlar versiones de recursos, consulta [Scripting y automatización con la CLI](https://platform.claude.com/docs/es/cli-sdks-libraries/cli/scripting). ## Estructura de comandos Los comandos siguen un patrón `resource action` (recurso acción). Los recursos anidados usan dos puntos: ```text wrap ant [:] [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

` solo para sobrescribir el valor predeterminado (por ejemplo, para optar por una versión de esquema diferente). ```bash 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 | Flag | Descripción | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--profile` | Perfil con nombre a usar para esta invocación (equivalente a establecer `ANTHROPIC_PROFILE`). Consulta [Cambiar entre espacios de trabajo](https://platform.claude.com/docs/es/cli-sdks-libraries/cli/authentication#switch-between-workspaces). | | `--format` | Formato de salida: `auto`, `json`, `jsonl`, `yaml`, `pretty`, `raw`, `explore` | | `--transform` | Filtra o reestructura la respuesta con una [ruta GJSON](https://platform.claude.com/docs/es/cli-sdks-libraries/cli/using#transform-output-with-gjson) | | `-r`, `--raw-output` | Imprime resultados de tipo cadena sin comillas alrededor, como `jq -r` | | `--base-url` | Sobrescribe la URL base de la API | | `--workspace-id` | Opcional. ID del espacio de trabajo (`wrkspc_...`) a enviar como el encabezado `anthropic-workspace-id`, para claves de API con acceso a múltiples espacios de trabajo (equivalente a establecer `ANTHROPIC_WORKSPACE_ID`). Consulta [Seleccionar un espacio de trabajo](https://platform.claude.com/docs/es/manage-claude/authentication#select-a-workspace). Los comandos de la [Admin API](https://platform.claude.com/docs/es/manage-claude/admin-api) aceptan su propio `--workspace-id`, que en su lugar indica el espacio de trabajo que administran. | | `--debug` | Imprime la solicitud y respuesta HTTP completas en stderr | | `--format-error`, `--transform-error` | Igual que `--format` y `--transform` pero aplicados a las [respuestas de error](https://platform.claude.com/docs/es/cli-sdks-libraries/cli/scripting#inspect-errors) | ## 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](https://platform.claude.com/docs/es/cli-sdks-libraries/cli/using#interactive-explorer) cuando escriben en una terminal, y JSON con formato legible cuando se redirigen mediante pipe. Sobrescribe cualquiera de los valores predeterminados con `--format`: ```bash ant models retrieve --model-id claude-opus-5-5 --format yaml ``` ```yaml Output type: model id: claude-opus-5-5 display_name: Claude Opus 5.5 created_at: "2026-09-22T00: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: ```bash 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](https://github.com/tidwall/gjson/blob/master/SYNTAX.md). Para los endpoints de listado, la transformación se ejecuta sobre cada elemento individualmente, no sobre el envoltorio: ```bash ant beta:agents list \ --transform "{id,name,model}" \ --format jsonl ``` ```jsonl Output {"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: ```bash AGENT_ID=$(ant beta:agents create \ --name "My Agent" \ --model '{id: claude-opus-5-5}' \ --transform id --raw-output) printf '%s\n' "$AGENT_ID" ``` ```text Output wrap agent_011CYm1BLqPXpQRk5khsSXrs ``` `--raw-output` es distinto de `--format raw`. `--raw-output` elimina las comillas JSON de los resultados de tipo cadena, como `jq -r`. `--format raw` imprime los bytes JSON sin procesar del cuerpo de la respuesta sin paginar automáticamente; en los endpoints de listado aplica `--transform` al envoltorio de paginación en lugar de a cada elemento. ## 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: ```bash 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: ```bash 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 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](https://platform.claude.com/docs/es/cli-sdks-libraries/cli/using#extract-a-scalar): ```bash 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. ```bash 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: ```bash 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: ```bash ant beta:agents create \ --name "Researcher" --model '{id: claude-opus-5-5}' \ --system @./prompts/researcher.txt ``` Dentro de valores de flags estructurados, envuelve la ruta entre comillas. Para enviar un PDF a la Messages API: ```bash 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."} ]}' \ --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. ```bash ant --debug beta:agents list ``` ```text Output wrap 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: ... ``` ## Recursos disponibles Cada recurso de la API que expone la CLI está documentado en la [referencia de la API](https://platform.claude.com/docs/es/api/cli/messages/create). Para un listado local, ejecuta `ant --help`, y agrega `--help` a cualquier subcomando para ver sus flags y parámetros. ## Próximos pasos Control de versiones de recursos de la API, patrones de scripting y uso desde Claude Code Parámetros específicos de cada endpoint, campos de solicitud y esquemas de respuesta Claves de API, hosts sin interfaz, múltiples espacios de trabajo y perfiles con nombre