Exécution non interactive (codex exec) : scripts et CI/CD

📚 Navigation dans la série : Le chapitre précédent [27 · Automatisation et intégration continue (CI/CD)] présentait le paramétrage global des flux de CI/CD et des tâches planifiées. Ce chapitre se focalise sur la commande d'exécution sous-jacente : la commande codex exec permet d'exécuter des tâches en mode non interactif, de séparer proprement les flux de logs et de résultats, et d'intégrer le retour JSON dans vos scripts d'administration locaux. Le chapitre suivant [29 · Intégrations Slack, Linear et SDK] étendra cette automatisation aux plateformes de communication et aux outils de gestion de tickets.

Abordons la commande que vous utiliserez pour toute intégration de script : codex exec.

Au chapitre 8 présentant l'interface en ligne de commande (CLI), nous avions comparé cette fonction à une « livraison à domicile » : vous soumettez une consigne (votre commande), l'assistant réalise le traitement en arrière-plan et vous livre le résultat final directement dans le terminal, sans exiger votre présence. Ce chapitre ouvre les coulisses pour détailler la structuration, l'encapsulation et l'intégration de cette commande dans vos scripts d'automatisation.

Pourquoi dédier un chapitre à cette commande ? L'interface utilisateur classique (accessible en saisissant codex dans votre terminal) repose sur un postulat simple : la présence continue d'un opérateur humain devant l'écran pour valider les étapes, approuver les modifications de fichiers et inspecter les rendus de code. Or, si vous souhaitez lancer une revue de code automatique chaque matin, corriger un build cassé au milieu de la nuit, ou analyser une panne à partir d'un journal d'erreur, aucun opérateur n'est présent. L'interface interactive bloquerait le traitement en attendant une validation. La commande codex exec est conçue pour ces scénarios autonomes.

Maîtriser la commande codex exec est la clé pour passer de l'usage interactif de Codex à son intégration comme un composant automatisé de votre chaîne de développement.

À la fin de ce chapitre, vous aurez en main :

• La différence de fonctionnement entre l'interface interactive et le mode non interactif codex exec.
• Le principe de séparation des flux : les logs de progression sont envoyés sur stderr, le résultat final sur stdout, facilitant la redirection dans les pipelines.
• L'utilisation de l'option --json pour générer un flux d'événements structuré et de -o / --output-last-message pour isoler le rapport de sortie.
• La gestion de la sécurité : le mode non interactif s'exécute par défaut en lecture seule, exigeant l'activation explicite de sandbox: workspace-write pour modifier les fichiers.
• La redirection des entrées standard (stdin) selon deux approches (données comme contexte ou consigne complète).
• Un script minimal prêt à l'emploi pour enchaîner les traitements en boucle sur plusieurs fichiers.

⚠️ Note concernant les options : Les arguments et comportements décrits ci-dessous correspondent aux spécifications de la documentation officielle de Codex pour l'exécution non interactive. Les noms de modèles d'IA peuvent évoluer selon les mises à jour de la plateforme.

---

01 Le besoin d'une exécution non interactive

