Exécuter Claude Code par programmation

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 :

--continue pour continuer les conversations
--allowedTools pour approuver automatiquement les outils
--output-format pour obtenir une sortie structurée

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 adapter leur comportement selon 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 installés, serveurs MCP, mémoire automatique et CLAUDE.md. Sans cela, claude -p les découvre et les charge comme le ferait 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 demande d’approbation par serveur. What runs before you trust a folder couvre chaque type de contenu de dépôt 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 demande 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 <file-or-json>`
Un plugin	`--plugin-dir <path>`, `--plugin-url <url>`

Le mode bare limite également ce qui se passe pendant l’exécution de la session :

Serveurs MCP : seuls les serveurs fournis sur la ligne de commande se connectent, par exemple avec --mcp-config. Dans une session interactive, Claude Code ignore également la connexion automatique à l’IDE, sauf si vous passez --ide.
Rappels système : Claude reçoit vos prompts et les résultats des outils sans les rappels système que Claude Code y ajouterait. Par exemple, Claude n’est pas informé lorsqu’un fichier qu’il a lu précédemment change sur le disque, et il ne reçoit pas la liste des skills disponibles, y compris les skills d’un dossier --add-dir.
Tâches en arrière-plan : aucune ne s’exécute. Une commande qui atteint son délai d’expiration s’arrête au lieu de passer en arrière-plan.

Avant la v2.1.286, ces limites ne s’appliquaient que partiellement : une session --bare interactive connectait les serveurs MCP qu’une session normale aurait connectés, chaque session --bare envoyait des rappels système, et les tâches en arrière-plan restaient disponibles.

--bare est le mode recommandé pour les appels scriptés et SDK, et deviendra le mode par défaut pour -p dans une version future.

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

Une fois que Claude a terminé son tour et que stdin a été fermé, une exécution claude -p peut rester ouverte pour attendre le travail en arrière-plan que Claude a démarré. Sauf si une commande en arrière-plan démarrée par la conversation principale s’exécute toujours, Claude Code arrête par défaut tout ce qui s’exécute encore après 10 minutes d’attente continue inactive et abandonne son résultat partiel. Pour modifier la limite de 10 minutes, définissez CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, ou définissez-la sur 0 pour attendre sans limite. L’exécution attend le travail en arrière-plan tel que les commandes en arrière-plan, les sous-agents et workflows, les surveillances Monitor et les réveils /loop en attente :

Commandes en arrière-plan : pour une commande démarrée par la conversation principale, par exemple un serveur de développement ou un build en mode watch, l’exécution attend que la commande se termine ou atteigne sa limite de temps. Claude effectue ensuite un tour supplémentaire avec le résultat. Tant que la commande s’exécute, la limite de 10 minutes ne met pas fin à l’attente.
Sous-agents en arrière-plan et workflows : l’exécution reste ouverte jusqu’à ce que ce travail se termine, car son résultat fait partie de la sortie finale.
Surveillances Monitor : l’exécution attend jusqu’à ce que la surveillance expire ou que la limite de 10 minutes mette fin à l’attente, selon ce qui arrive en premier. Pendant l’attente, Claude continue de répondre à ce que la surveillance signale. Par défaut, une surveillance expire cinq minutes après que Claude l’a démarrée.
Réveils en attente : dans une exécution dont vous avez passé le prompt sous forme de texte plutôt qu’avec --input-format stream-json, lorsque Claude a planifié un réveil /loop à son propre rythme, l’exécution attend que chaque réveil se déclenche et exécute son itération jusqu’à la fin de la boucle, même au-delà de la limite de 10 minutes.

Lorsque stderr est un terminal et que l’exécution a attendu cinq secondes, Claude Code affiche sur stderr une ligne qui commence par Waiting for background work to finish et nomme le travail concerné. Avec une sortie json ou stream-json, la ligne ne s’affiche que lorsque stdout n’est pas un terminal, de sorte que le JSON lu par votre script ne la contient jamais. Si l’exécution atteint sa limite --max-budget-usd, Claude Code arrête le travail en arrière-plan restant au lieu d’attendre. Lorsque le travail en arrière-plan démarre un autre tour, l’exécution affiche le résultat de chaque tour avec la sortie text par défaut, et le résultat du dernier tour avec la sortie json. Avant la v2.1.295, l’exécution n’affichait également que le résultat du dernier tour avec la sortie text.

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 requête au 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 demande 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 demande de permission : si vous envoyez SIGTERM au processus, Claude Code laisse la demande 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 la demande dès que l’entrée se termine.

Quand vous reprenez la session, Claude Code laisse le tour interrompu tel qu’il est, et votre prochain prompt conduit la conversation. Pour que Claude Code continue le tour interrompu à la reprise à la place, définissez CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1.

Si le répertoire de travail est supprimé

Si le répertoire de travail d’une session claude -p ou Agent SDK est supprimé en cours de session, la session continue de s’exécuter. Quand un tour commence alors que le répertoire est manquant, Claude Code émet un message d’avertissement dans la sortie stream-json, et les commandes shell échouent jusqu’à ce que le répertoire existe à nouveau.

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. Dans les environnements CI ou 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 sans consulter le tableau de bord d’utilisation. Lorsque vous continuez une conversation antérieure avec --continue ou --resume, l’exécution rapporte le total de la conversation, les dépenses des exécutions antérieures incluses. Les deux chiffres sont des estimations côté client et peuvent différer de votre facture réelle.

L’entrée stdin transmise est limitée à 10 Mo. Si vous dépassez la limite, Claude Code se ferme avec une erreur claire et un statut non nul. Pour travailler avec des entrées plus volumineuses, écrivez le contenu dans un fichier et référencez le chemin du fichier dans votre prompt au lieu de le transmettre.

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 imprime un avertissement sur stderr et continue avec le prompt de la ligne de commande. Avant la v2.1.211, une stdin illisible sur Windows plantait la session ou la fermait 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 renvoyé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 en 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 de la requête (ID de session, utilisation, etc.) avec la sortie structurée dans le champ structured_output. Cet exemple extrait les noms de fonction 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.

Utilisez un outil comme jq pour analyser la réponse et extraire des champs spécifiques :

# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

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

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 se fermer, en mettant à l’échelle l’attente en fonction de la quantité restante en file d’attente, plafonnée à 30 secondes. Avant la v2.1.214, l’attente de fermeture était plafonnée à environ deux secondes, ce qui pouvait couper la fin d’une grande réponse. L’exemple suivant utilise jq pour filtrer les deltas de texte et afficher uniquement le texte en streaming. Le flag -r génère des chaînes brutes (sans guillemets) et -j joint sans sauts de ligne pour que les tokens se transmettent continuellement :

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 des rappels et des objets de message, consultez Réponses en streaming en temps réel dans la documentation du SDK Agent.

Suivre les messages des sous-agents

Les messages des sous-agents et des skills qui s’exécutent dans un sous-agent apparaissent dans le flux sous forme de messages assistant et user. Leur champ parent_tool_use_id indique à quelle exécution chacun appartient. Les messages de la conversation principale portent null dans ce champ. Le premier message d’un skill dupliqué, ou d’un sous-agent s’exécutant en avant-plan, est un message user portant le prompt ou le contenu du skill qui le pilote. Après ce premier message, Claude Code émet :

Par défaut : les blocs tool_use et tool_result de l’exécution.
Avec --forward-subagent-text ou CLAUDE_CODE_FORWARD_SUBAGENT_TEXT : les blocs de texte et de réflexion de l’exécution également, afin que vous puissiez reconstruire la transcription de chaque exécution.

Lorsque vous activez l’une ou l’autre option, Claude Code transfère les messages des sous-agents à chaque profondeur d’imbrication, que chacun ait été généré avec l’outil Agent ou démarré en tant que skill dupliqué. Dans parent_tool_use_id, les messages du sous-agent imbriqué portent l’ID de l’appel d’outil Agent ou Skill qui l’a démarré, afin que vous puissiez reconstruire l’arborescence d’imbrication complète en suivant ces ID. Une exécution que Claude démarre avec un appel d’outil porte l’ID de cet appel d’outil. Un skill dupliqué que vous démarrez en passant /<skill-name> comme prompt n’a pas d’appel d’outil, ses messages portent donc à la place une valeur forked-command- et arrivent une fois son exécution terminée. Repérez la façon dont l’exécution a démarré dans la première colonne :

Comment l’exécution démarre	`parent_tool_use_id`	Quand ses messages arrivent
Claude appelle l’outil Agent depuis la conversation principale	L’ID de ce bloc `tool_use` Agent	Pendant que le sous-agent travaille
Claude appelle l’outil Skill pour un skill dupliqué depuis la conversation principale	L’ID de ce bloc `tool_use` Skill	Pendant que le skill dupliqué travaille
Vous passez `/<skill-name>` comme prompt	Une valeur qui commence par `forked-command-`	Ensemble et dans l’ordre une fois le skill dupliqué terminé

Pour un skill dupliqué démarré depuis le prompt, faites correspondre parent_tool_use_id sur le préfixe forked-command-, car le nom qui le suit peut différer de celui que vous avez saisi. Si certains de ces messages manquent dans votre flux, comparez votre version de Claude Code à ces versions minimales :

--forward-subagent-text et CLAUDE_CODE_FORWARD_SUBAGENT_TEXT : v2.1.211 ou ultérieur
Transfert à chaque profondeur d’imbrication : v2.1.219 ou ultérieur
Un skill dupliqué que Claude démarre avec l’outil Skill depuis la conversation principale : v2.1.86 ou ultérieur pour ses blocs tool_use et tool_result, et v2.1.265 ou ultérieur pour son premier message user et ses blocs de texte et de réflexion
Messages des sous-agents qu’un skill dupliqué génère, et des skills dupliqués démarrés à l’intérieur d’un sous-agent ou d’un autre skill dupliqué : v2.1.275 ou ultérieur
Messages d’un skill dupliqué que vous démarrez en passant /<skill-name> comme prompt : v2.1.287 ou ultérieur

Gérer les tentatives d’API

Lorsqu’une requête API échoue avec une erreur réessayable, Claude Code émet un événement system/api_retry avant de réessayer. Sur la v2.1.246 ou ultérieur, lorsqu’un 401 ou 403 rejette des identifiants 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	tentatives totales autorisées pour la cause de cet échec
`retry_delay_ms`	entier	millisecondes jusqu’à la prochaine tentative
`error_status`	entier ou null	code de statut HTTP de la tentative échouée, ou `null` lorsque la tentative n’a pas reçu de réponse HTTP de l’API
`no_response`	objet, optionnel	présent uniquement lorsque la tentative échouée n’a pas reçu d’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 nouvelle tentative. Nécessite Claude Code v2.1.261 ou ultérieur
`error`	chaîne	catégorie d’erreur : `authentication_failed`, `oauth_org_not_allowed`, `account_on_hold`, `billing_error`, `rate_limit`, `overloaded`, `invalid_request`, `model_not_found`, `server_error`, `max_output_tokens`, `cloud_credential_error`, 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 des événements de démarrage le précèdent :

Événements plugin_install, lorsque CLAUDE_CODE_SYNC_PLUGIN_INSTALL est défini.
Événements hook_started, hook_progress et hook_response, tandis qu’un hook SessionStart ou Setup configuré s’exécute. Ceux-ci se transmettent au fur et à mesure que le hook les produit.

L’événement porte également un tableau optionnel capabilities 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. Consultez SDKSystemMessage pour la liste des capacités.

Échouer CI lorsqu’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 échecs de chargement `--plugin-dir` tels qu’un chemin manquant ou une archive invalide. Un plugin qui ne s’est pas chargé est absent de `plugins`. La clé est omise lorsqu’il n’y a pas d’erreurs

Lorsqu’un répertoire ou une archive --plugin-dir lui-même échoue à se charger, son entrée plugin_errors inclut le chemin absolu résolu en tant que path. Utilisez-le pour déterminer lequel de plusieurs valeurs --plugin-dir a échoué. Le champ path nécessite Claude Code v2.1.283 ou ultérieur. Utilisez les champs du serveur MCP de la même manière. Lorsque vous passez --mcp-config avec -p, Claude Code attend les serveurs toujours en attente avant d’exécuter le premier tour, jusqu’au délai d’expiration de démarrage MCP_TIMEOUT, 30 secondes par défaut. Un serveur distant avec une liste d’outils mise en cache ignore l’attente, affiche pending dans system/init et se connecte lors de son premier appel d’outil. Dans un environnement auto-hébergé, une attente plus courte s’applique à la place. 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 ferme correctement, vérifiez donc 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 lorsqu’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

Lorsque vous exécutez la commande à la main dans un terminal, Claude Code imprime é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. Lorsque vous redirigez stderr, ou lorsqu’un programme tel qu’un exécuteur CI ou un hôte SDK le capture, Claude Code n’imprime 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

Lorsque CLAUDE_CODE_SYNC_PLUGIN_INSTALL est défini, Claude Code émet des événements system/plugin_install tandis 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. Lister Read et Edit permet à Claude de lire et modifier des fichiers sans demander la permission, à l’exception des lectures depuis des chemins réseau. Lister Bash fait de même pour les commandes shell, sauf dans une exécution qui démarre en mode auto, où Claude Code supprime une entrée Bash nue comme règle d’autorisation large et le mode auto évalue chaque commande à la place. Cet exemple exécute une suite de tests et corrige les défaillances avec ces trois outils listés :

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. Une exécution où rien ne définit un mode de permission prend le mode de permission de démarrage intégré, qui peut être auto, donc passez celui que vous souhaitez :

auto : passez --permission-mode auto pour qu’un classificateur examine la plupart des actions au lieu de vous
dontAsk : Claude Code refuse chaque appel qui demanderait autrement, ce qui est utile pour les exécutions CI verrouillées. Les actions qui n’ont pas besoin d’approbation en mode Manual s’exécutent toujours, telles que les lectures de fichiers dans vos répertoires de travail et l’ensemble de commandes en lecture seule, ainsi que les actions que vos entrées --allowedTools ou les règles permissions.allow couvrent. AskUserQuestion, les outils de connecteur que votre organisation a définis sur ask, les outils MCP marqués requiresUserInteraction et les lectures depuis des chemins réseau sont refusés même lorsqu’une règle d’autorisation correspond
acceptEdits : Claude écrit les fichiers sans demander, et Claude Code approuve automatiquement les commandes de système de fichiers courantes telles que mkdir, touch, mv et cp. Les actions qu’aucun mode n’approuve automatiquement s’appliquent toujours. Hormis 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 demandes de permission dans les exécutions sans surveillance

Passez --permission-prompts none lorsque personne n’est disponible pour répondre aux demandes de permission, par exemple dans une tâche planifiée. Le flag est plus important lorsque votre exécution a un hôte de permission : une application Agent SDK avec un rappel 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 n’attend pas. Tout ce qui demanderait est refusé sauf si un hook PermissionRequest l’autorise, Claude est informé que personne ne peut approuver la demande et ne 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 entraîné une demande de permission :

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 à laquelle 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.

Le flag --permission-prompts nécessite Claude Code v2.1.259 ou ultérieur. Les versions antérieures le rejettent avec une erreur d’option inconnue.

Créer un commit

Cet exemple examine les modifications indexées 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 de règle de permission. Le * de fin active la correspondance de préfixe, donc Bash(git diff *) autorise toute commande commençant par git diff. L’espace avant * est important : sans lui, Bash(git diff*) correspondrait également à git diff-index.

Le support des commandes diffère en mode -p :

Les skills invoqués par l’utilisateur et les commandes personnalisées fonctionnent. Incluez /skill-name dans la chaîne du prompt et Claude Code l’étend avant d’exécuter.
Les commandes intégrées qui ne s’exécutent que dans l’interface du terminal, telles que /login, ne sont pas disponibles.
/model, /effort, /fast, /color et /rename acceptent la valeur comme argument, par exemple /model sonnet, et /mcp sans argument imprime un résumé textuel du statut du serveur. Ces formes suivent les notes de disponibilité de chaque commande.
Pour modifier un paramètre, passez key=value à /config, par exemple /config thinking=false.
/output-style <style> bascule les styles de sortie et /output-style seul les énumère. Nécessite Claude Code v2.1.269 ou ultérieur.

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 transmet un diff 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 imprime l’examen en JSON, avec le texte dans le champ result. Consultez les flags de prompt système pour plus d’options, y compris --system-prompt pour remplacer complètement le prompt par défaut. Si vous le remplacez, l’exécution démarre également sans l’instantané du statut git.

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. Sur Claude Code v2.1.257 ou ultérieur, lorsque vous passez --continue, Claude Code ouvre une session en arrière-plan qui a terminé, mais pas une qui s’exécute toujours. 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. À la place de l’ID de session, vous pouvez passer à --resume le chemin absolu vers le fichier de transcription .jsonl d’une session, et Claude Code continue la conversation stockée dans ce fichier.

Étapes suivantes

Démarrage rapide de l’Agent SDK : créez votre premier agent avec Python ou TypeScript
Référence CLI : tous les flags et options CLI
GitHub Actions : utilisez l’Agent SDK dans les workflows GitHub
GitLab CI/CD : utilisez l’Agent SDK dans les pipelines GitLab

Agents et travail en parallèle

MCP

Skills

Artefacts

Automatisation

Guides

Dépannage

Exécuter Claude Code par programmation

Utilisation basique

Démarrer plus rapidement avec le mode bare

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

Arrêter une exécution avec SIGTERM

Si le répertoire de travail est supprimé

Exemples

Transmettre des données via Claude

Ajouter Claude à un script de compilation

Obtenir une sortie structurée

Réponses en streaming

Suivre les messages des sous-agents

Gérer les tentatives d’API

Lire les métadonnées de session

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

Suivre les installations de plugins

Approuver automatiquement les outils

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

Créer un commit

Personnaliser le prompt système

Continuer les conversations

Étapes suivantes

​Utilisation basique

​Démarrer plus rapidement avec le mode bare

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

​Arrêter une exécution avec SIGTERM

​Si le répertoire de travail est supprimé

​Exemples

​Transmettre des données via Claude

​Ajouter Claude à un script de compilation

​Obtenir une sortie structurée

​Réponses en streaming

​Suivre les messages des sous-agents

​Gérer les tentatives d’API

​Lire les métadonnées de session

​Échouer CI lorsqu’un plugin ou un serveur MCP ne se charge pas

​Suivre les installations de plugins

​Approuver automatiquement les outils

​Désactiver les demandes de permission dans les exécutions sans surveillance

​Créer un commit

​Personnaliser le prompt système

​Continuer les conversations

​Étapes suivantes

Utilisation basique

Démarrer plus rapidement avec le mode bare

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

Arrêter une exécution avec SIGTERM

Si le répertoire de travail est supprimé

Exemples

Transmettre des données via Claude

Ajouter Claude à un script de compilation

Obtenir une sortie structurée

Réponses en streaming

Suivre les messages des sous-agents

Gérer les tentatives d’API

Lire les métadonnées de session

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

Suivre les installations de plugins

Approuver automatiquement les outils

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

Créer un commit

Personnaliser le prompt système

Continuer les conversations

Étapes suivantes