Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

CLI headless (ax-code run)

Estado: Activo Alcance: estado actual Última revisión: 2026-09-22 Responsable: mantenedores del entorno de ejecución de AX Code

ax-code run es el punto de entrada de un solo uso y no interactivo para agentes de programación con IA y scripts. Envía un único prompt, imprime la respuesta final del asistente y sale: sin interfaz de terminal ni prompts interactivos. Esta guía cubre la superficie de opciones, el contrato de salida, los códigos de salida y recetas para copiar y pegar en scripts y CI.

Invocar una ejecución

Hay cuatro formas de suministrar el prompt. Se componen en orden: --prompt-file, luego -p/--prompt, luego el mensaje posicional y luego stdin por tubería.

# Positional after -- (safest; flags after -- are never consumed as options)
ax-code run --model qwen -- "Review this change"

# Explicit prompt flag
ax-code run --model qwen --prompt "Review this change"
ax-code run --model qwen -p "Review this change"

# Prompt read from a file (not an attachment)
ax-code run --model qwen --prompt-file ./prompt.txt

# Piped stdin (used as the prompt when no positional/--prompt is given)
printf 'Review this change' | ax-code run --model qwen

Cuando stdin no es un TTY, su contenido se añade al prompt compuesto, así que es el prompt completo cuando no se suministra nada más. El lector de stdin espera una ventana de silencio de 300 ms antes de rendirse ante una tubería abierta, así que escribe el prompt enseguida y cierra stdin, o usa --prompt-file para prompts grandes o producidos con lentitud. --prompt-file - lee el prompt desde stdin de forma explícita (error de uso cuando stdin es un TTY); el añadido implícito de stdin por tubería nunca se ejecuta una segunda vez en esa invocación.

-f/--file adjunta archivos al mensaje y nunca sustituye el prompt; se puede repetir:

ax-code run --model qwen --file README.md --file src/main.ts -- "Summarize these"

Un adjunto debe vivir dentro del directorio del proyecto: el servidor rechaza adjuntos fuera de él con independencia de las reglas de permiso, así que la CLI los rechaza de antemano con un error de uso. Copia el archivo al proyecto o pasa su contenido con --prompt-file. --add-dir concede a las herramientas acceso a directorios extra, pero no cambia esta regla.

