Premiers pas avec la CLI

📚 Navigation de la série : Le chapitre précédent 07 · Présentation de l'application de bureau a détaillé l'utilisation de l'interface graphique (visualisation des diffs, tâches parallèles et approbations). Ce chapitre se concentre sur l'interface en ligne de commande (CLI) de Codex. Vous y apprendrez à structurer la commande codex, à naviguer dans l'interface interactive TUI, et à manipuler les options et commandes slash courantes. Le chapitre 09 · Extensions IDE (VS Code...) présentera l'intégration dans vos éditeurs de code.

On estime parfois qu'il convient de privilégier les interfaces graphiques sur la ligne de commande. Pour Codex, ce jugement mérite d'être nuancé.

L'expérience montre que l'application de bureau excelle pour la visualisation, tandis que la CLI est optimisée pour l'intégration opérationnelle. L'application graphique facilite le suivi de diffs complexes ou l'exécution de tâches parallèles. En revanche, l'intégration de Codex dans vos scripts réguliers, son exécution sur des serveurs distants ou son intégration dans des pipelines de CI/CD exigent l'usage exclusif de la CLI.

De plus, la CLI ne se limite pas à un simple prompt passif. L'appel à la commande codex ouvre une interface interactive plein écran désignée sous le terme de TUI (Terminal User Interface). Elle intègre un historique d'échange, une zone de saisie et une barre d'état, offrant une densité d'information équivalente à l'application de bureau, mais pilotable au clavier.

Ce chapitre détaille la structure et l'utilisation de la commande codex.

À la fin de ce chapitre, vous obtiendrez :

• Le plan de structure de la commande codex (sous-commandes, options, prompts)
• L'organisation de la TUI en trois zones (historique, saisie et état)
• Un tableau de référence des options de configuration de la CLI (--model, --sandbox, --cd, --search, etc.)
• Les commandes slash et raccourcis clavier indispensables, complétés par un exercice de validation
• La distinction d'usage entre le mode interactif et le mode d'exécution direct exec

---

01 Structure de la commande codex

La longueur des arguments de commandes en console (ex. codex exec --sandbox workspace-write --model xxx "consignedefin") peut sembler complexe.

La structure s'aligne systématiquement sur quatre blocs principaux : la commande principale, la sous-commande, les options et le prompt.

Analogie : Passer commande dans un café. L'appel codex équivaut à commander un café (la commande principale). Le choix d'un expresso ou d'un café glacé correspond à la sous-commande (exec, resume...). Les suppléments (lait d'avoine, glaçons) s'apparentent aux options (préfixées par --). Le prompt final — « analyse ce module » — est la consigne transmise.

Représentation structurelle :

codex   [子命令]   [选项...]   ["提示词"]
  │         │          │            │
  主命令   换跑法     调参数      要干的活

Détail des blocs :

• Commande principale codex : Lance l'interface interactive TUI par défaut.
• Sous-commande : Définit le mode d'exécution. Par exemple, exec exécute la consigne et ferme la session (non interactif) ; resume rouvre la dernière session active ; login gère l'authentification.
• Options (flags) : Paramètres préfixés par -- ou - (ex. --model ou -m pour le modèle, --sandbox ou -s pour la sandbox, --cd pour le répertoire).
• Prompt : Consigne formulée entre guillemets. Optionnelle, elle initie la tâche dès le lancement de la TUI.

Exemples d'utilisation :

# 啥都不带，进交互界面
codex

# 带一句提示词，进界面后它直接开干
codex "解释一下这个项目的结构"

# 换个模型 + 指定工作目录
codex --model gpt-5.5 --cd ~/my-project "把 README 补全"

⚠️ Note : L'identifiant gpt-5.5 est indicatif ; consultez les modèles valides sur votre instance via la commande slash /model.

💡 En résumé : La commande codex réunit : la commande principale, la sous-commande, les options et le prompt. Ce schéma structure l'ensemble de vos appels.

---

