Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

CLI sem interface (ax-code run)

Status: Ativo Escopo: estado atual Última revisão: 2026-09-22 Responsável: mantenedores do runtime do AX Code

ax-code run é o ponto de entrada de execução única e não interativo para agentes de programação com IA e para scripts. Ele envia um único prompt, imprime a resposta final do assistente e encerra — sem interface de terminal e sem prompts interativos. Este guia cobre a superfície de opções, o contrato de saída, os códigos de saída e receitas para copiar em scripts e em CI.

Invocar uma execução

Há quatro maneiras de fornecer o prompt. Elas se combinam nesta ordem: --prompt-file, depois -p/--prompt, depois a mensagem posicional e, por fim, a entrada padrão canalizada.

# 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

Quando a entrada padrão não é um TTY, o conteúdo dela é acrescentado ao prompt composto; portanto, ela é o prompt inteiro quando nada mais é fornecido. O leitor da entrada padrão espera uma janela de 300 ms de silêncio antes de desistir de um pipe aberto, então escreva o prompt logo e feche a entrada padrão — ou use --prompt-file para prompts grandes ou produzidos aos poucos. --prompt-file - lê o prompt da entrada padrão de forma explícita (erro de uso quando a entrada padrão é um TTY); o acréscimo implícito da entrada canalizada nunca ocorre uma segunda vez nessa invocação.

-f/--file anexa arquivos à mensagem e nunca substitui o prompt; pode ser repetido:

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

Um anexo precisa estar dentro do diretório do projeto: o servidor recusa anexos fora dele, quaisquer que sejam as regras de permissão, e a CLI os rejeita de imediato com um erro de uso. Copie o arquivo para o projeto ou passe o conteúdo com --prompt-file. --add-dir concede às ferramentas acesso a diretórios extras, mas não altera essa regra.

