SpyBara
Go Premium

headless.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 121 additions and 28 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

Exécuter Claude Code par programmation

Utilisez l'Agent SDK pour exécuter Claude Code par programmation depuis la CLI, Python ou TypeScript.

L'Agent SDK vous donne accès aux mêmes outils, boucle d'agent et gestion du contexte qui alimentent Claude Code. Il est disponible en tant que CLI pour les scripts et CI/CD, ou en tant que packages Python et TypeScript pour un contrôle programmatique complet.

Pour exécuter Claude Code en mode non interactif, passez -p avec votre prompt et les options CLI dont vous avez besoin :

claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"

Cette page couvre l'utilisation de l'Agent SDK via la CLI (claude -p). Pour les packages SDK Python et TypeScript avec sorties structurées, callbacks d'approbation d'outils et objets de message natifs, consultez la documentation complète de l'Agent SDK.

Utilisation basique

Ajoutez le flag -p (ou --print) à n'importe quelle commande claude pour l'exécuter de manière non-interactive. Toutes les options CLI ne se combinent pas avec -p. Claude Code rejette --bg, et rejette --cloud avec une description de tâche, avec une erreur nommant le conflit ; --cloud avec un ID de session et -p à la place met en file d'attente un message dans cette session cloud et se termine. Les options que vous combinerez souvent avec -p incluent :

Cet exemple pose une question à Claude sur votre base de code et affiche la réponse :

claude -p "What does the auth module do?"

Claude Code se termine avec le code 0 en cas de succès et un code non-zéro quand l'exécution échoue, donc vos scripts peuvent se brancher sur le code de sortie. Si vous passez un flag invalide, Claude Code signale l'erreur sur stderr avant le démarrage de l'exécution. Quand une défaillance se produit à l'intérieur de l'exécution, comme une authentification manquante, Claude Code affiche la défaillance comme le résultat sur stdout.

Démarrer plus rapidement avec le mode bare

Ajoutez --bare pour réduire le temps de démarrage en ignorant la découverte automatique des hooks, skills, commandes personnalisées, sous-agents, plugins, serveurs MCP, mémoire automatique et CLAUDE.md. Sans cela, claude -p charge le même contexte qu'une session interactive, y compris tout ce qui est configuré dans le répertoire de travail ou ~/.claude.

Le mode bare est utile pour CI et les scripts où vous avez besoin du même résultat sur chaque machine. Un hook dans le ~/.claude d'un coéquipier ou un serveur MCP dans le .mcp.json du projet ne s'exécutera pas, car le mode bare ne les lit jamais. Un répertoire que vous nommez avec --add-dir est une exception partielle : le mode bare charge les skills de son dossier .claude/skills/, mais ignore toujours ses dossiers .claude/commands/ et .claude/agents/. Skills from additional directories couvre ce qui se charge et ce qui ne se charge pas.

Sans --bare, une session -p exécute les hooks dans le .claude/settings.json d'un projet et connecte les serveurs dans son .mcp.json, même dans un dossier que vous n'avez jamais approuvé. Une session -p n'affiche aucune boîte de dialogue de confiance d'espace de travail et aucune invite d'approbation par serveur. What runs before you trust a folder couvre chaque type de contenu de référentiel sous -p et comment le garder à l'écart.

Cet exemple exécute une tâche de résumé ponctuelle en mode bare et pré-approuve l'outil Read pour que l'appel se termine sans invite de permission. Définissez ANTHROPIC_API_KEY avant de l'exécuter, car le mode bare n'utilise pas votre connexion d'abonnement :

claude --bare -p "Summarize README.md" --allowedTools "Read"

En mode bare, Claude Code ne lit jamais les identifiants OAuth ou le trousseau système. Pour l'API Anthropic, définissez ANTHROPIC_API_KEY dans l'environnement, avec une clé créée dans la Claude Console, ou fournissez un apiKeyHelper dans le JSON --settings. Amazon Bedrock, Google Cloud's Agent Platform et Microsoft Foundry continuent à lire leurs propres identifiants de fournisseur comme d'habitude.

