Questa pagina è tradotta dalla documentazione inglese. Comandi, identificatori ed esempi restano invariati. Runtime 7.24.4 · SDK 2.6.7. Testo inglese

CLI headless (ax-code run)

Stato: attivo Ambito: stato attuale Ultima revisione: 2026-09-22 Responsabile: manutentori del runtime di AX Code

ax-code run è il punto di ingresso one-shot e non interattivo per agenti di programmazione con IA e per gli script. Invia un solo prompt, stampa la risposta finale dell’assistente ed esce: niente interfaccia del terminale, niente prompt interattivi. Questa guida copre la superficie delle opzioni, il contratto di output, i codici di uscita e ricette da copiare e incollare per script e CI.

Avviare un'esecuzione

Ci sono quattro modi per fornire il prompt. Si compongono in ordine: --prompt-file, poi -p/--prompt, poi il messaggio posizionale, poi lo stdin in pipe.

# 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 stdin non è un TTY, il suo contenuto viene accodato al prompt composto, quindi è l’intero prompt se non viene fornito altro. Il lettore di stdin attende una finestra di quiete di 300 ms prima di rinunciare a una pipe aperta, quindi scrivi il prompt subito e chiudi stdin, oppure usa --prompt-file per prompt grandi o prodotti lentamente. --prompt-file - legge il prompt da stdin in modo esplicito (errore di uso quando stdin è un TTY); l’accodamento implicito dello stdin in pipe non viene eseguito una seconda volta per quella invocazione.

-f/--file allega file al messaggio e non sostituisce mai il prompt; è ripetibile:

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

Un allegato deve trovarsi dentro la directory del progetto: il server rifiuta gli allegati esterni indipendentemente dalle regole di permesso, quindi la CLI li rifiuta subito con un errore di uso. Copia il file nel progetto oppure passa il suo contenuto con --prompt-file. --add-dir concede agli strumenti l’accesso a directory aggiuntive, ma non cambia questa regola.