Os tipos MIME dos anexos são inferidos pela extensão: png, jpg, jpeg, gif e webp correspondem ao tipo image/*, e pdf a application/pdf, de modo que anexos binários chegam ao servidor com o tipo real, e não como text/plain. Qualquer outro arquivo — inclusive um sem extensão reconhecida — é enviado como text/plain, e um anexo de diretório é classificado como application/x-directory.

Direcionar a execução

Três flags direcionam uma execução sem alterar o texto do prompt. Todas existem apenas na forma longa e em kebab-case.

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

Acrescenta texto extra ao prompt de sistema, depois dos prompts de sistema do agente e do ambiente — acrescenta e nunca substitui o prompt de sistema integrado. As duas formas se excluem. A variante em arquivo é conveniente para instruções mais longas; exatamente uma quebra de linha final é removida, e um texto vazio (ou um arquivo ilegível) é um erro de uso, antes de qualquer envio.

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

--disallowed-tools a,b

Desativa ferramentas pelo ID durante a execução (separadas por vírgula e repetível). A opção passa pelos dois mecanismos do servidor: regras de negação na sessão criada cobrem execuções novas, e um mapa de ferramentas por requisição também cobre execuções retomadas de --session/--continue. Negar bash também nega o comando da ferramenta monitor, que roda pelo mesmo lançador de shell; uma chamada que esbarra em uma regra de negação falha como erro de ferramenta e conta como negação para o status de execução bloqueada. IDs desconhecidos não são um erro — os IDs de ferramentas MCP são dinâmicos — mas, no formato padrão, cada ID fora do conjunto de ferramentas integradas imprime um aviso em stderr (suprimido por --quiet).

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

--add-dir PATH

Concede ao agente acesso a um diretório adicional (repetível): uma regra de permissão allow de external_directory para <resolved-path>/* é adicionada às regras de permissão da sessão nova, cobrindo o diretório e tudo o que está abaixo dele. Cada caminho precisa existir e ser um diretório (resolvido em relação ao cwd de quem chama, como --file). A regra é aplicada quando a sessão é criada; portanto, sob --session/--continue ela não pode surtir efeito — a CLI imprime --add-dir applies only to new sessions em stderr e continua. Isso não muda o confinamento de --file: os anexos ainda precisam estar dentro do diretório do projeto. A regra cobre as ferramentas de arquivo (read, glob, grep, list, edit, write); um comando de shell que alcança o diretório por um caminho dinâmico ainda dispara o prompt de acesso a caminho, exclusivo do modo interativo, e uma execução sem interface o rejeita automaticamente. Prefira as ferramentas de arquivo ou passe o conteúdo do arquivo de forma explícita.

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

Escolher um modelo

Liste os IDs utilizáveis com ax-code models. Passe o valor resultante de provider/model para --model (-m):

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

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

Os nomes de família deepseek, glm e qwen resolvem para os padrões Flash correspondentes, então ax-code run --model qwen -- "..." funciona sem escrever um ID provider/model completo. Omitir --model usa o padrão configurado; o agente e o modelo efetivos são impressos em stderr como > Agent · model.

Formatos de saída

--format aceita default (o padrão), json, jsonl ou ndjson (jsonl e ndjson são aliases de json).

Padrão (texto)

O formato padrão imprime apenas o texto final do assistente em stdout. Todo o progresso, a atividade das ferramentas e os diagnósticos vão para stderr, começando por um cabeçalho > Agent · model · ses_... que inclui o ID da sessão, para que um chamador de vários turnos possa retomar com --session sem mudar para --format json (--quiet suprime o cabeçalho). As cores ANSI ficam desativadas quando stderr não é um TTY ou quando NO_COLOR está definido (com qualquer valor), de modo que uma execução canalizada nunca emite códigos de escape.

Fluxo JSON (--format json)

--format json imprime um fluxo de eventos JSON delimitado por quebras de linha (NDJSON) — um objeto JSON por linha, e não um único documento JSON. Os eventos incluem step_start, text, tool_use, reasoning (somente com --thinking), permission_denied, error e step_finish. O fluxo sempre termina com exatamente uma linha result:

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

status é completed, blocked ou error. usage traz apenas contagens de tokens — input, output, reasoning, cacheRead e cacheWrite — e é omitido por completo quando as contagens são desconhecidas; não há campo de custo. Quando uma execução falha antes do envio (flag incorreta, modelo desconhecido etc.), o formato de fluxo imprime uma linha antes de encerrar:

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

error.code é um destes valores:

Códigos de saída

Sandbox

--sandbox read-only|workspace-write|full-access seleciona o modo de isolamento (padrão full-access). Em execuções sem interface, os pedidos de permissão são rejeitados automaticamente e relatados como eventos permission_denied; assim, uma execução que precise de uma escrita não autorizada relata blocked e sai com o código 3. Isso também cobre subagentes: pedidos surgidos em sessões filhas criadas pela ferramenta task são rejeitados do mesmo modo, e os eventos permission_denied delas trazem o sessionID da sessão filha. Chamadas de ferramenta recusadas por uma regra de negação de permissão (por exemplo, a partir de --disallowed-tools) ou pelo sandbox somente leitura também contam como negações. As ferramentas interativas question e plan_exit ficam sempre desativadas em uma execução sem interface, inclusive em sessões retomadas. Use read-only somente quando nenhuma alteração for esperada; workspace-write mantém as escritas dentro do projeto.

Sob --attach, a flag também é enviada como política de isolamento por requisição em cada corpo de prompt; o servidor aplica o mais restrito entre o próprio modo e a política pedida, então só pode tornar o isolamento mais restrito. A mesma política por requisição é enviada para servidores de propriedade local, para manter o comportamento uniforme.

Saída estruturada

-o/--output-file <path> grava o texto final do assistente em um arquivo. --output-schema <file> valida o texto final como JSON em relação a um arquivo de JSON Schema; uma divergência é relatada como um evento error com result.status error e a execução termina com o código 1. O arquivo de esquema é pré-verificado antes de o modelo executar — um esquema ilegível, impossível de analisar ou que não seja um objeto é um erro de uso, antes de qualquer envio. Em caso de sucesso, o esquema analisado também é enviado ao modelo como o formato de saída json_schema da execução, e o servidor tenta outra vez uma resposta inválida até duas vezes, antes de a validação final da própria CLI servir de última barreira. A saída final é o objeto estruturado serializado (uma linha de JSON): é o que stdout, --output-file e result.text carregam:

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

Sessões e retomada

• -c/--continue — continua a sessão mais recente.
• -s/--session <id> — continua uma sessão específica pelo ID.
• --fork — faz um fork da sessão antes de continuar (exige --continue ou --session).
• --show-history — imprime o histórico visível da sessão ao retomar (exige --continue ou --session).
• --attach <url> — conecta-se a um servidor que já está em execução, em vez de iniciar um; combine com --dir para apontar um diretório de projeto nesse servidor. Um servidor protegido com AX_CODE_SERVER_PASSWORD recebe --password (ou a mesma variável do lado de quem chama); um runtime administrado obtém o token em AX_CODE_RUNTIME_TOKEN.
• --runtime — conecta-se ao runtime administrado do diretório do projeto (--dir ou o cwd de quem chama) iniciado com ax-code runtime start, resolvendo a URL e o token a partir do registro privado do runtime. Sem um runtime em execução, a chamada falha antes de qualquer requisição, com o código de erro attach e uma mensagem que indica o comando de início. --runtime e --attach se excluem mutuamente.

Receitas

Execução única

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

Limitar uma execução com tempo máximo

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

--timeout <seconds> aborta a execução no servidor e sai com 124 (result.status é timeout) quando ela ultrapassa o limite, para que um agente travado não mantenha um job de CI aberto por tempo indefinido. O limite cobre a invocação inteira — entra em vigor antes da primeira chamada ao servidor, então até um host --attach que engole a conexão, ou uma inicialização travada, termina no prazo (nesse caso inicial, a linha de resultado traz um sessionID vazio).

Esperar subagentes em segundo plano

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

--await-background <seconds> mantém esta invocação aberta para os filhos task em segundo plano criados pela sessão e para os turnos seguintes do processo pai disparados pelos resultados deles. A opção é explícita e tem teto de 3600 segundos. A resposta final e o JSON result.text vêm do último turno concluído do pai. Se os filhos ou o acompanhamento não se estabilizarem dentro do limite de espera, a execução relata um erro e sai com 1. --timeout continua sendo o limite geral. Tarefas agendadas do projeto rodam em sessões separadas e não fazem parte desta espera. Este comando de execução única não assume agendamentos do projeto que já estejam vencidos; um backend persistente é quem despacha essas tarefas.

Analisar o fluxo JSON

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

A linha result é sempre a última, então tail -n 1 a isola mesmo quando o fluxo termina antes do esperado.

Revisão somente leitura

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

Saída JSON estruturada com um 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"

Retomar uma sessão

# 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"

Anexar um arquivo

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

Comandos legíveis por máquina

ax-code run --format json emite um fluxo de eventos delimitado por quebras de linha (veja fluxo JSON); é a única superfície de --json que transmite em fluxo. Todo outro comando somente leitura que tenha uma flag --json segue um contrato mais estrito: em caso de sucesso, grava exatamente um documento JSON em stdout; em caso de falha, stdout permanece vazio, um único documento {"error":{"code","message"}} vai para stderr e o código de saída é 1.

Comandos com --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 o documento JSON sem condição — a flag --json é aceita por consistência, mas a ação de status sempre emite JSON em stdout.

Chamar o ax-code a partir de outro agente

Ao encapsular ax-code run em um script, em um passo de CI ou em outro agente:

• Use --format json e leia a última linha — o registro result é sempre a linha final, mesmo quando o fluxo termina antes do esperado.
• Capture sessionID dessa linha de resultado para qualquer turno seguinte; devolva esse valor com --session.
• Nunca use --continue a partir de chamadores simultâneos — ele retoma a sessão mais recente, o que cria uma condição de corrida quando vários chamadores estão ativos; passe um ID --session explícito.
• Passe um --model explícito, para que a execução não dependa de um padrão configurado que pode mudar.
• Sempre passe --timeout, para que um agente travado não deixe quem chama preso.
• Feche a entrada padrão, ou use --prompt-file / --prompt-file -: o leitor implícito de pipe desiste após uma janela de 300 ms de silêncio e trunca um pipe lento sem aviso.
• Defina NO_COLOR=1, ou confie na detecção de ausência de TTY, para que uma execução canalizada nunca emita códigos de escape ANSI.
• Execute a partir do diretório do projeto: um diretório pessoal ou um diretório pai de vários repositórios é recusado no modo não interativo. Defina AX_CODE_ALLOW_BROAD_DIR=1 para sobrepor essa proteção.
• Falhas de uso não imprimem nada em stdout (a ajuda e o erro de uma linha vão para stderr), então um comando digitado de forma incorreta deixa stdout vazio e sai com 1. Sob --format json, a falha de uso também é gravada como uma linha error em stdout.
• Um sinal que chega enquanto o processo ainda está carregando, antes de o comando run estar ativo, encerra o processo com saída 130 e sem texto; quando o comando já está ativo, SIGINT e SIGTERM sempre produzem a única linha final result com status cancelled.