Guide de référence CLI : Commandes et tous les drapeaux

📚 Navigation de la série : Le chapitre précédent 33 Hooks vous a appris à déclencher automatiquement des actions sur des événements définis et à mettre des garde-fous à Claude. Ce chapitre revient à l'essentiel : combien de variantes pouvez-vous ajouter à cette ligne claude que vous tapez dans le terminal. Commandes, drapeaux (flags), pipelines, codes de sortie, tout est regroupé dans cet article, accompagné d'un tableau de référence rapide.

« On peut ajouter des arguments après claude ? Moi, je tape juste claude tout court. »

« Bien sûr, et pas qu'un peu. Tu peux faire exécuter claude -p '总结这个 PR' par un script, et le résultat est directement écrit dans un fichier sans jamais entrer dans l'interface interactive. »

« Attends — c'est quoi -p ? J'ai parcouru claude --help pendant un long moment sans tout voir. »

Cette conversation est assez courante. Beaucoup de personnes utilisent Claude Code depuis six mois et ne savent que taper claude pour entrer en mode interactif, sans savoir qu'il y a des dizaines de drapeaux (flags) derrière cette commande. On ne peut en vouloir à personne — la documentation officielle elle-même le dit : claude --help ne liste pas tous les drapeaux. Si vous vous contentez de --help, vous passerez à côté de beaucoup de choses.

En clair, dans les trente chapitres précédents, nous avons tourné en rond dans le "mode interactif" : entrer, discuter, le laisser travailler. Mais claude est par essence un outil en ligne de commande, et les possibilités d'un outil en ligne de commande vont bien au-delà de la simple "ouverture d'une interface" — il peut être connecté à des pipelines, intégré dans des scripts et juger du succès ou de l'échec selon le code de sortie. Ce chapitre d'aujourd'hui est ce "manuel d'instructions" : nous allons détailler d'un coup les commandes, les drapeaux, l'utilisation des pipelines et les codes de sortie de claude, afin que vous puissiez directement consulter le tableau à l'avenir.

À la fin de ce chapitre, vous obtiendrez :

• La liste des commandes de base de claude : démarrage, démarrage avec invite initiale, pipelines, continuation/reprise de session, mise à jour, connexion, et ce que fait chacune d'elles ;
• Les drapeaux les plus courants (comme -p, --model, -c, --resume, --permission-mode, --add-dir, etc.) expliqués en détail, accompagnés d'un tableau comparatif complet ;
• L'utilisation sans tête (headless) et des pipelines : comment intégrer Claude dans des scripts, l'utiliser comme un linter, ou le connecter à jq pour traiter la sortie ;
• Comment lire les codes de sortie : comment s'appuyer sur eux dans un script pour déterminer si l'action a réussi ou échoué ;
• Un flux de travail complet sans tête (headless) à suivre étape par étape : appel brut, alimentation par pipeline, sortie structurée et vérification du code de sortie.

---

01 Distinguer d'abord deux termes : commandes vs drapeaux (flags)

Avant de consulter les tableaux, clarifions deux termes souvent confondus. Une ligne entière saisie dans le terminal se compose de deux éléments : la commande (command) et le drapeau (flag).

Analogie : Remplir un bordereau d'expédition. claude est l'action d'envoyer le colis en elle-même ; ce qui suit, comme update ou mcp, correspond à des sous-actions (commandes), indiquant au système que vous n'envoyez pas un colis ordinaire aujourd'hui, mais que vous voulez faire une "mise à jour" ou "configurer MCP" ; et les -p ou --model plus loin sont des cases à cocher (drapeaux) sur le formulaire pour ajuster la livraison — est-ce urgent ? assuré ? avec quel modèle ? Vous choisissez une action principale, et vous pouvez cocher plusieurs cases.

Concrètement :

claude update
claude -p "解释这个函数" --model sonnet

• Première ligne : claude est le programme, update est la commande (une sous-action qui se termine et quitte le programme après exécution).
• Deuxième ligne : aucune commande ne suit claude, on entre directement dans la logique de session ; -p et --model sont tous deux des drapeaux, et le "解释这个函数" qui suit -p est l'invite initiale de cette session.

Pourquoi distinguer les deux ? Parce qu'ils sont listés dans deux tableaux différents dans la documentation, et vous devez savoir lequel consulter. Si vous voulez savoir "comment mettre à jour / se connecter / configurer MCP" — consultez le tableau des commandes ; si vous voulez savoir "comment changer de modèle / obtenir le résultat directement sans entrer en mode interactif / faire en sorte qu'il ne demande pas de permissions d'abord" — consultez le tableau des drapeaux.

Un autre détail appréciable est à noter : si vous tapez une commande erronée, il vous le signalera. Le texte officiel est très clair à ce sujet —

Si vous saisissez une sous-commande incorrecte, Claude Code suggérera la correspondance la plus proche et quittera sans démarrer de session. Par exemple, claude udpate affichera Did you mean claude update?.