02 Organisation de l'interface TUI

L'interface TUI s'articule autour de trois zones distinctes :

Analogie : L'écran de diffusion en direct. La zone centrale affiche les actions et rapports de l'agent (zone d'échange : code, diff review, logs d'analyse). La zone inférieure reçoit vos prompts (zone de saisie). La ligne de statut affiche les paramètres actifs (barre d'état : modèle, taille du contexte, répertoire).

Détail des zones :

• Zone d'échange (partie centrale) : Affiche l'historique de discussion, le code généré et les diffs de révision avec coloration syntaxique.
• Zone de saisie (ligne inférieure) : Reçoit vos instructions textuelles, chemins d'accès ou commandes slash.
• Barre d'état / Footer (bas de l'écran) : Affiche le modèle actif, la consommation de tokens, le répertoire de travail et la branche git (personnalisable via /statusline).

Note de secours : Si des distorsions d'affichage surviennent (notamment lors de l'usage de multiplexeurs comme tmux), utilisez le raccourci Ctrl+L pour forcer le rafraîchissement de l'interface TUI. Le contexte de discussion reste actif.

Distinguez ce raccourci de la commande slash de nettoyage :

Le raccourci Ctrl+L actualise uniquement l'affichage écran en préservant le fil de discussion. La commande slash /clear réinitialise le contexte de la session active en effaçant l'historique.

💡 En résumé : L'interface TUI réunit la zone d'échange, la zone de saisie et la barre d'état. Utilisez Ctrl+L pour nettoyer l'affichage, et /clear pour réinitialiser la session.

---

03 Sélection d'options de configuration indispensables

Voici les options de configuration de la CLI les plus fréquemment utilisées (issues du document de référence cli/reference) :

Analogie : Les réglages d'un appareil photo. Un boîtier professionnel comporte de nombreuses touches, mais vous n'utilisez au quotidien que l'ouverture, l'exposition et la sensibilité. De même, maîtrisez ces huit options de base avant d'explorer les configurations avancées.

Option (Longue / Courte)	Action	Exemple d'usage
--model / -m	Sélectionner temporairement un modèle	codex -m gpt-5.5 "Reconstruis cette fonction"
--sandbox / -s	Configurer le mode de sandbox	codex -s read-only "Revue de code uniquement"
--ask-for-approval / -a	Définir la politique d'approbation	codex -a on-request "Correction de bug"
--cd / -C	Exécuter directement dans un répertoire	codex --cd ~/proj "Présente-moi ce projet"
--add-dir	Ajouter un dossier d'écriture autorisé	codex --cd app --add-dir ../shared
--image / -i	Soumettre un document visuel	codex -i error.png "Analyse de cette capture"
--search	Activer la recherche web en temps réel	codex --search "Recherche documentation API"
--oss	Utiliser un modèle local (via Ollama actif)	codex --oss "Écris ce script hors-ligne"

Remarques complémentaires :

L'option --cd permet d'éviter l'exécutions séquentielle de cd puis de codex. Elle cible directement le répertoire de travail pour la session.

Les options --sandbox et --ask-for-approval surchargent les profils par défaut du projet. Le couple --sandbox workspace-write et --ask-for-approval on-request constitue la configuration recommandée (sécurité des écritures, alertes lors des accès externes). La persistance des configurations est détaillée au chapitre 15.

L'option --search active la recherche réseau en temps réel, remplaçant la recherche par index mis en cache utilisée par défaut par l'agent.

Note de sécurité sur l'accès illimité :

⚠️ L'argument --dangerously-bypass-approvals-and-sandbox (alias --yolo) désactive l'intégralité des sécurités de la sandbox et des approbations d'écritures. Évitez son utilisation sur votre machine locale ; réservez-le aux conteneurs de tests isolés.

💡 En résumé : Raccourcis prioritaires : -m (modèle), -s/-a (sécurité), --cd (répertoire) et --search (web). Évitez le mode --yolo sur vos machines locales.

