La CLI claude : les flags qui changent le résultat

Intermédiaire

Dernière vérification : 2026-10-07.

Chaque commande, flag, valeur par défaut et version minimale ci-dessous provient de la référence CLI officielle, consultée le 2026-10-07. Les flags apparaissent et changent d'une version à l'autre, et la référence précise que claude --help ne liste pas tous les flags — un flag absent de --help n'est donc pas forcément absent de votre build. Fiez-vous à la référence, pas au texte d'aide, et vérifiez votre version avec claude -v.

Vérifiez auprès de la source officielle.

La plupart des gens apprennent trois choses sur la ligne de commande de Claude Code — claude, claude -c et claude -p — et s'arrêtent là. C'est un bon endroit pour s'arrêter si vous l'utilisez toujours assis devant. Dès que vous placez Claude Code dans un script, un job de CI, une file d'attente en arrière-plan ou entre les mains d'un collègue, les flags cessent d'être des commodités et font la différence entre une exécution qui coûte un dollar et une qui reste bloquée une heure.

Cette page n'est pas une seconde copie du tableau de référence. C'est l'ordre dans lequel apprendre la surface, les flags qui changent vraiment ce qui se passe, et les quatre pièges qui coûtent du temps réel.

What you'll learn

• Les six types de session que vous pouvez démarrer, et quel flag choisit chacun
• Le contrat à cinq flags qui rend une exécution sans surveillance bornée, avec réponse possible et analysable
• Pourquoi modifier --append-system-prompt puis relancer --continue semble ne rien faire — la règle du prompt enregistré
• En quoi --bare, --safe-mode et --restricted diffèrent, et lequel choisir selon le cas
• Piloter des sessions en arrière-plan depuis le shell : agents, attach, logs, respawn, rm, daemon
• Les paires de flags que l'on confond : --tools vs --allowedTools vs --disallowedTools

Commencez par la question : de quel type de session s'agit-il ?

Toutes les autres décisions en découlent. Claude Code peut démarrer six choses sensiblement différentes, et le flag qui en choisit une est généralement la première chose que vous tapez.

Vous voulez	Flag	Cela vous donne
Une conversation que vous suivez	(aucun)	Une session interactive dans ce terminal
Une réponse, puis la sortie	-p / --print	Une exécution non interactive, sortie sur stdout
Un travail qui survit à ce terminal	--bg / --background	Une session en arrière-plan ; elle affiche son ID et comment la gérer
Une branche isolée pour expérimenter	-w / --worktree	Un worktree git sous <repo>/.claude/worktrees/<name>
Un travail sur les machines d'Anthropic	--cloud	Une session cloud, ou un suivi mis en file dans une session existante
Piloter cette session depuis votre téléphone	--rc / --remote-control	Une session interactive également contrôlable depuis claude.ai ou l'app Claude

Deux d'entre elles sont incompatibles : --bg et -p s'excluent mutuellement, car l'une rend la main immédiatement et l'autre attend une réponse. Si vous voulez lancer en arrière-plan une commande shell plutôt qu'une session Claude, associez --bg à --exec :

Lancer la suite de tests comme un job en arrière-plan, pas comme une session Claude

claude --bg --exec 'pytest -x'

Et --bg vérifie la confiance accordée à l'espace de travail pour le répertoire avant de démarrer — une session en arrière-plan dans un dépôt non approuvé échoue donc dès le départ plutôt qu'à mi-chemin.

Le contrat à cinq flags pour les exécutions sans surveillance

C'est la chose la plus utile de cette page. Une exécution claude -p sans surveillance peut mal tourner de trois façons qu'une session interactive ne connaît tout simplement pas : elle peut se bloquer sur des demandes de permission auxquelles personne n'est là pour répondre, elle peut boucler bien plus longtemps que prévu, et elle peut émettre de la prose alors que votre script attendait des données. Cinq flags referment ces trois risques.

Guided walkthrough1 of 5

1. `claude -p "query"` affiche la réponse puis quitte. Tout ce qui suit ne vaut qu'en mode print ; ce flag est donc la porte d'entrée de tout le reste.

Une étape de CI qui ne peut ni se bloquer, ni boucler à l'infini, ni trop dépenser

claude -p "Review the staged diff and list bugs" \
--permission-prompts none \
--allowedTools "Read" "Bash(git diff *)" \
--max-turns 6 \
--max-budget-usd 2.00 \
--output-format json

--max-budget-usd est une estimation, pas votre facture

• Claude Code compare le plafond à sa propre estimation de coût côté client, qui peut différer de ce qui vous est facturé.
• Quand vous reprenez une conversation avec --continue ou --resume, les totaux restaurés des exécutions précédentes ne comptent pas dans le plafond — trois exécutions reprises sous un plafond de 2 $ peuvent donc dépenser plus de 2 $ au total.
• Voyez-le comme un disjoncteur pour une exécution. Pour un vrai plafond sur un compte ou un projet entier, voir Hard Spend Caps.

