Aller au contenu
Mastering Claude

Le cours175 leçons

Accueil / Gestes courants

Gestes courants9 minApplication

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.

Figure 1

D'une commande headless à une sortie exploitable par un script

01
Entrée en mode headless
Le drapeau -p envoie un prompt à Claude Code sans ouvrir d'interface interactive.
02
Exécution non interactive
Claude Code traite la demande seul, sans attendre de réponse humaine entre les étapes.
03
Sortie choisie
Le paramètre --output-format détermine si le résultat sort en texte, en un objet JSON unique, ou en JSON Lignes en flux.
04
Script lit le résultat
Un programme externe récupère la sortie structurée, avec le coût total et l'identifiant de session, sans analyser du texte libre.
05
Commande longue en tâche de fond
Si une étape dure trop longtemps, run_in_background la fait continuer pendant que le script reste libre de la suite.
La séquence montre comment une demande envoyée en mode headless traverse une exécution non interactive jusqu'à une sortie structurée qu'un script peut lire, avec un basculement possible en tâche de fond si une étape dure trop longtemps.
Calibrez vous-même

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 qu’il faut retenir
  • 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.
À faire maintenant

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.

Vérifier à la source

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.