I tipi mime degli allegati si deducono dall’estensione: png, jpg, jpeg, gif e webp corrispondono al proprio tipo image/* e pdf a application/pdf, così gli allegati binari raggiungono il server con il tipo reale invece di text/plain. Tutto il resto, incluso un file senza estensione riconosciuta, viene inviato come text/plain, e un allegato directory è classificato application/x-directory.

Guidare l'esecuzione

Tre flag guidano un’esecuzione senza cambiare il testo del prompt. Sono tutti solo in forma lunga e in kebab-case.

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

Accoda testo extra al prompt di sistema dopo i prompt di sistema dell’agente e dell’ambiente: accoda e non sostituisce mai il prompt di sistema integrato. Le due forme si escludono a vicenda. La variante da file è comoda per istruzioni più lunghe; viene rimosso esattamente un newline finale, e un testo vuoto (o un file illeggibile) è un errore di uso prima che venga inviato qualcosa.

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

--disallowed-tools a,b

Disabilita gli strumenti per id per l’esecuzione (separati da virgola, ripetibile). Si applica tramite entrambi i meccanismi del server: le regole di negazione sulla sessione creata coprono le nuove esecuzioni, e una mappa di strumenti per richiesta copre anche le esecuzioni riprese --session/--continue. Negare bash nega anche il comando dello strumento monitor, che passa dallo stesso launcher della shell; una chiamata che incontra una regola di negazione fallisce come errore di strumento e conta come negazione per lo stato di esecuzione bloccata. Gli id sconosciuti non sono un errore — gli id degli strumenti MCP sono dinamici — ma nel formato predefinito ogni id fuori dall’insieme di strumenti integrati stampa un avviso su stderr (soppresso da --quiet).

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

--add-dir PATH

Concede all’agente l’accesso a una directory aggiuntiva (ripetibile): una regola di consenso external_directory per <resolved-path>/* viene aggiunta alle regole di permesso della nuova sessione e copre la directory e tutto ciò che sta sotto. Ogni percorso deve esistere ed essere una directory (risolto rispetto alla cwd del chiamante, come --file). La regola si applica quando la sessione viene creata, quindi con --session/--continue non può avere effetto: la CLI stampa --add-dir applies only to new sessions su stderr e continua. Non cambia il contenimento di --file: gli allegati devono comunque stare dentro la directory del progetto. Copre gli strumenti sui file (read, glob, grep, list, edit, write); un comando di shell che entra nella directory tramite un percorso dinamico attiva ancora il prompt di accesso al percorso, solo interattivo, che un’esecuzione headless rifiuta automaticamente, quindi preferisci gli strumenti sui file oppure passa il contenuto del file in modo esplicito.

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

Scegliere un modello

Elenca gli ID utilizzabili con ax-code models. Passa il valore provider/model risultante a --model (-m):

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

ax-code models --json stampa un solo documento della forma {"models":[{"id":"provider/model","provider":"...","model":"...","connected":true}]}.

I nomi di famiglia deepseek, glm e qwen si risolvono nei rispettivi predefiniti Flash, quindi ax-code run --model qwen -- "..." funziona senza scrivere per esteso un ID provider/model completo. Omettere --model usa il predefinito configurato; l’agente e il modello effettivi vengono stampati su stderr come > Agent · model.

Formati di output

--format accetta default (il predefinito), json, jsonl o ndjson (jsonl e ndjson sono alias di json).

Predefinito (testo)

Il formato predefinito stampa su stdout solo il testo finale dell’assistente. Progresso, attività degli strumenti e diagnostica vanno su stderr, a partire da un’intestazione > Agent · model · ses_... che include l’id della sessione, così un chiamante su più turni può riprendere con --session senza passare a --format json (--quiet sopprime l’intestazione). I colori ANSI sono disattivati quando stderr non è un TTY o quando NO_COLOR è impostato (qualsiasi valore), quindi un’esecuzione in pipe non emette mai codici di escape.

Flusso JSON (--format json)

--format json stampa un flusso di eventi JSON delimitato da newline (NDJSON): un oggetto JSON per riga, non un unico documento JSON. Gli eventi includono step_start, text, tool_use, reasoning (solo con --thinking), permission_denied, error e step_finish. Il flusso termina sempre con esattamente una riga 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 o error. usage porta solo i conteggi dei token — input, output, reasoning, cacheRead, cacheWrite — e viene omesso del tutto quando i conteggi sono sconosciuti; non esiste un campo di costo. Quando un’esecuzione fallisce prima dell’invio (flag errato, modello sconosciuto e simili), il formato a flusso stampa una riga prima di uscire:

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

Il error.code è uno tra:

Codici di uscita

Isolamento sandbox

--sandbox read-only|workspace-write|full-access seleziona la modalità di isolamento (predefinita full-access). Nelle esecuzioni headless le richieste di permesso vengono rifiutate automaticamente e segnalate come eventi permission_denied, quindi un’esecuzione che ha bisogno di una scrittura non consentita segnala blocked ed esce con 3. Vale anche per i subagenti: le richieste sollevate nelle sessioni figlie create dallo strumento task vengono rifiutate allo stesso modo, e i loro eventi permission_denied portano il sessionID figlio. Anche le chiamate di strumento rifiutate da una regola di negazione dei permessi (per esempio da --disallowed-tools) o dalla sandbox di sola lettura contano come negazioni. Gli strumenti interattivi question e plan_exit sono sempre disabilitati in un’esecuzione headless, anche sulle sessioni riprese. Usa read-only solo quando non è attesa alcuna mutazione; workspace-write mantiene le scritture dentro il progetto.

Con --attach il flag viene anche inviato come policy di isolamento per richiesta in ogni corpo di prompt; il server applica la più restrittiva tra la propria modalità e la policy richiesta, quindi può solo restringere. La stessa policy per richiesta viene inviata per i server di proprietà locale, mantenendo il comportamento uniforme.

Output strutturato

-o/--output-file <path> scrive il testo finale dell’assistente in un file. --output-schema <file> valida il testo finale come JSON rispetto a un file JSON Schema; una mancata corrispondenza viene segnalata come evento error con result.status error e uscita con codice 1. Il file di schema viene controllato in anticipo prima che il modello venga eseguito: uno schema illeggibile, non analizzabile o non oggetto è un errore di uso prima che venga inviato qualcosa. In caso di successo lo schema analizzato viene anche inviato al modello come formato di output json_schema dell’esecuzione, e il server ritenta una risposta non valida fino a due volte prima che la validazione finale della CLI agisca da rete di sicurezza. L’output finale è l’oggetto strutturato serializzato (una riga di JSON): è ciò che portano stdout, --output-file e result.text:

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

Sessioni e ripresa

• -c/--continue — continua la sessione più recente.
• -s/--session <id> — continua una sessione specifica per ID.
• --fork — biforca la sessione prima di continuare (richiede --continue o --session).
• --show-history — stampa la cronologia visibile della sessione in fase di ripresa (richiede --continue o --session).
• --attach <url> — si collega a un server già in esecuzione invece di avviarne uno; combinalo con --dir per puntare a una directory di progetto su quel server. Un server protetto con AX_CODE_SERVER_PASSWORD accetta --password (o la stessa variabile dal lato del chiamante); un runtime gestito prende il proprio token da AX_CODE_RUNTIME_TOKEN.
• --runtime — si collega al runtime gestito della directory di progetto (--dir o la cwd del chiamante) avviato con ax-code runtime start, risolvendo URL e token dal record privato del runtime. Senza un runtime in esecuzione, l’esecuzione fallisce prima di qualsiasi richiesta con codice di errore attach e un messaggio che nomina il comando di avvio. --runtime e --attach si escludono a vicenda.

Ricette

Esecuzione singola

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

Limita un'esecuzione con un timeout

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

--timeout <seconds> interrompe l’esecuzione sul server ed esce con 124 (result.status è timeout) quando l’esecuzione supera il limite, così un agente bloccato non può tenere aperto un job CI all’infinito. Il limite copre l’intera invocazione: viene armato prima della prima chiamata al server, quindi anche un host --attach irraggiungibile o un avvio appeso termina in tempo (in quel caso precoce la riga di risultato porta un sessionID vuoto).

Attendi i subagenti in background

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

--await-background <seconds> mantiene aperta questa invocazione per i figli task in background creati dalla sua sessione e per i turni di seguito del genitore innescati dai loro risultati. È facoltativo e ha un tetto di 3600 secondi. La risposta finale e il JSON result.text provengono dall’ultimo turno genitore completato. Se i figli o il loro seguito non si stabilizzano entro il limite di attesa, l’esecuzione segnala un errore ed esce con 1. --timeout resta il limite complessivo. Le attività pianificate del progetto girano in sessioni separate e non fanno parte di questa attesa. Questo comando one-shot non rivendica le pianificazioni di progetto scadute; un backend persistente ne possiede l’invio.

Analizza il flusso JSON

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

La riga result è sempre l’ultima, quindi tail -n 1 la isola anche quando il flusso termina in anticipo.

Revisione in sola lettura

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

Output JSON strutturato con uno schema

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"

Riprendi una sessione

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

Allega un file

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

Comandi leggibili dalla macchina

ax-code run --format json emette un flusso di eventi delimitato da newline (vedi flusso JSON); è l’unica superficie --json che trasmette in flusso. Ogni altro comando di sola lettura che porta un flag --json segue un contratto più stretto: in caso di successo scrive esattamente un documento JSON su stdout e, in caso di fallimento, stdout resta vuoto mentre un solo documento {"error":{"code","message"}} va su stderr e il codice di uscita è 1.

Comandi 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 stampa il proprio documento JSON in modo incondizionato: il flag --json è accettato per coerenza, ma l’azione di stato emette sempre JSON su stdout.

Chiamare ax-code da un altro agente

Quando avvolgi ax-code run da uno script, da un passo CI o da un altro agente:

• Usa --format json e leggi l’ultima riga: il record result è sempre la riga finale, anche quando il flusso termina in anticipo.
• Cattura sessionID da quella riga di risultato per ogni turno di seguito; ripassalo con --session.
• Non usare mai --continue da chiamanti concorrenti: riprende la sessione più recente, e questo crea una corsa quando più chiamanti sono attivi; passa invece un id --session esplicito.
• Passa un --model esplicito così l’esecuzione non dipende da un predefinito configurato mutabile.
• Passa sempre --timeout così un agente bloccato non può tenere aperto il chiamante.
• Chiudi stdin, oppure usa --prompt-file / --prompt-file -: il lettore implicito della pipe rinuncia dopo una finestra di quiete di 300 ms e tronca in silenzio una pipe lenta.
• Imposta NO_COLOR=1, oppure affidati al rilevamento di non-TTY, così un’esecuzione in pipe non emette mai codici di escape ANSI.
• Esegui dalla directory del progetto: una directory home o una directory genitore con più repository viene rifiutata in modalità non interattiva. Imposta AX_CODE_ALLOW_BROAD_DIR=1 per scavalcare quella protezione.
• I fallimenti di uso non stampano nulla su stdout (l’aiuto e l’errore di una riga vanno su stderr), quindi un comando digitato male lascia stdout vuoto con uscita 1. Con --format json il fallimento di uso viene anche scritto come una riga error su stdout.
• Un segnale che arriva mentre il processo è ancora in caricamento, prima che il comando run sia attivo, termina il processo con uscita 130 e senza output; una volta che il comando è attivo, SIGINT e SIGTERM producono sempre l’unica riga terminale result con stato cancelled.