---

04 Les commandes slash

Les commandes slash (saisie du caractère / dans la zone de prompt) configurent la session en cours d'exécution :

Commande slash	Action	Cas d'usage
/model	Modifier le modèle actif	Changement de modèle en cours de session
/permissions	Adapter la politique d'approbation	Modification des droits d'écriture
/status	Afficher l'état de la session (modèle, sandbox, contexte)	Contrôle des paramètres actifs
/diff	Afficher le diff git	Revue des modifications appliquées
/compact	Condenser l'historique	Session longue pour préserver le contexte
/review	Lancer une revue de code automatique	Validation finale de vos modifications
/init	Initialiser le fichier AGENTS.md	Ajout des conventions de projet
/clear	Réinitialiser l'historique et l'affichage	Démarrer une nouvelle tâche

Note : Codex intègre un système de file d'attente. Si une tâche est en cours d'exécution, vous pouvez saisir votre prochaine instruction ou commande slash et utiliser Tab pour la planifier à la suite.

Note : Les commandes avancées et la personnalisation de scripts sont détaillées au chapitre 12.

💡 En résumé : Commandes slash principales : /model (choix du modèle), /permissions (droits), /status (mesure du contexte) et /diff (revue). Utilisez Tab pour planifier la suite.

---

05 Raccourcis clavier indispensables dans la TUI

Voici les raccourcis de contrôle d'affichage et de saisie les plus courants :

Raccourci	Action
Ctrl+C	Interrompre l'action en cours ou quitter la session (via /exit)
Ctrl+L	Actualiser l'affichage écran (préserve l'historique)
↑ / ↓	Parcourir l'historique des prompts saisis
Ctrl+R	Recherche inversée dans l'historique des requêtes
Ctrl+O	Copier le dernier retour généré par l'agent
Tab	Planifier une instruction en file d'attente
Esc Esc	Rééditer le dernier prompt envoyé (avec modification du flux)
Ctrl+G	Ouvrir un éditeur externe pour rédiger un prompt long

Fonctionnalités avancées de saisie :

L'appel shell ! : préfixer une commande locale par un point d'exclamation (ex. !git status) l'exécute directement dans votre console sans solliciter le modèle. Codex intègre le retour de la commande dans le contexte système pour les requêtes ultérieures.

!git status

Rédiger un prompt long (Ctrl+G) : Ouvre votre éditeur système par défaut (configuré par la variable VISUAL ou EDITOR) pour composer des demandes structurées. À la fermeture du fichier, le texte est copié dans la zone de saisie.

L'appel @ active la recherche floue de fichiers dans l'espace de travail pour insérer le chemin absolu dans la saisie.

💡 En résumé : Raccourcis prioritaires : ! (commande locale), @ (insertion de fichier) et Ctrl+G (éditeur de prompt). Raccourcis configurables via /keymap.

---

06 Exercice pratique : valider l'usage de la CLI

Exercice pour manipuler l'interface TUI dans un dossier vide :

Note : Assurez-vous d'avoir validé l'étape de connexion (chapitre 03) avant de démarrer.

Étape 1 : Créer le répertoire et démarrer Codex

Saisissez (remplacez mkdir -p par mkdir sous Windows) :

mkdir -p ~/codex-cli-demo && cd ~/codex-cli-demo
codex

Résultat attendu : L'interface TUI s'ouvre avec la zone d'échange centrale et la zone de saisie inférieure.

Étape 2 : Lancer la commande slash /status

Saisissez :

/status

Résultat attendu : Affichage des paramètres de session : modèle, sandbox et consommation active de jetons.

Étape 3 : Lancer une commande shell locale

Saisissez :

!echo hello-codex-cli

Résultat attendu : Le message s'affiche directement en console et le retour est intégré au contexte.

Étape 4 : Parcourir l'historique

Appuyez sur la touche flèche haut ↑ :

Résultat attendu : La dernière commande saisie est recopiée dans la zone de prompt.