En mode bare, Claude a accès aux outils Bash, lecture de fichier et modification de fichier. Passez tout contexte dont vous avez besoin avec un flag :

Pour charger Utilisez
Ajouts de prompt système --append-system-prompt, --append-system-prompt-file
Paramètres --settings <file-or-json>
Serveurs MCP --mcp-config <file-or-json>
Agents personnalisés --agents <json>
Un plugin --plugin-dir <path>, --plugin-url <url>

Tâches en arrière-plan à la sortie

Si Claude démarre une tâche Bash en arrière-plan lors d'une exécution claude -p, par exemple un serveur de développement ou une compilation en surveillance, ce shell est terminé environ cinq secondes après que Claude ait retourné son résultat final et que stdin ait été fermé. La période de grâce permet à une tâche qui se termine juste après le résultat de livrer quand même sa sortie.

Si Claude démarre un sous-agent en arrière-plan ou un workflow, claude -p reste plutôt ouvert jusqu'à ce que ce travail se termine, car son résultat fait partie de la sortie finale.

Par défaut, l'attente se termine après 10 minutes d'attente continue inactive, donc un sous-agent ou un workflow bloqué ne peut pas maintenir le processus ouvert indéfiniment. À ce stade, Claude Code arrête tout ce qui s'exécute toujours et abandonne son résultat partiel. Pour modifier la limite, définissez CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, ou définissez-le sur 0 pour attendre sans limite.

Si Claude démarre une montre Monitor lors d'une exécution claude -p, Claude Code attend la montre jusqu'à ce qu'elle expire ou que le plafond de dix minutes termine l'attente, selon ce qui arrive en premier. Pendant qu'il attend, Claude continue à répondre à ce que la montre signale. Par défaut, une montre expire cinq minutes après que Claude la démarre.

Arrêter une exécution avec SIGTERM

Si vous arrêtez une exécution claude -p avec SIGTERM, par exemple avec kill ou depuis un superviseur de processus, Claude Code se termine avec le code 143. Claude Code laisse le tour en cours inachevé et n'enregistre aucun résultat pour celui-ci. Pour terminer le tour à la place, envoyez SIGINT, ou appelez interrupt() du SDK Agent, avant d'arrêter le processus.

Sur SIGTERM, Claude Code termine l'arborescence des processus de toute commande Bash qui s'exécute toujours. Claude Code exécute ensuite les hooks SessionEnd et se termine. Lors de la sortie, Claude Code ne démarre aucun nouvel appel d'outil, n'envoie aucune nouvelle demande de modèle et n'exécute aucun hook autre que SessionEnd. Si l'exécution était au milieu d'une commande ou en attente d'une réponse à une invite de permission quand le signal est arrivé, Claude Code gère cette étape comme suit :

  • Exécution d'une commande : Claude Code enregistre la commande comme tuée dans la session.
  • En attente d'une réponse à une invite de permission : si vous envoyez SIGTERM au processus, Claude Code laisse l'invite sans réponse. Si votre programme ferme la session via le SDK Agent, le SDK termine l'entrée de Claude Code avant d'envoyer un signal, et Claude Code annule l'invite dès que l'entrée se termine.

Quand vous reprenez la session, Claude Code continue le tour que SIGTERM a laissé inachevé.

Exemples

Ces exemples mettent en évidence les modèles CLI courants. Lorsqu'une commande nomme un fichier tel que auth.py ou build-error.txt, remplacez-le par un fichier de votre propre projet. En CI ou dans d'autres environnements scriptés, ajoutez --bare pour que Claude Code démarre sans charger les hooks, plugins, mémoire automatique ou CLAUDE.md de l'hôte.

Transmettre des données via Claude

Le mode non-interactif lit stdin, vous pouvez donc transmettre des données et rediriger la réponse comme n'importe quel autre outil en ligne de commande.