En résumé : la commande codex exec répond aux besoins des traitements sans opérateur humain (scripts d'administration, tâches planifiées, conteneurs de CI/CD) où les résultats doivent être traités de manière programmatique par d'autres utilitaires.

Jusqu'ici, nous avons principalement utilisé le mode interactif : ouverture de la console TUI (Terminal User Interface), saisie d'instructions et validation manuelle des modifications. Ce mode couvre la majorité des besoins du quotidien, pour peu que vous soyez devant votre poste.

Ce mode interactif est inutilisable ou inefficace dans trois situations :

1. Les tâches répétitives à grand volume : par exemple, générer une note de version (release note) pour chacun des dix derniers commits. Saisir ces instructions manuellement dans le chat pour chaque commit représente une perte de temps. 2. Les environnements sans terminal interactif : les serveurs d'intégration continue (CI), les machines virtuelles cloud ou les conteneurs Docker ne disposent pas de console interactive pour afficher le TUI de Codex. 3. Le chaînage de commandes (pipelines) : par exemple, extraire une trace d'erreur d'un fichier de log, la faire analyser par Codex sous forme de tableau Markdown, puis transmettre ce tableau à un utilitaire de notification pour publication. Le résultat de Codex doit être brut et exempt d'éléments d'interface pour être lu par le programme suivant.

Analogie : Le distributeur automatique et le comptoir de vente. L'interface interactive s'apparente à un comptoir de vente avec un vendeur : vous échangez sur votre besoin, le vendeur prépare la commande, vous demande des précisions en cours de route et vous remet le produit. La commande codex exec s'apparente à un distributeur automatique : vous insérez votre jeton de consigne, la machine s'active en interne et livre le produit fini dans le réceptacle de sortie (stdout), sans interaction intermédiaire. Ce fonctionnement autonome est indispensable pour paralléliser ou automatiser des tâches à grande échelle.

Exemples d'utilisation réels :

• Analyser une erreur de build de CI en lui transmettant le flux de logs, pour proposer un correctif de façon autonome.
• Générer un fichier récapitulatif des modifications (release notes) à partir des derniers commits Git de la journée.
• Transmettre une trace de crash réseau pour générer une alerte contenant la cause probable et les étapes de diagnostic.

💡 En résumé : Le mode non interactif codex exec supprime la console graphique et les invites de validation. Il permet d'automatiser des traitements répétitifs et de transmettre les résultats à d'autres programmes.

---

02 Structure de la commande codex exec

La syntaxe minimale consiste à saisir l'instruction de la tâche à la suite de la commande codex exec :

codex exec "总结这个仓库的结构，列出最该警惕的 5 个地方"

Codex analyse le répertoire courant, exécute la consigne, affiche son rapport dans la console et ferme le processus, sans ouvrir l'interface TUI.

Analogie : L'envoi d'un ordre par courrier. Le mode interactif s'apparente à une conversation téléphonique où vous pouvez préciser vos consignes au fil des réponses. La commande codex exec équivaut à envoyer une lettre contenant l'intégralité du cahier des charges : le destinataire réalise la tâche en autonomie d'après vos écrits et vous renvoie le rapport final. Votre message initial doit donc être le plus précis possible.

Quelques raccourcis et options utiles :

# L'alias codex e est équivalent à codex exec
codex e "Explique le rôle de ce projet de code"

# Renseigner un modèle d'IA spécifique (ex: gpt-5.5)
codex exec -m gpt-5.5 "Recherche les failles de sécurité dans le code actuel"

# Exécuter la tâche sans archiver la session dans l'historique (mode éphémère)
codex exec --ephemeral "Analyse rapide de ce répertoire et propose des pistes d'amélioration"

Différence fondamentale avec le mode interactif : aucun arrêt sur invite de validation n'intervient en cours de traitement. Le niveau de modification possible sur vos fichiers dépend de la configuration de sécurité (politique de bac à sable) déclarée lors de l'appel (section 04).

⚠️ Contrôle de dépôt Git : Par défaut, Codex exige que la commande soit lancée dans un répertoire de projet géré par Git afin de pouvoir annuler les écritures en cas d'erreur. Vous pouvez contourner ce contrôle en ajoutant l'option --skip-git-repo-check, à réserver aux environnements isolés et sécurisés.

💡 En résumé : La commande codex exec (alias codex e) exécute une consigne en ligne de commande et ferme la session. Elle n'interrompt pas son exécution pour demander de validation. Le répertoire cible doit être sous Git par sécurité.

---

03 Séparation des flux de sortie : stdout et stderr

Cette section présente le principe de routage des données de codex exec dans votre console.

Pour permettre l'intégration de la commande dans des scripts, Codex sépare ses sorties : les informations de progression du traitement (logs) sont dirigées vers le flux d'erreur standard (stderr), tandis que le rapport ou code final généré est dirigé vers la sortie standard (stdout).

Analogie : L'accès aux vestiaires et à la salle de réunion d'un atelier. Les bruits de chantier, le déplacement des outils et les rapports d'étapes (stderr) sont confinés dans la zone technique. Seul le livrable final validé (stdout) est présenté dans la salle de réunion pour livraison. Cette séparation évite que les bruits de chantier ne polluent la livraison.

Cette organisation permet d'utiliser les opérateurs de redirection standards de votre console (comme le pipe | ou l'écriture de fichier >) qui ne capturent que la sortie standard (stdout) :

codex exec "Génère une note de synthèse des 10 derniers commits" | tee release-notes.md

Comportement attendu : Les messages de progression de Codex s'affichent à l'écran (stderr), mais le fichier release-notes.md ne contient que le texte propre de la note de synthèse (stdout), sans aucune ligne de log de l'outil.

Exemples de redirections selon le besoin :