Pour toute la posture à adopter quand on laisse une exécution se dérouler sans humain — quoi autoriser, quoi masquer, quoi journaliser — voir Durcir les exécutions autonomes et Mode headless et Agent SDK. Pour les plafonds au niveau du fournisseur, Hard Spend Caps.

La famille du prompt système, et le piège qu'elle contient

Cinq flags façonnent le prompt système. Quatre en fixent le texte ; le cinquième décide si la conversation conserve le texte avec lequel elle a démarré.

Flag	Ce qu'il fait
--system-prompt	Remplace tout le prompt par défaut par votre texte
--system-prompt-file	Le remplace par le contenu d'un fichier
--append-system-prompt	Ajoute votre texte au prompt par défaut
--append-system-prompt-file	Ajoute le contenu d'un fichier au prompt par défaut
--system-prompt-snapshot	off reconstruit le prompt à chaque requête ; on (la valeur par défaut) réutilise celui qui a été enregistré

Choisir entre ajouter et remplacer revient à choisir une identité. Ajouter conserve les consignes d'outils, les instructions de sécurité et les conventions de code par défaut de Claude Code, et superpose vos règles — idéal pour des instructions propres à une exécution, un format de sortie ou un contexte de projet. Remplacer abandonne tout cela, y compris les consignes d'outils, ce qui ne se justifie que lorsque la surface n'est vraiment pas un assistant de code : un agent non-code dans un pipeline que personne ne surveille. Si vous remplacez, vous êtes responsable de tout ce dont la tâche a encore besoin.

Vous pouvez les combiner. Passer un flag d'ajout avec un flag de remplacement remplace la valeur par défaut puis ajoute votre texte. Depuis la v2.1.283, vous pouvez aussi passer un flag avec sa propre forme fichier — --append-system-prompt et --append-system-prompt-file — et Claude Code utilise les deux, le contenu du fichier venant en premier quel que soit l'ordre tapé.

Le piège : une conversation reprise réutilise le prompt avec lequel elle est née

• Claude Code construit le prompt système une fois, à la première requête d'une conversation, et l'enregistre dans la session.
• Tant que la conversation n'est pas compactée, chaque requête suivante utilise ce prompt enregistré — y compris après --resume ou --continue.
• Vous modifiez donc votre texte --append-system-prompt, relancez claude --continue, et rien ne change. Le flag n'est pas cassé ; la conversation utilise encore l'enregistrement.
• Le nouveau texte prend effet une fois la conversation compactée, ou dans une toute nouvelle conversation.
• Pour itérer sur la formulation d'une exécution --continue à l'autre, passez --system-prompt-snapshot off et le prompt est reconstruit à chaque requête. Nécessite la v2.1.257 ou ultérieure.

Il reste une astuce utile dans un prompt de remplacement qui mêle instructions stables et contexte propre à chaque exécution. Placez entre les deux une ligne contenant uniquement __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ : Claude Code coupe à la première ligne de ce type et la supprime, de sorte que la partie du dessus reste en cache pendant que celle du dessous change. Nécessite la v2.1.275 ou ultérieure. Pourquoi cela compte pour votre facture, c'est le sujet de Prompt Caching.

Et pour les charges de travail scriptées multi-utilisateurs, --exclude-dynamic-system-prompt-sections déplace le contexte propre à l'utilisateur, comme l'emplacement de la mémoire automatique, du prompt système vers le premier message utilisateur — la même tâche sur des machines différentes partage ainsi un seul préfixe en cache. Il ne s'applique qu'au prompt par défaut et est ignoré quand vous définissez --system-prompt ou --system-prompt-file.

Trois flags qui désactivent des choses, et ce n'est pas la même chose

On les prend volontiers l'un pour l'autre, puis on s'étonne que le symptôme ne bouge pas. Ils résolvent trois problèmes différents.

	--bare	--safe-mode	--restricted
Le problème qu'il résout	Le démarrage est trop lent pour un appel scripté	Ma configuration est cassée et je ne sais pas quelle partie	Un harnais d'évaluation ne doit pas toucher cette machine partagée
CLAUDE.md, skills, commandes, sous-agents, plugins, MCP, mémoire automatique	Non découverts	Non chargés	Seuls les paramètres gérés et --settings sont chargés
Outils intégrés	Bash, lecture de fichier, édition de fichier	Fonctionnent normalement	Les outils d'exécution de commandes/code et WebFetch sont retirés sauf s'ils sont nommés individuellement dans --tools
Accès aux fichiers	Normal	Normal	Confiné aux répertoires de travail
bypassPermissions	Autorisé	Autorisé	Refusé
Politique gérée	S'applique	S'applique toujours, y compris les hooks de politique et la ligne d'état	S'applique
Effet de bord	Définit CLAUDE_CODE_SIMPLE	Définit CLAUDE_CODE_SAFE_MODE	Refuse de créer des sessions cloud

Lisez le tableau comme une progression d'intentions : --bare vise la vitesse, --safe-mode le diagnostic, --restricted le confinement. Un détail utile : les skills d'un répertoire que vous passez avec --add-dir se chargent quand même sous --bare, ce qui permet de conserver exactement une capacité dans une exécution par ailleurs dépouillée.

