Cette page est traduite de la documentation anglaise. Les commandes, identifiants et exemples sont inchangés. Runtime 7.24.4 · SDK 2.6.7. Source anglaise

CLI sans interface (ax-code run)

Statut : Actif Portée : état actuel Dernière revue : 2026-09-22 Responsable : mainteneurs du runtime AX Code

ax-code run est le point d’entrée unique et non interactif pour les agents de codage par IA et les scripts. Il soumet une seule invite, affiche la réponse finale de l’assistant et se termine — pas d’interface de terminal, pas d’invites interactives. Ce guide couvre la surface des options, le contrat de sortie, les codes de sortie et des recettes à copier pour les scripts et CI.

Invoquer une exécution

Il y a quatre façons de fournir l’invite. Elles se composent dans l’ordre : --prompt-file, puis -p/--prompt, puis le message positionnel, puis stdin redirigé.

# 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

Lorsque stdin n’est pas un TTY, son contenu est ajouté à l’invite composée, donc c’est l’invite entière lorsqu’aucune autre source n’est fournie. Le lecteur de stdin attend une fenêtre calme de 300 ms avant d’abandonner un tube ouvert, donc écrivez l’invite rapidement et fermez stdin — ou utilisez --prompt-file pour les invites volumineuses ou produites lentement. --prompt-file - lit l’invite depuis stdin explicitement (erreur d’usage lorsque stdin est un TTY) ; l’ajout implicite de stdin redirigé ne s’exécute jamais une seconde fois pour cette invocation.

-f/--file joint des fichiers au message et ne remplace jamais l’invite ; il est répétable :

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

Une pièce jointe doit se trouver dans le répertoire du projet : le serveur refuse les pièces jointes hors de celui-ci, quelles que soient les règles de permission, donc le CLI les rejette d’emblée avec une erreur d’usage. Copiez le fichier dans le projet ou passez son contenu avec --prompt-file. --add-dir accorde aux outils l’accès à des répertoires supplémentaires, mais ne change pas cette règle.