Cet exemple transmet un journal de compilation à Claude et écrit l'explication dans un fichier :

cat build-error.txt | claude -p 'concisely explain the root cause of this build error' > output.txt

Avec --output-format json, la charge utile de réponse inclut total_cost_usd et une ventilation des coûts par modèle, afin que les appelants scriptés puissent suivre les dépenses par invocation sans consulter le tableau de bord d'utilisation. Les deux chiffres sont des estimations côté client et peuvent différer de votre facture réelle.

Si Claude Code ne peut pas lire stdin, par exemple parce que le processus qui l'a démarré a déconnecté son extrémité, Claude Code affiche un avertissement sur stderr et continue avec le prompt de la ligne de commande. Avant v2.1.211, un stdin illisible sur Windows plantait la session ou la faisait quitter silencieusement sans sortie.

Ajouter Claude à un script de compilation

Vous pouvez envelopper un appel non-interactif dans un script pour utiliser Claude comme linter ou examinateur spécifique au projet.

Ce script package.json transmet le diff par rapport à main à Claude et lui demande de signaler les fautes de frappe. Transmettre le diff signifie que Claude n'a pas besoin de permission Bash pour le lire, et les guillemets échappés gardent le script portable vers Windows :

{
  "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.\""
  }
}

Exécutez-le avec npm run lint:claude.

Obtenir une sortie structurée

Utilisez --output-format pour contrôler la façon dont les réponses sont retournées :

  • text (par défaut) : sortie en texte brut
  • json : JSON structuré avec résultat, ID de session et métadonnées
  • stream-json : JSON délimité par des sauts de ligne pour le streaming en temps réel

Cet exemple retourne un résumé du projet au format JSON avec les métadonnées de session, avec le résultat textuel dans le champ result :

claude -p "Summarize this project" --output-format json

Pour obtenir une sortie conforme à un schéma spécifique, utilisez --output-format json avec --json-schema et une définition JSON Schema. La réponse inclut les métadonnées sur la requête (ID de session, utilisation, etc.) avec la sortie structurée dans le champ structured_output.

Cet exemple extrait les noms de fonctions et les retourne sous forme de tableau de chaînes :

claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

Si la valeur n'est pas un JSON Schema valide, claude se ferme avec Error: --json-schema is not a valid JSON Schema suivi du diagnostic du validateur. Claude Code accepte les schémas qui utilisent le mot-clé format, tel que "format": "email", mais traite format comme une annotation et ne l'applique pas. Avant v2.1.205, Claude Code ignorait silencieusement un schéma invalide et retournait du texte non structuré, et traitait tout schéma contenant format comme invalide.

Réponses en streaming

Utilisez --output-format stream-json avec --verbose et --include-partial-messages pour recevoir les tokens au fur et à mesure qu'ils sont générés. Chaque ligne est un objet JSON représentant un événement :

claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

La dernière ligne du flux est un message result avec le texte de réponse final, le coût et les métadonnées de session.

Si votre consommateur lit le flux lentement, Claude Code attend que la sortie en file d'attente se vide avant de quitter, en mettant à l'échelle l'attente en fonction de la quantité encore en file d'attente, plafonnée à 30 secondes. Avant v2.1.214, l'attente à la sortie était plafonnée à environ deux secondes, ce qui pouvait couper la fin d'une réponse volumineuse.

L'exemple suivant utilise jq pour filtrer les deltas de texte et afficher uniquement le texte en streaming. Le flag -r affiche les chaînes brutes (sans guillemets) et -j joint sans sauts de ligne pour que les tokens se diffusent en continu :

claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

Pour le streaming programmatique avec callbacks et objets de message, consultez Réponses en streaming en temps réel dans la documentation de l'Agent SDK.

Suivre les messages des sous-agents

Les messages des sous-agents apparaissent dans le flux sous forme de messages assistant et user dont le champ parent_tool_use_id est l'ID de l'appel d'outil qui a généré le sous-agent. Les messages de la conversation principale portent null dans ce champ.