Étape 5 : Lancer une modification et lire le diff

Formulez une commande d'écriture simple :

新建一个文件 hi.txt，里面写一行 "hello from codex cli"。

Validez la demande d'écriture le cas échéant, puis saisissez :

/diff

Résultat attendu : Codex affiche le diff du nouveau fichier hi.txt généré sur le disque.

Étape 6 : Quitter l'interface

Saisissez :

/exit

Résultat attendu : Retour au shell de votre terminal.

Ces étapes valident les bases de manipulation de l'interface en ligne de commande.

---

07 Mode interactif vs exécution non interactive (exec)

La CLI intègre un mode d'exécutions automatisé sans interface utilisateur : la commande codex exec (ou codex e).

Le mode interactif standard convient au développement pas à pas. L'analyse asynchrone (ex. vérification de commits en tâche de fond, résolution automatique de tests en CI) s'effectue plus efficacement via exec : l'agent traite le prompt et se ferme à la fin du traitement.

Analogie : Le repas en salle vs la livraison. Le mode interactif correspond au repas en salle : vous ajustez les demandes à mesure de la génération de code. Le mode exec s'apparente à la livraison de plats cuisinés : vous soumettez le prompt, l'agent traite l'opération et vous livre le résultat (redirigé vers la sortie standard stdout) sans nécessiter votre présence.

Exemple d'appel simple :

codex exec "审查当前改动，列出潜在 bug"

L'agent analyse l'espace de travail et retourne la synthèse en console avant de fermer la session.

Options de configuration du mode exec (source : document de référence cli/reference) :

Option exec	Action
--model / -m	Forcer le modèle pour l'exécutions
--json	Retourner la sortie au format JSON (pour intégration dans des scripts)
--output-last-message / -o	Écrire le rapport final dans un fichier
--skip-git-repo-check	Autoriser l'exécutions hors d'un dépôt git
--ephemeral	Ne pas enregistrer l'historique de session localement

Comparatif des deux approches :

Critère	Mode interactif (codex)	Mode non interactif (codex exec)
Fin de tâche	TUI active en attente d'instruction	Fermeture de la session
Cas d'usage	Diagnostics complexes, itérations pas à pas	CI/CD, scripts d'automatisation, planifications
Supervision	Indispensable (relecture pas à pas)	Autonome (traitement asynchrone)
Format de sortie	Rendu coloré en TUI	Redirection stdout, format --json machine
Exemple type	« Refactorise cette couche logicielle »	« Génère la liste des modifications depuis hier »

Note : Le mode exec étant configuré sans intervention humaine, la politique d'approbation est par défaut sur never. Veillez à associer une sandbox restreinte (workspace-write ou read-only) pour sécuriser vos fichiers lors de ces appels autonomes.

💡 En résumé : Le mode interactif correspond à l'usage manuel pas à pas, le mode exec à l'intégration asynchrone ou automatisée. Choisissez selon le besoin de supervision.

---

08 Résumé

Ce chapitre a détaillé la structure et les raccourcis de la CLI :

Objectif	Commande / Action
Ouvrir la TUI	Commande codex (suivie du prompt éventuel)
Configurer la session au lancement	--model / --sandbox / --ask-for-approval
Définir le répertoire de travail	--cd /chemin/acces
Soumettre un document visuel	-i /chemin/image.png
Options en cours de session	Commandes slash /model, /status ou /diff
Exécuter une commande locale	Préfixer la saisie par un point d'exclamation !
Rafraîchir l'affichage TUI	Raccourci Ctrl+L
Rédiger un prompt structuré	Raccourci Ctrl+G
Exécutions autonome asynchrone	Commande codex exec

Le chapitre suivant 09 · Extensions IDE (VS Code...) présente l'intégration de Codex au sein des éditeurs de code (VS Code, Cursor).

---

Lectures recommandées

• Windows : environnement natif vs WSL
• Table de référence des commandes et configurations
• Installation et connexion