Los tipos mime de los adjuntos se infieren de la extensión: png, jpg, jpeg, gif y webp se asignan a su tipo image/* y pdf a application/pdf, así que los adjuntos binarios llegan al servidor con su tipo real en lugar de text/plain. Cualquier otra cosa — incluido un archivo sin extensión reconocida — se envía como text/plain, y un adjunto de directorio se clasifica como application/x-directory.

Dirigir la ejecución

Tres marcas dirigen una ejecución sin cambiar el texto del prompt. Todas son solo de forma larga y kebab-case.

--append-system-prompt TEXT / --append-system-prompt-file PATH

Añade texto extra al prompt de sistema después de los prompts de sistema del agente y del entorno: añade y nunca sustituye el prompt de sistema integrado. Las dos formas son mutuamente excluyentes. Una variante de archivo conviene para instrucciones más largas; se recorta exactamente un salto de línea final, y un texto vacío (o un archivo ilegible) es un error de uso antes de que se envíe nada.

ax-code run --model qwen --append-system-prompt "Answer in English only" -- "Review this change"

--disallowed-tools a,b

Desactiva herramientas por id durante la ejecución (separadas por comas, repetible). Se aplica mediante ambos mecanismos del servidor: las reglas de denegación de la sesión creada cubren las ejecuciones nuevas, y un mapa de herramientas por solicitud cubre también las ejecuciones reanudadas de --session/--continue. Denegar bash también deniega el comando de la herramienta monitor, que se ejecuta a través del mismo lanzador de shell; una llamada que choca con una regla de denegación falla como error de herramienta y cuenta como denegación para el estado de ejecución bloqueada. Los id desconocidos no son un error — los id de herramientas MCP son dinámicos — pero con el formato predeterminado cada id fuera del conjunto de herramientas integradas imprime un aviso en stderr (suprimido por --quiet).

ax-code run --model qwen --disallowed-tools bash,write -- "Audit this module without mutating anything"

--add-dir PATH

Concede al agente acceso a un directorio adicional (repetible): se añade una regla de permiso external_directory para <resolved-path>/* a las reglas de permiso de la sesión nueva, cubriendo el directorio y todo lo que hay debajo. Cada ruta debe existir y ser un directorio (resuelta respecto al cwd del llamador, como --file). La regla se aplica cuando se crea la sesión, así que bajo --session/--continue no puede surtir efecto: la CLI imprime --add-dir applies only to new sessions en stderr y continúa. No cambia la contención de --file: los adjuntos deben seguir viviendo dentro del directorio del proyecto. Cubre las herramientas de archivo (read, glob, grep, list, edit, write); un comando de shell que entra en el directorio a través de una ruta dinámica sigue disparando el prompt de acceso a ruta, solo interactivo, que una ejecución headless rechaza de forma automática, así que prefiere las herramientas de archivo o pasa el contenido del archivo de forma explícita.

ax-code run --model qwen --add-dir ../design-docs -- "Read ../design-docs/spec.md and summarize it"

Elegir un modelo

Lista los ID utilizables con ax-code models. Pasa el valor provider/model resultante a --model (-m):

ax-code models            # one "provider/model" ID per line
ax-code models --json     # one JSON document

ax-code models --json imprime un único documento de la forma {"models":[{"id":"provider/model","provider":"...","model":"...","connected":true}]}.

Los nombres de familia deepseek, glm y qwen se resuelven a sus valores predeterminados Flash, así que ax-code run --model qwen -- "..." funciona sin escribir un ID provider/model completo. Omitir --model usa el valor predeterminado configurado; el agente y el modelo efectivos se imprimen en stderr como > Agent · model.

Formatos de salida

--format acepta default (el predeterminado), json, jsonl o ndjson (jsonl y ndjson son alias de json).

Predeterminado (texto)

El formato predeterminado imprime solo el texto final del asistente en stdout. Todo el progreso, la actividad de herramientas y los diagnósticos van a stderr, empezando por una cabecera > Agent · model · ses_... que incluye el id de sesión, para que un llamador de varios turnos pueda reanudar con --session sin cambiar a --format json (--quiet suprime la cabecera). Los colores ANSI se desactivan cuando stderr no es un TTY o cuando NO_COLOR está definido (cualquier valor), así que una ejecución por tubería nunca emite códigos de escape.

Flujo JSON (--format json)

--format json imprime un flujo de eventos JSON delimitado por saltos de línea (NDJSON): un objeto JSON por línea, no un único documento JSON. Los eventos incluyen step_start, text, tool_use, reasoning (solo con --thinking), permission_denied, error y step_finish. El flujo siempre termina con exactamente una línea result:

{
  "type": "result",
  "timestamp": 1727000000000,
  "sessionID": "ses_...",
  "status": "completed",
  "text": "...",
  "permissionDenials": 0,
  "usage": { "input": 1200, "output": 80, "reasoning": 0, "cacheRead": 0, "cacheWrite": 0 }
}

status es completed, blocked o error. usage lleva solo recuentos de tokens — input, output, reasoning, cacheRead, cacheWrite — y se omite por completo cuando los recuentos son desconocidos; no hay campo de coste. Cuando una ejecución falla antes de enviarse (marca incorrecta, modelo desconocido, etc.), el formato de flujo imprime una línea antes de salir:

{ "type": "error", "error": { "code": "usage", "message": "..." } }

El error.code es uno de:

Códigos de salida

Sandbox

--sandbox read-only|workspace-write|full-access selecciona el modo de aislamiento (predeterminado full-access). En las ejecuciones headless las preguntas de permiso se rechazan de forma automática y se informan como eventos permission_denied, así que una ejecución que necesita una escritura que no se le permitió hacer informa blocked y sale con 3. Esto cubre también a los subagentes: las preguntas planteadas en sesiones hijas creadas por la herramienta task se rechazan del mismo modo, y sus eventos permission_denied llevan el sessionID hijo. Las llamadas a herramientas rechazadas por una regla de denegación de permiso (por ejemplo desde --disallowed-tools) o por el sandbox de solo lectura también cuentan como denegaciones. Las herramientas interactivas question y plan_exit están siempre desactivadas en una ejecución headless, incluso en sesiones reanudadas. Usa read-only solo cuando no se espera ninguna mutación; workspace-write mantiene las escrituras dentro del proyecto.

Bajo --attach la marca también se envía como política de aislamiento por solicitud en cada cuerpo de prompt; el servidor aplica la más estricta entre su propio modo y la política solicitada, así que solo puede endurecer. La misma política por solicitud se envía para servidores de propiedad local, manteniendo el comportamiento uniforme.

Salida estructurada

-o/--output-file <path> escribe el texto final del asistente en un archivo. --output-schema <file> valida el texto final como JSON frente a un archivo JSON Schema; una discrepancia se informa como un evento error con result.status error y salida

1. El archivo de esquema se comprueba antes de que el modelo se ejecute: un esquema ilegible, no analizable o que no es un objeto es un error de uso antes de que se envíe nada. Si tiene éxito, el esquema analizado también se envía al modelo como formato de salida json_schema de la ejecución, y el servidor reintenta una respuesta no válida hasta dos veces antes de que la validación final propia de la CLI actúe como respaldo. La salida final es el objeto estructurado serializado (una línea de JSON): es lo que llevan stdout, --output-file y result.text:

ax-code run --model qwen --output-schema ./answer.schema.json -- "Return a JSON object with a summary field"

Sesiones y reanudación

• -c/--continue — continúa la sesión más reciente.
• -s/--session <id> — continúa una sesión concreta por ID.
• --fork — bifurca la sesión antes de continuar (exige --continue o --session).
• --show-history — imprime el historial visible de la sesión al reanudar (exige --continue o --session).
• --attach <url> — se conecta a un servidor que ya está en marcha en lugar de iniciar uno; combínalo con --dir para apuntar a un directorio de proyecto en ese servidor. Un servidor protegido con AX_CODE_SERVER_PASSWORD toma --password (o la misma variable del lado del llamador); un entorno de ejecución gestionado toma su token de AX_CODE_RUNTIME_TOKEN.
• --runtime — se conecta al entorno de ejecución gestionado del directorio del proyecto (--dir o el cwd del llamador) iniciado con ax-code runtime start, resolviendo su URL y su token desde el registro privado del entorno de ejecución. Sin un entorno de ejecución en marcha, la ejecución falla antes de cualquier solicitud con el código de error attach y un mensaje que nombra el comando de inicio. --runtime y --attach son mutuamente excluyentes.

Recetas

Un solo uso

ax-code run --model qwen -- "Fix the failing test in src/parser.ts"

Acotar una ejecución con un tiempo de espera

ax-code run --timeout 120 --model qwen -- "Fix the failing test in src/parser.ts"

--timeout <seconds> aborta la ejecución en el servidor y sale con 124 (result.status es timeout) cuando la ejecución supera el límite, así que un agente atascado no puede mantener abierto un trabajo de CI de forma indefinida. El límite cubre toda la invocación: se arma antes de la primera llamada al servidor, así que incluso un host --attach inalcanzable o un arranque colgado termina a tiempo (en ese caso temprano la línea de resultado lleva un sessionID vacío).

Esperar a subagentes en segundo plano

ax-code run --await-background 300 --timeout 360 --model qwen -- \
  "Delegate the independent checks, then integrate their results"

--await-background <seconds> mantiene abierta esta invocación para los hijos task en segundo plano creados por su sesión y los turnos de seguimiento del padre disparados por sus resultados. Es opcional y está limitado a 3600 segundos. La respuesta final y el result.text JSON proceden del último turno del padre completado. Si los hijos o su seguimiento no se asientan dentro del límite de espera, la ejecución informa un error y sale con 1. --timeout sigue siendo el límite global. Las tareas programadas del proyecto se ejecutan en sesiones separadas y no forman parte de esta espera. Este comando de un solo uso no reclama programaciones de proyecto vencidas; un backend persistente es dueño de su despacho.

Analizar el flujo JSON

result=$(ax-code run --format json --model qwen -- "..." | tail -n 1)
echo "$result" | jq -r '.status'
echo "$result" | jq -r '.text'

La línea result es siempre la última, así que tail -n 1 la aísla incluso cuando el flujo termina antes.

Revisión de solo lectura

ax-code run --sandbox read-only --model qwen -- "Review this diff for bugs"

Salida JSON estructurada con un esquema

cat > answer.schema.json <<'JSON'
{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}
JSON
ax-code run --model qwen --output-schema answer.schema.json --output-file answer.json \
  -- "Return JSON with a one-sentence summary"

Reanudar una sesión

# Start a session and note the sessionID from the result line
ax-code run --format json --model qwen -- "Draft the outline" | tail -n 1

# Continue it
ax-code run --model qwen --session ses_... -- "Now write section 2"

Adjuntar un archivo

ax-code run --model qwen --file docs/spec.md -- "Summarize the attached spec"

Comandos legibles por máquina

ax-code run --format json emite un flujo de eventos delimitado por saltos de línea (consulta flujo JSON); es la única superficie de --json que transmite en flujo. Cualquier otro comando de solo lectura que lleve una marca --json sigue un contrato más estricto: si tiene éxito escribe exactamente un documento JSON en stdout, y si falla stdout queda vacío mientras un único documento {"error":{"code","message"}} va a stderr y el código de salida es 1.

Comandos con --json:

• ax-code session list --json
• ax-code models --json
• ax-code providers list --json
• ax-code agent list --json
• ax-code mcp list --json
• ax-code mcp auth list --json
• ax-code stats --json
• ax-code context --json
• ax-code memory status --json
• ax-code memory list --json
• ax-code task list --json / ax-code task show <taskID> --json
• ax-code schedule list --json / ax-code schedule show <taskID> --json
• ax-code runtime list --json / ax-code runtime status --json
• ax-code doctor --json
• ax-code risk <sessionID> --json
• ax-code wiki status --json
• ax-code workflow list --json / ax-code workflow status <runID> --json

ax-code runtime status imprime su documento JSON de forma incondicional: la marca --json se acepta por coherencia, pero la acción de estado siempre emite JSON en stdout.

Llamar a ax-code desde otro agente

Al envolver ax-code run desde un script, un paso de CI u otro agente:

• Usa --format json y lee la última línea: el registro result es siempre la línea final, incluso cuando el flujo termina antes.
• Captura sessionID de esa línea de resultado para cualquier turno de seguimiento; devuélvelo con --session.
• Nunca uses --continue desde llamadores concurrentes: reanuda la sesión más reciente, lo que entra en carrera cuando hay varios llamadores activos; pasa un id --session explícito en su lugar.
• Pasa un --model explícito para que la ejecución no dependa de un valor predeterminado configurado y mutable.
• Pasa siempre --timeout para que un agente atascado no pueda mantener abierto al llamador.
• Cierra stdin, o usa --prompt-file / --prompt-file -: el lector implícito de tubería se rinde tras una ventana de silencio de 300 ms y trunca una tubería lenta en silencio.
• Establece NO_COLOR=1, o confía en la detección de no TTY, para que una ejecución por tubería nunca emite códigos de escape ANSI.
• Ejecuta desde el directorio del proyecto: un directorio de inicio o un padre de varios repositorios se rechaza en modo no interactivo. Establece AX_CODE_ALLOW_BROAD_DIR=1 para anular esa protección.
• Los fallos de uso no imprimen nada en stdout (la ayuda y el error de una línea van a stderr), así que un comando mal escrito deja stdout vacío con salida 1. Bajo --format json el fallo de uso también se escribe como una línea error en stdout.
• Una señal que llega mientras el proceso aún se carga, antes de que el comando run esté activo, termina el proceso con salida 130 y sin salida; una vez que el comando está activo, SIGINT y SIGTERM producen siempre la única línea terminal result con estado cancelled.