Par défaut, Claude Code n'émet que les blocs tool_use et tool_result des sous-agents. Passez --forward-subagent-text ou définissez CLAUDE_CODE_FORWARD_SUBAGENT_TEXT pour émettre également les blocs de texte et de réflexion des sous-agents, afin que vous puissiez reconstruire la transcription de chaque sous-agent. Cela nécessite Claude Code v2.1.211 ou ultérieur.

Lorsque vous activez l'une ou l'autre option, Claude Code transmet les messages des sous-agents à chaque profondeur d'imbrication : quand un sous-agent génère son propre sous-agent, les messages du sous-agent imbriqué portent l'ID de l'appel d'outil Agent qui l'a généré dans parent_tool_use_id, afin que vous puissiez reconstruire l'arborescence d'imbrication complète en suivant ces ID. Avant v2.1.219, les messages des sous-agents imbriqués n'apparaissaient pas dans le flux.

Gérer les tentatives d'API

Quand une requête API échoue avec une erreur réessayable, Claude Code émet un événement system/api_retry avant de réessayer. Sur v2.1.246 ou ultérieur, quand un 401 ou 403 rejette une credential apiKeyHelper, Claude Code effectue les deux premières tentatives silencieusement sans événement, puis émet l'événement comme d'habitude à partir de la troisième tentative consécutive. Les tentatives silencieuses comptent toujours vers attempt. Vous pouvez utiliser l'événement pour afficher la progression des tentatives dans votre propre interface.

Champ Type Description
type "system" type de message
subtype "api_retry" identifie ceci comme un événement de tentative
attempt entier numéro de tentative actuel, commençant à 1
max_retries entier nombre total de tentatives autorisées
retry_delay_ms entier millisecondes jusqu'à la prochaine tentative
error_status entier ou null code de statut HTTP, ou null pour les erreurs de connexion sans réponse HTTP
no_response objet, optionnel présent uniquement quand la tentative échouée n'a pas reçu les en-têtes de réponse à temps. waited_ms est la durée d'attente de cette tentative et retry_wait_ms est la durée d'attente de la tentative. Dans ces événements, max_retries reflète la tentative que cette cause obtient normalement, pas le budget de session. Nécessite Claude Code v2.1.261 ou ultérieur
error chaîne catégorie d'erreur : authentication_failed, oauth_org_not_allowed, billing_error, rate_limit, overloaded, invalid_request, model_not_found, server_error, max_output_tokens, ou unknown
uuid chaîne identifiant d'événement unique
session_id chaîne session à laquelle appartient l'événement

Lire les métadonnées de session

L'événement system/init rapporte les métadonnées de session, y compris le modèle, les outils, les serveurs MCP et les plugins chargés. C'est le premier événement du flux sauf si les événements de démarrage le précèdent :

L'événement porte également un tableau capabilities optionnel de chaînes nommant les comportements de protocole que cette version de Claude Code implémente, tels que interrupt_receipt_v1 ou interrupt_cancel_queued_v1. Vérifiez-le pour détecter les fonctionnalités au lieu de comparer les chaînes de version, et ignorez les valeurs que vous ne reconnaissez pas. Le champ nécessite Claude Code v2.1.205 ou ultérieur et est absent des versions antérieures. Consultez SDKSystemMessage pour la liste des capacités.

Échouer CI quand un plugin ou un serveur MCP ne se charge pas

Utilisez les champs de plugin dans l'événement system/init pour détecter un plugin qui ne s'est pas chargé :

Champ Type Description
plugins tableau plugins qui se sont chargés avec succès, chacun avec name et path
plugin_errors tableau erreurs de chargement de plugin, chacune avec plugin, type et message. Inclut les versions de dépendance non satisfaites et les défaillances de chargement --plugin-dir telles qu'un chemin manquant ou une archive invalide. Les plugins affectés sont rétrogradés et absents de plugins. La clé est omise quand il n'y a pas d'erreurs