Objectif	Syntaxe de commande	Comportement
Enregistrer uniquement le résultat final	codex exec "..." > result.md	Le résultat est écrit dans le fichier, les logs de progression restent affichés à l'écran.
Enregistrer et afficher le résultat	codex exec "..." | tee result.md	Le résultat est copié dans le fichier et s'affiche dans la console.
Transmettre le résultat à un autre outil	codex exec "..." | pbcopy	Le résultat final est copié dans le presse-papiers de la machine.
Séparer les logs et le résultat final	codex exec "..." > result.md 2> debug.log	Le résultat final est écrit dans result.md ; les logs de progression sont écrits dans debug.log.

Attention lors de la rédaction de vos scripts à ne pas rediriger globalement les flux avec la syntaxe 2>&1, sous prétexte de polluer vos fichiers de résultats avec les messages d'état de Codex.

💡 En résumé : Codex sépare ses sorties : les logs de progression vont sur stderr, le résultat final sur stdout. Cela vous permet de capturer un résultat propre via des redirections (>) sans pollution de logs.

---

04 Gestion de la sécurité et politique de bac à sable

En mode non interactif, l'absence d'opérateur humain pour valider les actions de modification exige un encadrement strict des droits d'écriture.

Par défaut, la commande codex exec s'exécute sous la politique de bac à sable la plus restrictive : la lecture seule (read-only). Codex peut lire et analyser votre code, mais ne peut modifier aucun fichier physique ni exécuter de commande système modifiant l'état de votre répertoire.

Analogie : Le technicien d'inspection. Par défaut, l'inspecteur dispose d'un droit d'accès visuel (lecture seule) pour auditer les installations et rédiger un rapport. Si des réparations sont requises, vous devez lui signer une autorisation spécifique lui accordant l'accès aux outils de modification (mode workspace-write).

Le choix de la politique de bac à sable s'effectue via l'option --sandbox (ou -s) :

Option de bac à sable	Périmètre d'action	Cas d'usage type
read-only (par défaut)	Lecture seule. Interdiction d'écriture de fichiers et d'exécution de commandes.	Revue de code, génération de documentation, audit de sécurité.
workspace-write	Droits d'écriture limités au répertoire du projet.	Correction automatique de bugs, formatage de fichiers de code.
danger-full-access	Droits d'accès globaux à la machine hôte.	À réserver exclusivement aux conteneurs de CI/CD isolés.

Exemples de commandes :

# Analyse de code en lecture seule (sécurisé par défaut)
codex exec "Analyse le code et liste les risques de sécurité"

# Autoriser Codex à corriger les fichiers du répertoire projet
codex exec --sandbox workspace-write "Corrige les erreurs de build du projet"

Recommandations de sécurité pour vos scripts :

• N'utilisez pas l'ancien argument --full-auto (désormais déprécié) ; utilisez explicitement --sandbox workspace-write pour accorder les droits d'écriture sur le projet.
• Ne lancez jamais de tâche avec l'option danger-full-access sur votre machine de développement personnelle ; limitez cet usage aux conteneurs de CI/CD jetables.
• Pour garantir un comportement reproductible sur vos serveurs de build, ajoutez les options --ignore-user-config (ignore la configuration de l'utilisateur hôte) et --ignore-rules (ignore les fichiers de règles locaux).

💡 En résumé : Par sécurité, codex exec s'exécute en lecture seule (read-only) par défaut. Pour autoriser l'écriture sur votre projet, déclarez explicitement l'argument --sandbox workspace-write.

---

05 Automatiser le traitement des retours : JSON et sorties de fichiers

Pour analyser les résultats de Codex de façon programmatique (dans un script Python ou Bash), le format texte brut est difficile à parser. Codex propose deux options pour structurer et exporter les retours.

Le flux d'événements JSON avec --json

L'ajout de l'option --json (ou --experimental-json) transforme la sortie standard (stdout) en un flux de lignes JSON (JSONL - JSON Lines). Chaque ligne renvoie un objet JSON décrivant un événement de traitement.

Analogie : La feuille d'enregistrement d'activité. Au lieu de lire un résumé textuel rédigé en fin de journée, vous lisez un tableau de bord électronique listant chaque action avec son heure et son statut (« Démarrage du script à 8h01 », « Commande Bash exécutée à 8h02 », « Token consommés à 8h03 »). Chaque ligne est structurée pour être lue par un programme.

codex exec --json "总结这个仓库 the structure" | jq

Chaque ligne JSON correspond à un type d'événement, par exemple thread.started (session démarrée), turn.started / turn.completed (début/fin de boucle de réflexion), item.completed (action de l'agent validée) ou error (erreur système) :