Les types MIME des pièces jointes sont déduits de l’extension : png, jpg, jpeg, gif et webp correspondent à leur type image/*, et pdf à application/pdf, afin que les pièces jointes binaires atteignent le serveur avec leur type réel au lieu de text/plain. Tout le reste — y compris un fichier sans extension reconnue — est envoyé comme text/plain, et une pièce jointe de répertoire est classée application/x-directory.

Orienter l'exécution

Trois drapeaux orientent une exécution sans changer le texte de l’invite. Tous sont seulement en forme longue et en casse kebab.

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

Ajoute du texte supplémentaire à l’invite système après les invites système de l’agent et de l’environnement — il ajoute et ne remplace jamais l’invite système intégrée. Les deux formes sont mutuellement exclusives. Une variante fichier est pratique pour des instructions plus longues ; exactement un saut de ligne final est retiré, et un texte vide (ou un fichier illisible) est une erreur d’usage avant toute soumission.

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

--disallowed-tools a,b

Désactive des outils par identifiant pour l’exécution (séparés par des virgules, répétable). Il est appliqué par les deux mécanismes du serveur : les règles de refus sur la session créée couvrent les nouvelles exécutions, et une carte d’outils par requête couvre aussi les exécutions reprises --session/--continue. Refuser bash refuse aussi la commande de l’outil monitor, qui s’exécute par le même lanceur shell ; un appel qui touche une règle de refus échoue comme erreur d’outil et compte comme un refus pour l’état d’exécution bloquée. Les identifiants inconnus ne sont pas une erreur — les identifiants d’outils MCP sont dynamiques — mais, sous le format par défaut, chaque identifiant hors de l’ensemble d’outils intégré affiche un avertissement sur stderr (supprimé par --quiet).

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

--add-dir PATH

Accorde à l’agent l’accès à un répertoire supplémentaire (répétable) : une règle d’autorisation external_directory pour <resolved-path>/* est ajoutée aux règles de permission de la nouvelle session, couvrant le répertoire et tout ce qui se trouve dessous. Chaque chemin doit exister et être un répertoire (résolu par rapport au répertoire courant de l’appelant, comme --file). La règle est appliquée à la création de la session, donc sous --session/--continue elle ne peut pas prendre effet — le CLI affiche --add-dir applies only to new sessions sur stderr et continue. Cela ne change pas le confinement --file : les pièces jointes doivent encore se trouver dans le répertoire du projet. Cela couvre les outils de fichiers (read, glob, grep, list, edit, write) ; une commande shell qui atteint le répertoire par un chemin dynamique déclenche encore l’invite d’accès au chemin, seulement interactive, qu’une exécution sans interface rejette automatiquement. Préférez donc les outils de fichiers ou passez le contenu du fichier explicitement.

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

Choisir un modèle

Listez les identifiants utilisables avec ax-code models. Passez la valeur provider/model résultante à --model (-m) :

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

ax-code models --json affiche un seul document de la forme {"models":[{"id":"provider/model","provider":"...","model":"...","connected":true}]}.

Les noms de famille deepseek, glm et qwen se résolvent vers leurs défauts Flash, donc ax-code run --model qwen -- "..." fonctionne sans épeler un identifiant provider/model complet. Omettre --model utilise le défaut configuré ; l’agent et le modèle effectifs sont affichés sur stderr comme > Agent · model.

Formats de sortie

--format accepte default (le défaut), json, jsonl ou ndjson (jsonl et ndjson sont des alias de json).

Défaut (texte)

Le format par défaut n’affiche que le texte final de l’assistant sur stdout. Toute la progression, l’activité des outils et les diagnostics vont sur stderr, en commençant par un en-tête > Agent · model · ses_... qui inclut l’identifiant de session, afin qu’un appelant multi-tours puisse reprendre avec --session sans passer à --format json (--quiet supprime l’en-tête). Les couleurs ANSI sont désactivées lorsque stderr n’est pas un TTY ou lorsque NO_COLOR est défini (toute valeur), donc une exécution redirigée n’émet jamais de codes d’échappement.

Flux JSON (--format json)

--format json affiche un flux d’événements JSON délimité par des sauts de ligne (NDJSON) — un objet JSON par ligne, pas un seul document JSON. Les événements comprennent step_start, text, tool_use, reasoning (seulement avec --thinking), permission_denied, error et step_finish. Le flux se termine toujours par exactement une ligne result :

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

status vaut completed, blocked ou error. usage ne porte que des comptes de jetons — input, output, reasoning, cacheRead, cacheWrite — et est entièrement omis lorsque les comptes sont inconnus ; il n’y a pas de champ de coût. Lorsqu’une exécution échoue avant la soumission (mauvais drapeau, modèle inconnu, etc.), le format de flux affiche une ligne avant de se terminer :

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

Le error.code est l’un des suivants :

Codes de sortie

Bac à sable

--sandbox read-only|workspace-write|full-access sélectionne le mode d’isolation (défaut full-access). Dans les exécutions sans interface, les demandes de permission sont rejetées automatiquement et signalées comme événements permission_denied, donc une exécution qui a besoin d’une écriture non autorisée signale blocked et se termine avec le code 3. Cela couvre aussi les sous-agents : les demandes levées dans les sessions enfants créées par l’outil task sont rejetées de la même façon, et leurs événements permission_denied portent le sessionID enfant. Les appels d’outils refusés par une règle de refus de permission (par exemple depuis --disallowed-tools) ou par le bac à sable en lecture seule comptent aussi comme des refus. Les outils interactifs question et plan_exit sont toujours désactivés dans une exécution sans interface, y compris sur les sessions reprises. Utilisez read-only seulement lorsqu’aucune mutation n’est attendue ; workspace-write garde les écritures dans le projet.

Sous --attach, le drapeau est aussi envoyé comme politique d’isolation par requête dans chaque corps d’invite ; le serveur applique le plus strict entre son propre mode et la politique demandée, donc il ne peut que resserrer. La même politique par requête est envoyée pour les serveurs possédés localement, ce qui garde le comportement uniforme.

Sortie structurée

-o/--output-file <path> écrit le texte final de l’assistant dans un fichier. --output-schema <file> valide le texte final comme JSON contre un fichier JSON Schema ; une non-concordance est signalée comme un événement error avec result.status error et une sortie

1. Le fichier de schéma est précontrôlé avant l’exécution du modèle — un schéma illisible, non analysable ou qui n’est pas un objet est une erreur d’usage avant toute soumission. En cas de succès, le schéma analysé est aussi envoyé au modèle comme format de sortie json_schema de l’exécution, et le serveur réessaie une réponse invalide jusqu’à deux fois avant que la validation finale propre du CLI serve de filet. La sortie finale est l’objet structuré sérialisé (une ligne de JSON) : c’est ce que portent stdout, --output-file et result.text :

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

Sessions et reprise

• -c/--continue — poursuivre la session la plus récente.
• -s/--session <id> — poursuivre une session précise par identifiant.
• --fork — fourcher la session avant de poursuivre (exige --continue ou --session).
• --show-history — afficher l’historique de session visible lors de la reprise (exige --continue ou --session).
• --attach <url> — s’attacher à un serveur déjà en cours au lieu d’en démarrer un ; combinez avec --dir pour cibler un répertoire de projet sur ce serveur. Un serveur protégé par AX_CODE_SERVER_PASSWORD prend --password (ou la même variable côté appelant) ; un runtime géré prend son jeton depuis AX_CODE_RUNTIME_TOKEN.
• --runtime — s’attacher au runtime géré du répertoire de projet (--dir ou le répertoire courant de l’appelant) démarré avec ax-code runtime start, en résolvant son URL et son jeton depuis l’enregistrement privé du runtime. Sans runtime en cours, l’exécution échoue avant toute requête avec le code d’erreur attach et un message qui nomme la commande de démarrage. --runtime et --attach sont mutuellement exclusifs.

Recettes

Exécution unique

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

Borner une exécution avec un délai

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

--timeout <seconds> abandonne l’exécution sur le serveur et se termine avec le code 124 (result.status vaut timeout) lorsque l’exécution dépasse la borne, afin qu’un agent bloqué ne puisse pas tenir un travail CI ouvert indéfiniment. La borne couvre toute l’invocation — elle est armée avant le premier appel serveur, donc même un hôte --attach injoignable ou un démarrage figé se termine à temps (dans ce cas précoce, la ligne de résultat porte un sessionID vide).

Attendre les sous-agents en arrière-plan

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

--await-background <seconds> garde cette invocation ouverte pour les enfants task en arrière-plan créés par sa session et les tours de suivi du parent déclenchés par leurs résultats. C’est une activation explicite, plafonnée à 3600 secondes. La réponse finale et le JSON result.text viennent du dernier tour parent achevé. Si les enfants ou leur suivi ne se stabilisent pas dans la borne d’attente, l’exécution signale une erreur et se termine avec le code 1. --timeout reste la borne globale. Les tâches planifiées du projet s’exécutent dans des sessions distinctes et ne font pas partie de cette attente. Cette commande unique ne réclame pas les planifications de projet échues ; un moteur persistant possède leur distribution.

Analyser le flux JSON

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

La ligne result est toujours la dernière, donc tail -n 1 l’isole même lorsque le flux se termine tôt.

Revue en lecture seule

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

Sortie JSON structurée avec un schéma

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"

Reprendre une session

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

Joindre un fichier

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

Commandes lisibles par machine

ax-code run --format json émet un flux d’événements délimité par des sauts de ligne (voir Flux JSON) ; c’est la seule surface --json qui diffuse. Chaque autre commande en lecture seule qui porte un drapeau --json suit un contrat plus strict : en cas de succès elle écrit exactement un document JSON sur stdout, et en cas d’échec stdout reste vide tandis qu’un seul document {"error":{"code","message"}} va sur stderr et le code de sortie est 1.

Commandes avec --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 affiche son document JSON sans condition — le drapeau --json est accepté pour la cohérence, mais l’action d’état émet toujours du JSON sur stdout.

Appeler ax-code depuis un autre agent

Lorsque vous enveloppez ax-code run depuis un script, une étape CI ou un autre agent :

• Utilisez --format json et lisez la dernière ligne — l’enregistrement result est toujours la ligne finale, même lorsque le flux se termine tôt.
• Capturez sessionID depuis cette ligne de résultat pour tout tour de suivi ; renvoyez-le avec --session.
• N’utilisez jamais --continue depuis des appelants concurrents — il reprend la session la plus récente, ce qui entre en course lorsque plusieurs appelants sont actifs ; passez plutôt un identifiant --session explicite.
• Passez un --model explicite afin que l’exécution ne dépende pas d’un défaut configuré mutable.
• Passez toujours --timeout afin qu’un agent bloqué ne puisse pas tenir l’appelant ouvert.
• Fermez stdin, ou utilisez --prompt-file / --prompt-file - : le lecteur de tube implicite abandonne après une fenêtre calme de 300 ms et tronque un tube lent en silence.
• Définissez NO_COLOR=1, ou fiez-vous à la détection hors TTY, afin qu’une exécution redirigée n’émette jamais de codes d’échappement ANSI.
• Exécutez depuis le répertoire du projet : un répertoire personnel ou parent multi-dépôts est refusé en mode non interactif. Définissez AX_CODE_ALLOW_BROAD_DIR=1 pour outrepasser cette garde.
• Les échecs d’usage n’affichent rien sur stdout (l’aide et l’erreur d’une ligne vont sur stderr), donc une commande mal saisie laisse stdout vide avec le code de sortie 1. Sous --format json, l’échec d’usage est aussi écrit comme une ligne error sur stdout.
• Un signal qui arrive pendant que le processus charge encore, avant que la commande run soit active, termine le processus avec le code 130 et sans sortie ; une fois la commande active, SIGINT et SIGTERM produisent toujours la seule ligne terminale result avec l’état cancelled.