Utilisez les champs du serveur MCP de la même manière. Quand vous passez --mcp-config avec -p, Claude Code attend les serveurs encore en attente avant d'exécuter le premier tour, jusqu'au timeout de démarrage MCP_TIMEOUT, 30 secondes par défaut. Un serveur distant avec une liste d'outils en cache ignore l'attente, affiche pending dans system/init et se connecte lors de son premier appel d'outil. L'attente nécessite Claude Code v2.1.221 ou ultérieur.

Claude Code valide chaque entrée --mcp-config au démarrage et ignore les entrées qui échouent la validation, par exemple une entrée url sans type. L'exécution continue et se termine correctement, donc vérifiez ces champs pour détecter un serveur qui ne s'est jamais chargé :

Champ Type Description
mcp_servers tableau serveurs MCP dans la session, chacun avec name et status
mcp_server_errors tableau entrées --mcp-config ignorées par la validation de configuration, chacune avec name, type et message. type est une catégorie d'ignorance telle que unknown_type, url_missing_type, invalid_config ou reserved_name ; traitez les valeurs que vous ne reconnaissez pas comme un ignorage générique. Les serveurs affectés sont absents de mcp_servers. La clé est omise quand il n'y a pas d'erreurs, donc une porte CI peut échouer sur un tableau non vide. Nécessite Claude Code v2.1.219 ou ultérieur

Quand vous exécutez la commande à la main dans un terminal, Claude Code affiche également un avertissement de démarrage sur stderr, tel que Warning: 1 MCP server skipped due to invalid config:, suivi de la raison de chaque entrée ignorée. Quand vous redirigez stderr, ou quand un programme tel qu'un exécuteur CI ou un hôte SDK le capture, Claude Code n'affiche aucun avertissement et rapporte les entrées ignorées uniquement dans le champ mcp_server_errors. L'avertissement nécessite Claude Code v2.1.219 ou ultérieur.

Suivre les installations de plugins

Quand CLAUDE_CODE_SYNC_PLUGIN_INSTALL est défini, Claude Code émet des événements system/plugin_install pendant que les plugins de marketplace s'installent avant le premier tour. Utilisez-les pour afficher la progression de l'installation dans votre propre interface utilisateur.

Champ Type Description
type "system" type de message
subtype "plugin_install" identifie ceci comme un événement d'installation de plugin
status "started", "installed", "failed", ou "completed" started et completed encadrent l'installation globale ; installed et failed rapportent les marketplaces individuelles
name chaîne, optionnel nom de la marketplace, présent sur installed et failed
error chaîne, optionnel message d'échec, présent sur failed
uuid chaîne identifiant d'événement unique
session_id chaîne session à laquelle appartient l'événement

Approuver automatiquement les outils

Utilisez --allowedTools pour permettre à Claude d'utiliser certains outils sans demander. Cet exemple exécute une suite de tests et corrige les défaillances, permettant à Claude d'exécuter des commandes Bash et de lire/modifier des fichiers sans demander la permission :

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

Pour définir une base de référence pour la session entière au lieu de lister les outils individuels, passez un mode de permission. Pour -p, le mode de permission de démarrage intégré est Manual sur tous les plans, donc passez le mode de permission que vous voulez :

  • auto : passez --permission-mode auto pour qu'un classificateur examine la plupart des actions au lieu de vous
  • dontAsk : Claude Code refuse tout ce qui n'est pas dans vos règles permissions.allow ou l'ensemble de commandes en lecture seule, ce qui est utile pour les exécutions CI verrouillées. AskUserQuestion, les outils connecteur que votre organisation a définis sur ask, et les outils MCP marqués requiresUserInteraction sont refusés même quand une règle d'autorisation correspond
  • acceptEdits : Claude écrit des fichiers sans demander, et Claude Code approuve automatiquement les commandes de système de fichiers courants telles que mkdir, touch, mv et cp. Les actions qu'aucun mode n'approuve automatiquement s'appliquent toujours. À part l'ensemble de commandes en lecture seule, les autres commandes shell et requêtes réseau ont toujours besoin d'une entrée --allowedTools ou d'une règle permissions.allow. Consultez ce que acceptEdits approuve automatiquement pour la liste complète