{"type":"thread.started","thread_id":"0199a213-81c0-7800-8aa1-bbab2a035a53"}
{"type":"turn.started"}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"Le projet contient trois dossiers principaux."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"output_tokens":122}}

Votre script peut lire ce flux ligne par ligne pour valider la réussite de la tâche ou extraire le volume de tokens consommés.

Exporter le rapport final avec -o

Si vous souhaitez conserver le rapport textuel final dans un fichier distinct sans intercepter le flux stdout, utilisez l'argument -o <chemin_fichier> (ou --output-last-message) :

codex exec "Génère une documentation du projet" -o ./summary.md

Le texte du rapport final est écrit dans le fichier summary.md tout en restant envoyé sur la sortie standard (stdout), vous permettant de chaîner les commandes sans interruption.

Comparatif des options d'exportation :

Option	Format de sortie	Usage recommandé
--json	Flux JSON Lines (un objet JSON par ligne)	Analyse programmatique des étapes et de la consommation de tokens.
-o <chemin>	Fichier textuel Markdown	Exportation du rapport final pour archivage ou artefact de CI/CD.
Les deux combinés	Flux JSON sur stdout et fichier textuel sur le disque	Analyse de progression par script et sauvegarde du rapport final.

💡 En résumé : L'option --json génère un flux d'événements JSON Lines sur stdout pour l'analyse par vos scripts. L'option -o sauvegarde le rapport final dans un fichier tout en le conservant sur la sortie standard.

---

06 Redirection d'entrées standard (stdin) : Alimenter Codex par pipeline

Cette section présente l'alimentation de Codex en données par redirection de flux.

Pour traiter des données générées par une commande en amont (fichiers de logs, retours d'API), vous pouvez rediriger le flux de sortie de cette commande vers l'entrée standard (stdin) de codex exec.

Deux configurations d'entrées standard existent selon la provenance des consignes :

Configuration A : Consigne textuelle + données en entrée

Lorsque vous rédigez l'instruction dans la commande et que les données du flux servent de contexte d'analyse :

Si des données sont reçues sur l'entrée standard (stdin) et que vous fournissez une instruction textuelle en paramètre, Codex utilise l'instruction comme consigne et traite les données du flux comme contexte de travail.

Exemple pour analyser une trace de crash de tests unitaires :

npm test 2>&1 | codex exec "Analyse les tests en échec et propose une correction"

Le flux d'erreur de npm test est injecté comme contexte. Codex exécute la consigne d'analyse sur ces données.

Configuration B : Consigne complète via l'entrée standard

Lorsque l'instruction et les données sont entièrement générées en amont (par exemple, issues d'un fichier de prompt stocké sur le disque). Utilisez le caractère de contrôle - pour indiquer à Codex de lire l'intégralité de sa consigne sur son entrée standard :

cat prompt_configuration.txt | codex exec -

Cette méthode permet d'isoler vos fichiers de prompts de vos scripts d'exécution.

💡 En résumé : Alimentez Codex en données en redirigeant la sortie d'une commande vers codex exec. Saisissez votre consigne en paramètre pour traiter le flux comme contexte, ou utilisez le caractère - pour lire la consigne complète depuis le flux.

---

07 Reprendre une session précédente : codex exec resume

L'exécution non interactive n'est pas limitée à des traitements uniques. Vous pouvez chaîner des actions au sein d'une même session en utilisant la sous-commande resume.

Analogie : La reprise d'un dossier de travail. Un premier traitement analyse une situation et ferme le dossier (première exécution). La sous-commande resume réouvre le dossier à la dernière page rédigée et permet au collaborateur de poursuivre la tâche d'après les conclusions précédentes.

Exemple de chaînage de commandes :

# Étape 1 : Demander une analyse
codex exec "Recherche les failles de sécurité dans le code actuel"

# Étape 2 : Lancer la correction d'après l'analyse précédente
codex exec resume --last "Propose une correction pour la faille majeure identifiée"

L'argument --last cible la session la plus récente exécutée dans le répertoire courant.

Pour cibler une session d'historique spécifique, renseignez son identifiant unique (session ID) :

codex exec resume <SESSION_ID> "Poursuis le traitement"

Note technique : cette fonction de reprise n'est pas disponible si vous utilisez l'option --ephemeral (mode éphémère) lors du premier appel, la session n'étant pas enregistrée sur le disque.

💡 En résumé : Utilisez la commande codex exec resume --last pour enchaîner des instructions non interactives au sein de la même session en conservant l'historique d'analyse.