--safe-mode est le premier réflexe quand quelque chose se comporte mal et que vous ne savez pas si c'est Claude Code ou votre propre configuration — y compris quand vous cherchez à savoir si une personnalisation déclenche le repli automatique de modèle. Associez-le à claude doctor, qui affiche des diagnostics d'installation et de paramètres en lecture seule sans démarrer de session. (La commande /doctor dans la session est autre chose : elle peut aussi appliquer des correctifs.) Plus de débogage par symptôme dans Dépanner Claude Code. --restricted nécessite la v2.1.248 ou ultérieure.

Piloter des sessions en arrière-plan depuis le shell

Dès que vous démarrez des sessions avec --bg, le terminal devient un plan de contrôle. Tout le cycle de vie a sa commande, et rien n'exige d'ouvrir l'interface interactive.

Guided walkthrough1 of 6

1. Ouvre la vue des agents pour surveiller et répartir des sessions en arrière-plan en parallèle. Pour les scripts, `--json` affiche les sessions actives sous forme de tableau JSON, et `--json --all` inclut celles qui sont terminées. `--cwd <path>` restreint aux sessions démarrées sous ce répertoire. Ouvrir la vue elle-même demande un terminal interactif ; la forme JSON, non.

Le pendant depuis l'intérieur d'une session — comment le travail passe en arrière-plan, et ce qui est conservé quand c'est le cas — se trouve dans Tâches en arrière-plan, /loop et planification.

Les paires de flags que l'on comprend de travers

Six confusions à prévenir

• --tools restreint quels outils intégrés existent. --allowedTools dit quels appels sautent la demande de permission. --disallowedTools refuse des appels. Ce sont trois métiers différents, et passer le mauvais est la cause la plus fréquente de « pourquoi me redemande-t-il encore ».
• --tools n'affecte pas du tout les outils MCP. Pour les retirer aussi, ajoutez --disallowedTools "mcp__*".
• Un nom seul dans --disallowedTools retire l'outil du contexte de Claude ; une règle ciblée comme Bash(rm *) laisse l'outil disponible et ne refuse que les appels correspondants.
• --dangerously-skip-permissions démarre en bypassPermissions. --allow-dangerously-skip-permissions ajoute seulement ce mode au cycle Shift+Tab, pour que vous puissiez démarrer en plan mode et changer plus tard. Le second est presque toujours ce que vous vouliez vraiment.
• --add-dir accorde l'accès aux fichiers, mais Claude Code ne découvre pas la plupart de la configuration .claude/ de ces répertoires. Ajouter un répertoire n'est pas adopter sa configuration.
• --desktop ne prend ni prompt ni autres flags à part --verbose et les flags --debug, car l'application Desktop démarre elle-même la session. Nécessite la v2.1.285 ou ultérieure.

Un petit détail de confort : si vous faites une faute de frappe dans une sous-commande, Claude Code suggère la plus proche et quitte sans démarrer de session — claude udpate affiche Did you mean claude update? au lieu d'ouvrir une conversation que vous ne vouliez pas.

Vérifiez vos acquis

Check yourself

0/3

1. 1Votre job nocturne exécute `claude -p` dans une application Agent SDK dont le callback `canUseTool` interroge une personne, et la nuit il reste bloqué jusqu'au timeout. Quel flag manque le plus probablement ?
2. 2Vous modifiez votre texte --append-system-prompt, relancez `claude --continue`, et le comportement est inchangé. Pourquoi ?
3. 3Une personnalisation casse votre session et vous ne savez pas laquelle. Quel flag l'isole tout en laissant vos outils et vos permissions fonctionner normalement ?

Appuyez sur Entrée ou Espace pour retourner la carte. Utilisez les flèches gauche et droite pour naviguer entre les cartes.Terme affiché.

1 / 8

Key takeaways

• Choisissez d'abord le type de session — le flag qui le fait contraint tous les autres flags que vous pouvez passer.
• Une exécution sans surveillance a besoin de cinq flags, pas d'un seul : -p, --permission-prompts none, --max-turns, --max-budget-usd et un format de sortie structuré.
• Voyez --max-budget-usd comme un disjoncteur pour une exécution, pas comme un plafond de facture. C'est une estimation côté client et les totaux repris lui échappent.
• Les conversations enregistrent leur prompt système à la première requête. Si une modification du prompt semble ignorée, c'est pour cela — utilisez --system-prompt-snapshot off pendant que vous itérez.
• --bare, c'est la vitesse ; --safe-mode, le diagnostic ; --restricted, le confinement. Choisir le mauvais fait perdre un après-midi.
• --help est incomplet par conception. La référence CLI fait foi, et les versions minimales comptent — vérifiez claude -v avant d'accuser un flag.

Suite

• Mode headless et Agent SDK — que construire quand un simple appel -p ne suffit plus
• settings.json : le système de configuration — le foyer durable des flags que vous retapez sans cesse
• Dépanner Claude Code — débogage par symptôme, en commençant par --safe-mode

Partager cette page

• X
• LinkedIn
• Reddit
• Hacker News