Il est fréquent de faire une faute de frappe rapide avec claude udpate. À chaque fois, il vous demandera sagement « si vous vouliez taper claude update », au lieu de démarrer bêtement une session avec une faute d'orthographe. Cette petite attention évite bien des frustrations du genre « tiens, pourquoi ça ne réagit pas ? ».

💡 Résumé en une phrase : Une ligne de commande se divise en deux — les commandes sont des sous-actions (update, mcp, qui quittent après exécution) ; les drapeaux sont des cases à cocher (-p, --model, pour ajuster le comportement de l'exécution) ; déterminez d'abord quel tableau vous devez consulter.

---

02 Commandes principales : Les différentes façons de démarrer une session

Voyons d'abord les commandes. Celles que vous taperez réellement au quotidien ne sont pas si nombreuses. Je les ai classées en trois groupes par « cas d'usage », chacun accompagné de la syntaxe standard officielle.

Premier groupe : Démarrage de session (le plus courant)

C'est ce groupe que vous utiliserez 90% du temps :

# 1. 光秃秃启动，进交互模式
claude

# 2. 带一句初始提示启动（进去后它先回答这句）
claude "解释这个项目"

# 3. 不进交互、直接出结果就退出（headless / 打印模式）
claude -p "解释这个函数"

Vous connaissez déjà bien les deux premières lignes. La troisième, claude -p, est « l'autre façon de faire » sur laquelle nous allons mettre l'accent dans cet article — elle n'ouvre pas l'interface de discussion, mais affiche directement la réponse dans le terminal puis se ferme, ce qui est spécifiquement conçu pour les scripts et les pipelines. Les détails sont fournis dans la section 04.

Deuxième groupe : Continuer la conversation précédente (éviter l'amnésie)

Vous souvenez-vous du chapitre 19 ? Chaque fois que vous ouvrez une nouvelle session, Claude est comme un « stagiaire amnésique », ayant complètement oublié ce dont vous parliez la fois passée. Ces deux commandes permettent de remédier à cette amnésie :

# 继续「当前目录」最近的那次对话
claude -c
# （--continue 是它的全称，-c 是简写）

# 按 ID 或名字恢复「某一次特定」的对话
claude -r "auth-refactor" "把这个 PR 收尾"
# （--resume 是全称，-r 是简写）

La seule différence réside dans ce mot : « récente » ou « spécifiée ».

• -c (--continue) : ne prend en compte que la « toute dernière dans le répertoire actuel », pas besoin de mémoriser d'ID, c'est le plus simple.
• -r (--resume) : désigne une session précise — en fournissant l'ID de session ou le nom que vous aviez défini avec --name ; si vous ne le fournissez pas, une liste interactive apparaîtra pour vous permettre de choisir.

Analogie : Continuer une conversation avec un collègue. -c équivaut à dire « continuons sur ce que nous venons de dire » — par défaut, il s'agit du sujet le plus récent, pas besoin d'expliquer ; -r équivaut à dire « continuons sur le sujet de la refactorisation de la connexion de mercredi dernier » — vous devez indiquer clairement de quoi il s'agit pour que l'interlocuteur retrouve ce souvenir.

Une bonne habitude à prendre : utilisez -c lorsque vous travaillez sur une seule tâche à la fois, pour éviter de retenir des noms ; utilisez -r pour reprendre une session précise uniquement si vous gérez plusieurs chantiers en parallèle (résoudre un bug par-ci, écrire des tests par-là) — à condition d'avoir nommé chaque chantier avec --name (raccourci -n) au démarrage, sinon vous vous retrouverez avec une pile d'UUID impossibles à identifier. Voici à quoi ressemble un flux de travail complet :

# 启动时起个好认的名字
claude -n "login-refactor"

# 几天后回来，按名字直接恢复这一摊
claude -r "login-refactor"

L'explication officielle de --name est très simple — le nom d'affichage qu'il configure apparaîtra dans la liste de /resume et dans le titre du terminal, ce qui vous permettra de le reprendre plus tard avec claude --resume <名字>. Lorsque vous menez de front trois ou quatre tâches, ce nom est indispensable pour s'y retrouver, bien plus pratique qu'une chaîne UUID du type 550e8400-....

Une combinaison mérite d'être mentionnée à part : -c et -p peuvent être combinés. claude -c -p "查一下有没有类型错误" signifie « continuer la conversation la plus récente, mais en mode headless cette fois-ci, et quitter après avoir produit le résultat » — il conserve le contexte précédent sans entrer dans l'interface interactive. C'est particulièrement pratique dans les scripts pour « faire avancer une tâche étape par étape de manière automatique » (l'exemple d'enchaînement de --continue de la section 04 montre comment les relier).

Troisième groupe : Maintenance et compte

Ce dernier groupe est moins utilisé au quotidien, mais vous devez savoir qu'il existe :

# 更新到最新版
claude update

# 安装 / 重装本机二进制（可指定版本：2.1.118 / stable / latest）
claude install stable

# 登录 Anthropic 账户
claude auth login

# 查登录状态（已登录退出码 0，未登录退出码 1）
claude auth status

Le détail concernant la possibilité de spécifier un numéro de version avec claude install peut s'avérer salvateur au moment opportun : la documentation officielle indique qu'elle accepte une version spécifique comme 2.1.118, ainsi que stable ou latest. Imaginez la situation suivante — le comportement d'une nouvelle version a changé et ne vous convient pas, vous pouvez utiliser claude install 2.1.x pour revenir en arrière et vous figer sur la version stable précédente, en attendant que le problème soit résolu, ce qui est bien plus confortable que d'attendre sans rien faire.

Gardez en tête la règle de claude auth status indiquant « code de sortie 0 si connecté, code de sortie 1 si non connecté », nous y reviendrons dans la section 05 sur les codes de sortie — c'est la méthode standard pour vérifier si l'utilisateur est actuellement connecté dans un script.

Ces commandes nécessitent une connexion Internet. Si l'accès au système de compte d'Anthropic (connexion, téléchargement des paquets de mise à jour) échoue, assurez-vous que votre configuration réseau le permet avant de réessayer.

💡 Résumé en une phrase : Mémorisez les commandes en trois groupes — démarrer une session (claude / claude "提示" / claude -p), continuer la conversation précédente (-c pour la plus récente, -r pour une session nommée) et maintenance du compte (update / install / auth) ; -c et -r sont les deux remèdes contre l'« amnésie de session ».

---

03 Drapeaux les plus courants : Explications détaillées

Les commandes étant posées, passons à la partie principale : les drapeaux (flags). Bien qu'il y en ait des dizaines, vous n'en utiliserez réellement que sept ou huit fréquemment — je vais d'abord vous expliquer ceux-ci en detail, puis je vous fournirai un tableau récapitulatif dans la section 06 (le tableau sert à « vérifier », cette section sert à « comprendre »).

-p / --print : Ne pas entrer en mode interactif, afficher directement le résultat

Le plus important de tous, sans exception. En ajoutant -p, Claude n'ouvrira pas l'interface de discussion — il lit votre invite, fait le travail, affiche le résultat dans le terminal et se ferme, le tout sans aucune supervision humaine.

claude -p "这个项目的 auth 模块是干啥 of"

C'est l'interrupteur du mode headless (sans tête, c'est-à-dire sans interface interactive, s'exécutant uniquement en ligne de commande), et la base de toutes les utilisations ultérieures pour les intégrations de scripts et de pipelines. La section 04 y est entièrement consacrée.

--model : Quel modèle utiliser pour cette session

Permet de spécifier temporairement le modèle à utiliser pour cette session, en écrasant le modèle par défaut configuré :

claude --model sonnet
claude --model opus
claude --model claude-sonnet-4-6   # 也可以写完整名字

Vous pouvez utiliser des alias (sonnet, opus pointant vers leurs versions les plus récentes respectives) ou saisir le nom complet du modèle. Le choix des modèles et leur positionnement ont été abordés au chapitre 05. Ici, nous nous conservons uniquement sur la manière de basculer temporairement en ligne de commande.

--permission-mode : Quel mode de permission activer pour cette session

Détermine directement si Claude vous demande votre accord avant d'agir. Vous vous souvenez de la « laisse des permissions » du chapitre 20 ? Ce drapeau sert précisément à ajuster la tension de cette laisse au moment du démarrage :

claude --permission-mode plan

Les valeurs acceptées officiellement sont les suivantes :

Accepte default, acceptEdits, plan, auto, dontAsk ou bypassPermissions. Écrase la valeur defaultMode du fichier de configuration.

En résumé : les modes plan (planifier uniquement sans exécuter), acceptEdits (approuver automatiquement les modifications de fichiers) et bypassPermissions (tout autoriser, à utiliser avec prudence) sont les plus courants. Le comportement de chacun de ces modes sera détaillé dans le prochain chapitre (chapitre 35). Pour l'instant, sachez simplement que ce drapeau permet de choisir le mode souhaité dès le démarrage.

--dangerously-skip-permissions : L'interrupteur au nom explicite « dangerous »

Nous abordons ce drapeau à part car c'est celui que les débutants demandent le plus souvent et ont tendance à utiliser à tort et à travers. Son rôle est d'ignorer toutes les demandes de permission — la documentation officielle indique clairement qu'il équivaut à --permission-mode bypassPermissions :

claude --dangerously-skip-permissions

En l'ajoutant, Claude ne s'arrêtera plus jamais pour vous demander l'autorisation de modifier un fichier ou de lancer une commande ; il foncera tête baissée. Le fait que le mot dangerously (dangereusement) figure explicitement dans le nom est une mise en garde d'Anthropic pour que vous y réfléchissiez à deux fois. Les chapitres 20 et 21 ont répété à maintes reprises le concept de la « laisse des permissions » — cet interrupteur revient à lâcher complètement la laisse.

Il y a une ligne rouge à ne pas franchir : ne l'utilisez que dans des environnements « clairement isolés et où une panne n'a pas d'importance » — comme un conteneur éphémère, un dépôt d'entraînement ou un bac à sable temporaire dans une CI. Dans vos répertoires de projets réels, et surtout là où vous pouvez toucher à des données de production, n'y touchez sous aucun prétexte. Pour limiter les invites de permission lors de traitements par lots en mode headless, privilégiez --allowedTools pour autoriser précisément certains outils, ou utilisez --permission-mode acceptEdits pour n'autoriser que les modifications de fichiers — ce qui est bien plus sûr qu'une autorisation globale.

--add-dir : Lui permettre d'accéder à un répertoire supplémentaire

Par défaut, Claude ne peut lire et modifier que le répertoire depuis lequel vous l'avez lancé. --add-dir lui accorde l'accès à des répertoires supplémentaires :

claude --add-dir ../apps ../lib

Scénario typique : votre projet et une bibliothèque dont il dépend se trouvent dans deux dossiers distincts, et vous voulez que Claude puisse travailler sur les deux en même temps. Notez bien cette mise en garde officielle —

Accorde l'accès aux fichiers ; la plupart des configurations de .claude/ ne seront pas découvertes à partir de ces répertoires.

En d'autres termes : --add-dir n'accorde que des droits de « lecture et écriture de fichiers », il ne va pas charger les fichiers de configuration comme CLAUDE.md ou les Skills de ce répertoire. Ne vous attendez pas à hériter de toute la configuration de ce répertoire simplement en l'ajoutant.

--output-format : Sous quel format renvoyer les résultats

N'a de sens qu'en mode d'affichage -p, pour contrôler la structure de la sortie :

claude -p "总结这个项目" --output-format json

Trois options : text (par défaut, texte brut), json (résultat structuré contenant l'ID de session, le coût et d'autres métadonnées), et stream-json (événements JSON ligne par ligne en temps réel). Si vous voulez obtenir le coût de la session ou l'ID de session dans un script, vous devez utiliser json — la section 04 montrera comment l'envoyer à jq.

--allowedTools / --disallowedTools : Liste blanche / Liste noire

Permet d'autoriser (ou de refuser) à l'avance certains outils, afin d'éviter que le mode headless ne se bloque sur une invite de permission en cours de route (un script non surveillé qui se bloque est un script gâché) :

claude -p "跑测试并修掉失败" --allowedTools "Bash,Read,Edit"

Les outils listés dans --allowedTools sont autorisés directement sans confirmation ; --disallowedTools fait l'inverse en les bloquant. Tous deux utilisent la syntaxe des règles de permission (détails au chapitre 20), par exemple "Bash(git diff *)" n'autorise que les commandes commençant par git diff.

Notez la différence avec --tools — --tools retire complètement un outil du contexte du modèle, le rendant unusable ; --allowedTools ne fait qu'ignorer la demande de confirmation, l'outil restant disponible.

Quelques « fusibles » dédiés au mode headless

Ceux-ci ne s'appliquent qu'en mode -p, mais ils sont très pratiques pour éviter que les scripts ne s'emballent :

# 限制最多跑几轮，超了报错退出（默认无限制）
claude -p --max-turns 3 "查询"

# API 花费一旦超过这个金额就停（单位美元）
claude -p --max-budget-usd 5.00 "查询"

Un piège discret se cache dans --max-turns : si vous oubliez de l'ajouter dans vos scripts d'automatisation, et que Claude se retrouve coincé dans une boucle d'essais-erreurs, le nombre d'étapes (turns) va grimper en flèche ainsi que la facture. Si le script n'est pas surveillé, c'est de l'argent jeté par les fenêtres. La bonne pratique consiste à ajouter systématiquement --max-turns dans vos scripts de traitement par lots, ce qui revient à lui fixer une limite stricte de « tentatives autorisées ». S'il la dépasse, il s'arrête avec une erreur, ce qui est bien plus rassurant.

💡 Résumé en une phrase : Retenez ces drapeaux fréquents — -p pour le résultat sans mode interactif, --model pour changer de modèle, --permission-mode pour régler les permissions, --add-dir pour ajouter un répertoire, --output-format json pour obtenir un résultat structuré, et --allowedTools pour pré-autoriser des outils ; si vous craignez qu'un script ne s'emballe, ajoutez --max-turns / --max-budget-usd comme garde-fous.

---

04 Mode headless et pipelines : Intégrer Claude dans la ligne de commande

C'est dans cette section que claude -p prend tout son sens. Alors que dans les chapitres précédents Claude était « une fenêtre de discussion avec laquelle vous échangez », il devient ici « un composant de la ligne de commande pouvant être connecté à des pipelines » — il peut recevoir des données provenant d'autres commandes et envoyer ses résultats à la commande suivante.

Analogie : Un poste de travail sur une chaîne de montage. Le mode interactif ressemble au travail manuel à un établi où vous traitez les pièces une par une ; le mode headless consiste à souder Claude à une chaîne de production — l'étape précédente (comme cat ou git diff) envoie la matière première, Claude la traite, puis le résultat passe directement à l'étape suivante (comme l'écriture dans un fichier ou le passage à jq). Vous n'avez pas besoin de rester à côté, toute la chaîne tourne d'elle-même.

Pipelines : Lui injecter des données

Le mode non interactif lit l'entrée standard (stdin). Vous pouvez donc, comme avec n'importe quel outil CLI, utiliser | pour lui envoyer des données par un pipeline :

cat build-error.txt | claude -p '简明解释这个构建错误的根本原因' > output.txt

Cette commande effectue trois tâches : cat extrait le contenu du journal → le pipeline l'envoie à claude -p → après analyse, > écrit le résultat dans output.txt. Aucune interface n'apparaît durant tout le processus, ce qui est idéal pour l'intégrer dans n'importe quel flux automatisé.

Il y a une limite officielle claire à retenir : à partir de la version v2.1.128, la taille maximale du contenu envoyé par pipeline est de 10 Mo. Si vous la dépassez, Claude Code affichera une erreur explicite et s'arrêtera avec un code de sortie non nul. Pour traiter des entrées plus volumineuses, écrivez-les dans un fichier et référencez son chemin dans l'invite, plutôt que de forcer le passage par un pipeline.

L'utiliser comme un linter propre au projet

En encapsulant l'appel headless dans un script, Claude devient l'« inspecteur attitré » de votre projet. L'exemple de package.json fourni par la documentation officielle est typique — envoyer le diff par rapport à main à Claude pour qu'il trouve les fautes de frappe :

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

Vous pouvez ensuite lancer npm run lint:claude. L'avantage d'envoyer le diff par pipeline : Claude n'a pas besoin de permissions Bash pour lire lui-même le diff, puisque c'est vous qui lui fournissez la matière.

Connecter à jq pour traiter la sortie structurée

Si vous voulez uniquement récupérer le texte du résultat ou extraire l'ID de session dans un script, utilisez --output-format json combiné avec jq (un outil en ligne de commande pour traiter le JSON) :

# 只取结果文本
claude -p "总结这个项目" --output-format json | jq -r '.result'

Le format json renvoie un objet contenant des métadonnées — le texte du résultat se trouve dans le champ .result, l'ID de session dans .session_id, et le coût de cette session dans total_cost_usd. Pour enchaîner plusieurs échanges dans un script, la méthode consiste à récupérer d'abord le session_id, puis à utiliser --resume :

session_id=$(claude -p "开始审查" --output-format json | jq -r '.session_id')
claude -p "继续那次审查" --resume "$session_id"

Assigner une « identité temporaire » à cet appel de script

Lors de l'exécution de traitements par lots en mode headless, on souhaite souvent faire jouer un rôle spécifique à Claude pour cette session — par exemple, « tu es un ingénieur en sécurité, cherche les vulnérabilités ». Utilisez --append-system-prompt pour ajouter cette consigne à la fin de l'invite système par défaut. Cet exemple officiel montre comment lui soumettre le diff d'une PR pour un audit de sécurité :

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

Il faut bien distinguer deux drapeaux ici pour éviter les erreurs : --append-system-prompt sert à « ajouter des instructions à la suite de l'invite par défaut ». Claude conserve ses capacités d'assistant de programmation et ses règles de sécurité, vous ne faites qu'ajouter une exigence supplémentaire ; tandis que --system-prompt sert à « remplacer intégralement » l'invite système par défaut — les outils et les contraintes de sécurité disparaissent, et vous devez tout gérer vous-même. Dans 90% des cas, vous aurez besoin d'un append (ajout), pas d'un system-prompt (remplacement) ; n'utilisez le remplacement que si l'identité par défaut d'« assistant de programmation » de Claude ne convient pas du tout à votre tâche.

--bare : Démarrage plus rapide dans les scripts

Il existe également un drapeau spécialement conçu pour les scripts nommé --bare (mode nu). La documentation officielle l'explique ainsi :

Mode minimal : ignore les hooks, les skills, les plugins, les serveurs MCP, la mémoire automatique et la découverte automatique de CLAUDE.md pour un démarrage plus rapide lors d'appels scriptés.

En clair, un appel claude -p standard chargera tout le contexte d'une session interactive (votre CLAUDE.md, les Skills installés, les MCP configurés) ; --bare ignore tout cela pour ne conserver que trois outils de base (Bash, lecture de fichier, écriture de fichier). Le démarrage est plus rapide et produit des résultats constants sur toutes les machines (sans être influencé par des personnalisations dans le dossier ~/.claude de quelqu'un). C'est particulièrement utile dans les environnements de CI et dans les scripts. La documentation officielle indique également que --bare deviendra la valeur par défaut pour -p dans les futures versions, il est donc judicieux de prendre cette habitude dès maintenant.

La comparaison directe entre le mode interactif et le mode headless permet de bien saisir les différences :

Dimension	Mode interactif (claude)	Mode headless (claude -p)
Interface de discussion ?	✅ Oui, vous échangez par texte	❌ Non, s'arrête après le résultat
Supervision humaine	✅ Oui, vous êtes devant l'écran	❌ Non, exécution automatique par script
Supporte les pipelines ?	❌ Non	✅ Oui, lit stdin et supporte les redirections
Gestion des permissions	Demande votre accord avant d'agir	Définies à l'avance via --allowedTools / --permission-mode
Cas d'usage typiques	Développement quotidien, travail conversationnel	CI, traitements par lots, utilisation comme linter, intégration dans des scripts

💡 Résumé en une phrase : claude -p transforme Claude en un composant de la ligne de commande compatible avec les pipelines — cat ... | claude -p ... > out.txt pour enchaîner sur une chaîne de production, --output-format json combiné avec jq pour extraire des champs, --bare pour que les scripts démarrent plus rapidement et proprement ; pour les tâches non surveillées, veillez à configurer les permissions à l'avance à l'aide de drapeaux.

---

05 Codes de sortie : Comment un script sait si l'action a réussi ou échoué

Cette section est courte, mais elle est incontournable pour quiconque écrit des scripts.

Analogie : Le résultat d'un examen (admis / refusé) sous forme d'un nombre. Dans le monde de la ligne de commande, chaque commande renvoie après son exécution un « code de sortie (exit code) » — un nombre où 0 signifie le succès, et toute valeur différente de 0 indique un problème. Il n'est pas conçu pour les humains, mais pour le « script parent » : le script s'appuie sur ce nombre pour déterminer si l'étape a réussi et s'il doit continuer.

Vous pouvez vérifier le code de sortie de la commande qui vient de s'exécuter dans le terminal de cette manière :

claude auth status
echo $?

echo $? affiche le code de sortie de la commande précédente ($? étant la variable du shell stockant le code de sortie de la dernière commande exécutée).

Voici quelques-uns des codes de sortie explicitement mentionnés dans la documentation officielle dont vous pourriez avoir besoin :

Commande / Situation	Code de sortie	Signification
claude auth status Connecté	0	Actuellement connecté
claude auth status Non connecté	1	Actuellement non connecté
claude -p --max-turns N Limite de tours atteinte	Non 0 (erreur)	Limite de tours dépassée, arrêt avec erreur
stdin du pipeline dépasse 10 Mo	Non 0	Entrée trop volumineuse, renvoie une erreur explicite avec sortie non nulle
claude daemon status Superviseur non actif	1	Le processus de gestion de session en arrière-plan n'est pas en cours d'exécution

Comment cela s'utilise-t-il concrètement ? Par exemple, si vous voulez « d'abord confirmer la connexion dans une CI, et faire échouer directement le pipeline si non connecté », vous pouvez vous appuyer sur le code de sortie de claude auth status :

# 没登录（退出码非 0）就报错退出，不往下跑
claude auth status || { echo "未登录，终止"; exit 1; }

|| signifie « si la commande précédente échoue (code de sortie non nul), alors exécuter la partie suivante ». C'est une bonne pratique pour un script planifié quotidiennement — tester d'abord avec claude auth status au début : si le jeton (token) a expiré, le script s'arrête immédiatement pour donner l'alerte, plutôt que de continuer bêtement à s'exécuter à moitié pour s'apercevoir tardivement que l'utilisateur n'est pas connecté, évitant ainsi de perdre du temps.

Il suffit de retenir cette convention simple : 0 = succès, on continue ; non nul = erreur, on s'arrête. Les différentes commandes de Claude Code s'y conforment, vous pouvez donc vous fier à ce nombre pour évaluer le succès d'un script.

💡 Résumé en une phrase : Le code de sortie est le « bulletin de notes pour les scripts » — 0 pour le succès, non nul pour un problème ; claude auth status renvoie 0/1 pour indiquer l'état de connexion, le dépassement de --max-turns et de la limite de 10 Mo du pipeline renvoient un code non nul, que l'on peut intercepter dans un script avec $? ou ||.

---

06 Tableau complet des drapeaux : La page à consulter

Après avoir détaillé les options les plus fréquentes, cette section sert de filet de sécurité — nous avons regroupé dans un tableau les drapeaux que vous êtes susceptible de rencontrer au quotidien dans la documentation officielle, afin de pouvoir les consulter rapidement. Avec des dizaines de drapeaux, pas besoin de les apprendre par cœur ; gardez simplement cette page sous la main.

Un rappel important issu de la documentation officielle : claude --help ne liste pas tous les drapeaux. Ainsi, le fait qu'un drapeau n'apparaisse pas dans --help ne signifie pas qu'il est inutilisable — référez-vous toujours au guide de référence CLI officiel.

Je les ai classés par « cas d'usage » pour faciliter vos recherches :

Démarrage et sessions

Drapeau	Raccourci	Description
--print	-p	N'entre pas en mode interactif, affiche le résultat et quitte (base du mode headless)
--continue	-c	Continue la conversation la plus récente dans le répertoire actuel
--resume	-r	Reprend une session spécifique par ID ou par nom, ou affiche une liste pour choisir
--name	-n	Donne un nom d'affichage à la session pour pouvoir la reprendre plus tard avec --resume <nom>
--fork-session	—	Crée un nouvel ID de session lors de la reprise, sans réutiliser le précédent (utilisé avec -r/-c)
--session-id	—	Spécifie un ID de session (doit être un UUID valide)

Modèles et permissions

Drapeau	Description
--model	Quel modèle utiliser pour cette session (alias sonnet/opus ou nom complet), écrase la valeur par défaut
--fallback-model	Bascule automatiquement vers le modèle spécifié si le modèle par défaut est surchargé ou indisponible (s'applique à -p et aux sessions en arrière-plan, ignoré en mode interactif)
--permission-mode	Mode de permission de départ (default/acceptEdits/plan/auto/dontAsk/bypassPermissions)
--allowedTools	Outils autorisés directement sans demande de confirmation
--disallowedTools	Règles de refus d'outils
--dangerously-skip-permissions	Ignore toutes les demandes de permission (équivalent à --permission-mode bypassPermissions, à utiliser avec prudence)

Répertoires et configuration

Drapeau	Description
--add-dir	Accorde en plus des droits de lecture/écriture sur certains répertoires (accorde uniquement l'accès aux fichiers, ne charge pas les configurations associées)
--settings	Spécifie un fichier JSON de paramètres ou un JSON en ligne pour écraser les clés correspondantes de cette session
--setting-sources	Quelles sources de paramètres charger (user/project/local)
--mcp-config	Charge le serveur MCP à partir d'un fichier ou d'une chaîne JSON
--bare	Mode minimal : ignore les hooks, les skills, les plugins, les MCP, la mémoire et la découverte automatique de CLAUDE.md pour un démarrage plus rapide

Sortie et contrôle headless (la plupart ne s'applquent qu'en mode -p)

Drapeau	Description
--output-format	Format de sortie : text (par défaut) / json / stream-json
--input-format	Format d'entrée : text / stream-json
--max-turns	Limite le nombre maximal de tours, s'arrête avec erreur si dépassé (sans limite par défaut)
--max-budget-usd	S'arrête si le coût API dépasse ce montant en dollars
--verbose	Journalisation détaillée, affiche la sortie complète de chaque étape
--append-system-prompt	Ajoute un texte personnalisé à la fin de l'invite système par défaut
--system-prompt	Remplace l'intégralité de l'invite système par défaut par un texte personnalisé

Divers

Drapeau	Raccourci	Description
--version	-v	Affiche le numéro de version
--ide	—	Se connecte automatiquement au démarrage s'il y a exactement un IDE disponible
--debug	—	Active le mode débogage, peut être filtré par catégorie (par ex. "api,mcp")

Ce tableau couvre la grande majorité des drapeaux dont vous aurez besoin au départ. Pour consulter le catalogue complet (contenant des dizaines d'autres options spécifiques liées aux sessions d'arrière-plan, aux équipes d'agents ou au contrôle à distance), reportez-vous à la page de référence CLI officielle — c'est le véritable manuel complet, cette section n'étant qu'un guide de consultation rapide.

💡 Résumé en une phrase : Il est plus rapide de rechercher les drapeaux par catégories (« démarrage/session », « modèles/permissions », « répertoires/configuration », « sortie headless », « divers ») ; --help est incomplet, référez-vous au guide de référence CLI officiel ; ce tableau couvre l'essentiel, les cas marginaux sont à chercher dans la documentation officielle.

---

07 Mise en pratique : Connecter claude -p aux pipelines de la ligne de commande

Regarder des tableaux ne suffit pas pour maîtriser le sujet, il faut réellement faire tourner le mode headless. Les étapes ci-dessous se déroulent entièrement dans le terminal, sans entrer dans une interface interactive — pour expérimenter directement ce que l'on ressent en utilisant « Claude comme composant de ligne de commande ». Nous utiliserons des exemples minimaux ne dépendant d'aucun projet existant complexe.

Ces étapes nécessitent une connexion Internet et consommeront un peu de votre quota (chaque appel à -p constitue une requête réelle). Si la connexion échoue, assurez-vous que votre configuration réseau le permet.

Étape 1 : Un appel -p des plus basiques

Choisissez un répertoire au hasard et tapez dans votre terminal (pas dans une session interactive claude) :

claude -p "用一句话说明 git rebase 和 git merge 的核心区别"

Résultat attendu : Le terminal affiche directement la réponse puis se ferme, sans faire apparaître l'interface de discussion. Si le résultat s'affiche et que l'invite du terminal réapparaît immédiatement, le mode headless fonctionne.

Étape 2 : Le connecter à un pipeline pour lui injecter des données

Créez un petit fichier pour servir de données d'entrée, puis passez-le à Claude par pipeline :

printf 'def add(a, b):\n    return a - b\n' > buggy.py
cat buggy.py | claude -p "这段代码有个 bug，一句话指出来"

Résultat attendu : Claude lit le code injecté par le pipeline et répond par une phrase similaire à « le nom de la fonction est add, mais elle effectue en réalité une soustraction (a - b) ». Le fait qu'il réponde sur le contenu injecté confirme que le pipeline fonctionne — il n'a utilisé aucun outil pour lire le fichier, la matière lui a été fournie directement par cat.

Étape 3 : Demander une sortie structurée et utiliser jq pour extraire des champs

claude -p "用一句话介绍 Python 是什么语言" --output-format json

Résultat attendu : Cette fois, la sortie n'est pas du texte brut mais un gros bloc JSON, contenant des champs comme result (le texte du résultat), session_id, total_cost_usd, etc. Si jq est installé sur votre machine, essayez cette commande pour extraire uniquement le résultat :

claude -p "用一句话介绍 Python" --output-format json | jq -r '.result'

Résultat attendu : Cette fois-ci, seule la ligne de texte propre du résultat est affichée, l'enveloppe JSON ayant été retirée par jq. C'est la méthode standard pour ne récupérer « que la réponse souhaitée, sans les métadonnées » dans un script.

Étape 4 : Utiliser le code de sortie pour déterminer le succès ou l'échec

claude auth status
echo $?

Résultat attendu : Si vous êtes connecté, echo $? affichera 0 ; sinon, il affichera 1. Ce nombre est l'indicateur utilisé par un script pour décider s'il doit continuer ou non — c'est exactement ce qu'intercepte la commande claude auth status || ... de la section 05.

En réussissant ces quatre étapes, vous venez de dérouler par vous-même la chaîne headless complète : « appel simple → alimentation par pipeline → sortie structurée filtrée par jq → décision par code de sortie ». À l'avenir, intégrer Claude dans un script, une CI ou une tâche planifiée ne sera rien d'autre qu'une combinaison de ces briques.

💡 Résumé en une phrase : Validez le mode headless en quatre étapes — -p brut pour le résultat, pipeline cat | claude -p pour alimenter, --output-format json | jq pour extraire les champs, et auth status + $? pour évaluer le succès ; l'assemblage de ces quatre briques forme la base de toute automatisation.

---

08 Résumé

Ce chapitre a détaillé de fond en comble la commande claude que vous tapez au quotidien — passant de « taper simplement claude pour ouvrir l'interface » à « maîtriser parfaitement les commandes, drapeaux, pipelines et codes de sortie ».

Récapitulons les points clés :

Votre objectif	Ce qu'il faut utiliser	Points clés
Distinguer commandes et drapeaux	La commande est une sous-action, le drapeau est une case à cocher	update/mcp sont des commandes, -p/--model sont des drapeaux
Démarrer / Reprendre	claude / -c / -r	-c reprend la plus récente, -r reprend une session précise, pour remédier à l'amnésie de session
Obtenir le résultat sans mode interactif	-p (--print)	Base du mode headless, utilisé pour les scripts et les pipelines
Changer temporairement de modèle / de permission	--model / --permission-mode	Écrase la configuration par défaut pour cette session uniquement
L'intégrer dans la ligne de commande	Pipeline + --output-format json + jq	cat ... | claude -p ... | jq pour enchaîner sur une chaîne
Vérifier le succès dans un script	Code de sortie	0 pour le succès, non nul pour une erreur, à intercepter avec $? ou ||
Rechercher un drapeau	Le tableau de la section 06 / la documentation officielle	--help est incomplet, référez-vous au guide de référence CLI officiel

Vous devriez désormais être capable de : décortiquer n'importe quelle ligne claude xxx --yyy pour identifier « ce qui est une commande, ce qui est un drapeau, et ce que chacun fait » ; savoir s'il faut utiliser -c ou -r pour reprendre une conversation précédente ; utiliser -p combiné à des pipelines et à --output-format json pour intégrer Claude dans un script, et vous appuyer sur le code de sortie pour vérifier si l'étape a réussi ; et en cas de drapeau inconnu, savoir dans quel tableau chercher tout en gardant en tête que --help n'est pas exhaustif et qu'il faut se référer à la documentation officielle. Cette maîtrise de la ligne de commande est le point de bascule pour transformer Claude Code d'un « simple espace de discussion » en « un composant orchestrable au sein de votre flux de travail de développement ».

L'utilisateur du début qui ne faisait que taper claude peut désormais, après avoir appris -p et les pipelines, automatiser sous forme de scripts plusieurs vérifications qu'il effectuait manuellement chaque jour — donnant l'impression d'avoir soudainement déplacé Claude du rôle de « copilote » à celui de « chaîne de production ». C'est exactement l'objectif de ce chapitre.

---

Le prochain chapitre 35 « Contrôle et modes » — dans ce chapitre, j'ai répété à plusieurs reprises que --permission-mode permettait de choisir entre plan, acceptEdits et bypassPermissions, mais je n'ai pas encore détaillé le tempérament de chaque mode, le nombre de fois où Claude vous demandera confirmation avant d'agir, et les situations propices pour basculer vers l'un ou l'autre. Le prochain chapitre décortiquera précisément ces différents modes, tout en expliquant comment basculer à la volée en cours de session à l'aide de raccourcis clavier. Imaginez : pour une même demande de modification de fichiers par Claude, « vous demander confirmation pour chaque fichier modifié » par rapport à « tout modifier en arrière-plan puis vous présenter le résultat global » peut changer radicalement votre efficacité et votre sentiment de sécurité — nous verrons comment ajuster ce curseur dans le prochain chapitre.

---

Lectures recommandées

• Présentation de Claude Code
• Configuration de l'API : abonnement ou clé API, comment choisir et basculer
• Checkpoints (Points de contrôle) : Un filet de sécurité pour revenir en arrière à tout moment