---

08 En pratique : Enchaîner les traitements sur plusieurs fichiers

Voici un exercice pratique pour exécuter un traitement non interactif sur une boucle de fichiers, séparer les flux de logs et valider les fichiers de résultats générés.

Note technique : Cet exercice s'exécute sur votre terminal local au sein d'un dépôt de code géré par Git.

Étape 1 : Initialiser le dépôt de test

Créez un dossier et générez deux fichiers de scripts Python d'exemples :

mkdir exec-demo
cd exec-demo
git init
printf 'def somme(a, b):\n    return a + b\n' > math_tools.py
printf 'def salutation(nom):\n    print("Bonjour " + nom)\n' > string_tools.py
git add .
git commit -m "feat: initialisation des modules de test"

Étape 2 : Exécuter un audit unitaire en lecture seule

Lancez un audit sur le premier fichier en redirigeant le résultat :

codex exec "Analyse le fichier math_tools.py et vérifie la présence de docstring" > math_report.txt

Comportement attendu : La console affiche les logs de progression (stderr). Une fois le traitement terminé, le fichier math_report.txt contient uniquement le rapport d'analyse de Codex (stdout).

Étape 3 : Valider le blocage en écriture par défaut

Tentez de modifier un fichier sans accorder de droits d'écriture :

codex exec "Ajoute un commentaire d'explication au début de string_tools.py"

Comportement attendu : Codex s'exécute en lecture seule par défaut. Le traitement se termine sans modifier le fichier string_tools.py.

Étape 4 : Exécuter un script de boucle de modification

Créez un script Bash (ou une commande en boucle) pour ajouter un commentaire sur chaque fichier Python du projet en activant le droit d'écriture :

for f in *.py; do
  echo "Modification du fichier : $f"
  codex exec --sandbox workspace-write "Ajoute un commentaire d'explication au début de la fonction dans $f"
done

Comportement attendu : La boucle appelle Codex pour chaque fichier. Le paramètre --sandbox workspace-write autorisant l'écriture, les fichiers math_tools.py et string_tools.py sont modifiés avec l'ajout du commentaire demandé.

Étape 5 : Supprimer le répertoire de test

Supprimez le répertoire de démonstration après validation :

cd ..
rm -rf exec-demo

Cet exercice valide la mise en œuvre de traitements programmatiques.

💡 En résumé : L'exercice démontre la séparation des sorties, la protection d'écriture par défaut, et la boucle d'exécution de modifications unitaires sur plusieurs fichiers via --sandbox workspace-write.

---

09 Résumé

Ce chapitre a présenté le fonctionnement de la commande codex exec pour exécuter des tâches automatisées en mode non interactif.

Voici les points clés à retenir :

Caractéristique	Règle d'intégration
Utilité	Permet d'intégrer Codex dans des scripts locaux ou des chaînes de CI/CD (sans opérateur humain).
Routage	Les logs de progression vont sur stderr ; le rapport de sortie final va sur stdout.
Sécurité	Mode lecture seule (read-only) par défaut. Droits d'écriture accordés avec --sandbox workspace-write.
JSON	L'option --json génère un flux d'événements JSON Lines (JSONL) structuré pour vos programmes.
Exportation	L'option -o <chemin> écrit le rapport final dans un fichier tout en le conservant sur la sortie standard.
Pipeline	Les données d'entrée standard (stdin) servent de contexte, ou de consigne globale avec la syntaxe cat file | codex exec -.
Reprise	La commande codex exec resume --last enchaîne les instructions au sein d'une même session.

Vous êtes désormais en mesure de comprendre les cas d'usage de la commande non interactive, d'exploiter la séparation des flux stdout/stderr pour rediriger vos rapports, de configurer les droits d'écriture avec le paramètre --sandbox, d'exploiter les sorties d'événements au format JSON, d'alimenter Codex via des redirections d'entrées standard, et d'enchaîner des traitements avec resume.

---

Le chapitre suivant 29 · Intégrations Slack, Linear et SDK présente l'interconnexion avec vos services collaboratifs : comment connecter Codex à vos outils de communication (Slack, Microsoft Teams) ou à vos gestionnaires de tickets (Linear, Jira) pour automatiser la réception de consignes et l'affectation de tâches de développement ? Nous verrons comment étendre la portée de nos automatisations.

---

Lectures recommandées

• Définir des compétences réutilisables (Skills)
• Exécution de tâches en arrière-plan avec Codex Cloud
• Interconnexion d'outils externes (MCP)