Cet exemple applique les corrections de lint avec acceptEdits comme base de référence :

claude -p "Apply the lint fixes" --permission-mode acceptEdits

Désactiver les invites de permission dans les exécutions sans surveillance

Passez --permission-prompts none quand personne n'est disponible pour répondre aux invites de permission, par exemple dans une tâche planifiée. Le flag est particulièrement important quand votre exécution a un hôte de permission : une application Agent SDK avec un callback canUseTool, ou un outil MCP que vous passez avec --permission-prompt-tool. Sans le flag, votre exécution attend que cet hôte réponde à chaque demande de permission.

Avec le flag, votre exécution ne consulte pas l'hôte et ne l'attend pas. Tout ce qui demanderait une permission est refusé sauf si un hook PermissionRequest l'autorise, Claude est informé que personne ne peut approuver la demande et ne doit pas la réessayer, et l'exécution continue. Dans une exécution -p sans hôte, ces demandes sont refusées de toute façon, et le flag indique également à Claude de ne pas les réessayer. Les règles de permission, les hooks PermissionRequest et le mode de permission que vous définissez décident toujours de chaque appel en premier ; Claude Code refuse uniquement les demandes que rien d'autre ne résout.

Cet exemple exécute une tâche sans surveillance en mode auto. Le classificateur examine chaque action comme d'habitude, et Claude Code refuse tout ce qui aurait autrement nécessité une invite :

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

Avec --permission-prompts none, Claude Code supprime les outils qui ont besoin d'une réponse d'une personne, tels que AskUserQuestion, afin que Claude ne puisse pas les appeler. Toute demande d'élicitation MCP qu'aucun hook Elicitation ne répond est annulée.

Avec --output-format stream-json, les refus apparaissent sous forme de messages système permission_denied, et le message de résultat final les énumère dans permission_denials.

Créer un commit

Cet exemple examine les modifications mises en scène et crée un commit avec un message approprié :

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

Le flag --allowedTools utilise la syntaxe des règles de permission. L'espace * à la fin active la correspondance de préfixe, donc Bash(git diff *) autorise n'importe quelle commande commençant par git diff. L'espace avant * est important : sans lui, Bash(git diff*) correspondrait également à git diff-index.

Personnaliser le prompt système

Utilisez --append-system-prompt pour ajouter des instructions tout en conservant le comportement par défaut de Claude Code. Cet exemple envoie un diff de PR à Claude et lui demande de vérifier les vulnérabilités de sécurité. Enregistrez-le en tant que script shell, par exemple review.sh :

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

Dans le script, "$1" représente le premier argument que vous passez sur la ligne de commande. Exécutez bash review.sh 123 et le shell remplace "$1" par 123, donc le script récupère le diff pour la PR 123. Claude Code affiche l'examen au format JSON, avec le texte dans le champ result.

Consultez les flags de prompt système pour plus d'options, notamment --system-prompt pour remplacer complètement le prompt par défaut.

Continuer les conversations

Utilisez --continue pour continuer la conversation la plus récente, ou --resume avec un ID de session pour continuer une conversation spécifique. --continue ignore les sessions en arrière-plan. Cet exemple exécute un examen, puis envoie des prompts de suivi :

# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue

Si vous exécutez plusieurs conversations, capturez l'ID de session pour reprendre une conversation spécifique :

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Vous pouvez exécuter les deux commandes à partir de répertoires différents : Claude Code trouve la session par son ID dans n'importe quel projet sur cette machine. Avant v2.1.223, Claude Code cherchait l'ID uniquement dans le répertoire de projet actuel et ses git worktrees, donc vous deviez exécuter les deux commandes à partir du même répertoire.

Étapes suivantes