Mode headless, formats de sortie et tâches de fond
Le mode headless exécute Claude Code sans interface interactive avec -p, --output-format détermine si la sortie reste du texte ou devient un objet JSON exploitable par un script, avec le coût total inclus, et run_in_background laisse une commande longue continuer sans bloquer la conversation.
Le mode headless exécute Claude Code sans interface interactive, en une seule commande qui rend son résultat et s'arrête. Le drapeau -p (ou --print) déclenche ce mode, avec un prompt donné en argument.
claude -p "Résume les fichiers modifiés dans ce dépôt" --output-format json
Trois formats de sortie pour trois usages
Le paramètre --output-format accepte trois valeurs. text, la valeur par défaut, rend une réponse en langage naturel destinée à un humain. json rend un seul objet structuré, avec le résultat, l'identifiant de session et le coût total en dollars ainsi qu'une répartition par modèle. stream-json rend la même information en JSON Lignes, un objet par ligne, utile quand un programme veut réagir avant la fin complète de l'exécution. Un drapeau --bare saute la découverte automatique des hooks, skills, commandes personnalisées, sous-agents, plugins, serveurs MCP, mémoire automatique et fichiers CLAUDE.md au démarrage, ce qui accélère le lancement, et la documentation officielle le recommande pour les appels scriptés. Contrepartie : le mode bare ne lit jamais les identifiants OAuth ni le trousseau du système, donc un script qui l'utilise doit poser la variable ANTHROPIC_API_KEY pour s'authentifier auprès de l'API Anthropic.
Un appel minimal quand --bare est exclu
Sur un abonnement, --bare ne sert pas, puisqu'il ne lit pas la connexion. On retire alors les sources une à une, avec des drapeaux que claude --help liste à la version 2.1.325 :
claude -p "Réponds par un mot" --output-format json \
--system-prompt "Réponds en un mot." --tools "" \
--strict-mcp-config --disable-slash-commands --no-session-persistence
Le prompt système par défaut est remplacé, les outils intégrés sont retirés, skills et commandes sont désactivées et la session n'est pas enregistrée. L'aide ne dit pas que ces drapeaux ignorent les fichiers CLAUDE.md : seul --bare le dit. Mesurez : comparez les champs input_tokens et cache_creation_input_tokens de l'objet usage entre l'appel par défaut et l'appel minimal.
Laisser une commande longue tourner sans bloquer
Une commande longue lancée par l'outil Bash de Claude Code peut demander run_in_background: true plutôt que d'attendre sa fin. L'outil rend alors immédiatement un identifiant de tâche, la commande continue en arrière plan, et sa sortie se relit ensuite avec l'outil Read. Le raccourci Ctrl+B pendant qu'une commande tourne fait la même bascule à la main, et la commande /tasks liste et arrête les tâches en cours.
Les tâches exposées par les serveurs MCP passent aussi par /tasks. Depuis la version 2.1.325, Claude est informé lorsqu'une de ces tâches attend votre réponse, et il peut vous renvoyer vers /tasks pour la voir et y répondre.
Ce basculement se produit aussi tout seul : une commande qui atteint son délai d'expiration sans avoir fini passe automatiquement en tâche de fond plutôt que d'être coupée net, sauf si elle commence par sleep. La variable CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 et le mode --bare désactivent la bascule : la commande s'arrête alors à son délai (référence des outils, relue le 2026-11-16). L'identifiant de session que --output-format json rend explicitement est le même que celui que reprend chaque geste rapide du terminal avec --resume.
Ce que le mode headless change en octobre 2026
Depuis octobre 2026, claude -p et l'Agent SDK sans mode de permission configuré démarrent en mode default : un appel qui demande une approbation y est refusé, sauf si une règle d'autorisation, un hook ou l'option --permission-prompt-tool l'accorde. Un script qui modifie des fichiers doit donc passer --permission-mode ou porter une règle. Par ailleurs, la limite de durée des commandes de fond ne s'applique plus qu'aux sessions sans surveillance (-p, SDK, CI, cloud) : une session de terminal, de bureau ou de VS Code n'a plus de limite.
Le code de sortie suit ces refus. En mode auto, quand les actions de claude -p sont refusées faute de contrôle de sécurité disponible, la commande sort avec le code 1, en sortie texte comme en JSON (journal, version 2.1.319) ; elle sortait auparavant avec 0. Un script qui teste le code de sortie voit donc l'échec, là où un ancien script pouvait croire à un succès.
D'une commande headless à une sortie exploitable par un script
Un développeur lance claude -p avec --output-format json dans un pipeline de déploiement, et le script du pipeline récupère le champ total_cost_usd du résultat pour l'ajouter au tableau de bord de coûts.
Écrivez en une phrase ce que cette situation établit, et en une phrase ce qu'elle n'établit pas.
Ce que cela établit : Ce lancement établit que le script peut lire un coût total sans analyser du texte libre, puisque le format json le rend disponible comme un champ structuré.
Ce que cela n’établit pas : Il n'établit pas que ce coût correspond à l'ensemble des dépenses du pipeline de déploiement, puisque d'autres étapes du pipeline peuvent engager des coûts qui n'ont rien à voir avec cet appel à Claude Code.
Les trois calibrages faux les plus courants
- Trop large Le format json expose désormais tous les coûts de n'importe quel outil utilisé dans le pipeline de déploiement, pas seulement celui de cet appel à Claude Code.
- Trop étroit Ce lancement ne prouve rien du tout, puisqu'un seul appel a été observé dans un seul pipeline.
- À côté Ce lancement montre que le pipeline de déploiement termine désormais plus vite qu'avant l'ajout de cet appel à Claude Code.
- Un script en claude -p sans mode configuré démarre en default et voit refuser tout appel qui demande une approbation : passez --permission-mode ou une règle.
- --output-format json rend un objet unique portant le résultat, l'identifiant de session et le coût total en dollars avec sa répartition par modèle.
- --bare saute la découverte automatique des hooks, skills et fichiers de contexte au démarrage, un gain de vitesse recommandé pour les appels scriptés, mais il ne lit jamais les identifiants OAuth ni le trousseau, ANTHROPIC_API_KEY devient donc nécessaire ; sur abonnement, un appel minimal se compose à la main avec --system-prompt, --tools et --strict-mcp-config.
- run_in_background rend immédiatement un identifiant de tâche et laisse une commande longue continuer ; une commande qui atteint son délai bascule seule en tâche de fond, sauf si elle commence par sleep, et CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 ou --bare désactivent la bascule. Une tâche MCP en attente de réponse est signalée à Claude, qui peut vous orienter vers /tasks.
- En mode auto, claude -p sort avec le code 1 quand ses actions sont refusées faute de contrôle de sécurité disponible : testez le code de sortie dans vos scripts.
Lancez depuis votre terminal claude -p "un mot au hasard" --output-format json sur un dossier ne contenant aucune donnée sensible, et repérez dans la sortie les champs session_id et total_cost_usd.
Chaque affirmation datable de cette leçon renvoie ici au texte public qui la porte. Une source qui ne s’ouvre pas ne prouve rien.
- Claude Code, mode headless, formats de sortie et drapeau --bare consultée le 2026-09-02
- Claude Code, référence des outils, run_in_background et bascule automatique en tâche de fond consultée le 2026-09-02
- Claude Code, modes de permission : claude -p démarre en default consultée le 2026-10-24
- Journal de Claude Code : limite des commandes de fond en session sans surveillance consultée le 2026-10-24
- Journal de Claude Code 2.1.325 : tâches MCP en attente de réponse et renvoi vers /tasks consultée le 2026-11-14
- Claude Code, référence de la ligne de commande : drapeaux --bare, --tools, --strict-mcp-config consultée le 2026-11-16
- Journal de Claude Code 2.1.319 : claude -p sort avec le code 1 en mode auto quand les actions sont refusées consultée le 2026-11-16