-p avec votre prompt et toute option 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 fonctionnent avec -p, notamment :
--continuepour continuer les conversations--allowedToolspour approuver automatiquement les outils--output-formatpour obtenir une sortie structurée
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, 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. Seuls les flags que vous passez explicitement prennent effet.
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 :
Le mode bare ignore OAuth et les lectures du trousseau. L’authentification Anthropic doit provenir de
ANTHROPIC_API_KEY ou d’un apiKeyHelper dans le JSON passé à --settings. Amazon Bedrock, Google Cloud’s Agent Platform et Microsoft Foundry utilisent leurs identifiants de fournisseur habituels.
--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
Si Claude démarre une tâche Bash en arrière-plan lors d’une exécutionclaude -p, par exemple un serveur de développement ou une compilation en surveillance, cette tâche est terminée 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. Avant la v2.1.163, un processus en arrière-plan qui ne s’arrêtait jamais maintiendrait l’invocation claude -p ouverte indéfiniment.
Les sous-agents en arrière-plan et les workflows sont exempts de la période de grâce de cinq secondes car leur résultat fait partie de la sortie finale, donc claude -p attend qu’ils se terminent. À partir de la v2.1.182, cette attente est plafonnée à dix minutes par défaut afin qu’un agent en arrière-plan bloqué ne puisse pas maintenir le processus ouvert indéfiniment. Ajustez le plafond avec CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, ou définissez-le sur 0 pour attendre sans limite.
Exemples
Ces exemples mettent en évidence les modèles CLI courants. Pour CI et autres appels scriptés, ajoutez--bare pour qu’ils ne reprennent pas ce qui se trouve configuré localement.
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 :--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.
À partir de Claude Code v2.1.128, stdin transmis est limité à 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 grandes, écrivez le contenu dans un fichier et référencez le chemin du fichier dans votre prompt au lieu de le transmettre.
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 scriptpackage.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 :
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 brutjson: JSON structuré avec résultat, ID de session et métadonnéesstream-json: JSON délimité par des sauts de ligne pour le streaming en temps réel
result :
--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 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 :
result avec le texte de réponse final, le coût et les métadonnées de session. Avant v2.1.208, transmettre une réponse volumineuse pouvait tronquer la dernière ligne et omettre le message result.
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 :
system/api_retry avant de réessayer. Vous pouvez l’utiliser pour afficher la progression des tentatives ou implémenter une logique de backoff personnalisée.
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 :
- Les événements
plugin_install, quandCLAUDE_CODE_SYNC_PLUGIN_INSTALLest défini. - Les événements
hook_started,hook_progressethook_response, pendant qu’un hookSessionStartouSetupconfiguré s’exécute. Ces événements se diffusent au fur et à mesure que le hook les produit. Claude Code v2.1.169 à v2.1.203 les a livrés en un seul lot après la fin du hook, toujours avantsystem/init; v2.1.204 a restauré la livraison en direct.
capabilities optionnel de chaînes nommant les comportements de protocole que cette version de Claude Code implémente, tels que interrupt_receipt_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.
Utilisez les champs de plugin pour échouer CI quand un plugin n’a pas pu être chargé :
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.
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.
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 :
dontAsk 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 permet à Claude d’écrire des fichiers sans demander et approuve également automatiquement les commandes de système de fichiers courants telles que mkdir, touch, mv et cp. Les autres commandes shell et requêtes réseau ont toujours besoin d’une entrée --allowedTools ou d’une règle permissions.allow, sinon l’exécution s’arrête quand l’une d’elles est tentée :
Créer un commit
Cet exemple examine les modifications mises en scène et crée un commit avec un message approprié :--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.
Les skills invoquées par l’utilisateur et les commandes personnalisées fonctionnent en mode
-p : incluez /skill-name dans la chaîne de prompt et Claude Code l’étend avant d’exécuter. Les commandes intégrées qui ouvrent un dialogue interactif, telles que /login, ne sont pas disponibles en mode -p. /model, /effort, /fast, /color et /rename acceptent la valeur comme argument, par exemple /model sonnet, et /mcp sans argument affiche un résumé textuel du statut du serveur ; ces formes nécessitent Claude Code v2.1.205 ou ultérieur et suivent les notes de disponibilité de chaque commande](/fr/commands#all-commands). Pour modifier un paramètre à partir d’une invocation -p, passez key=value à /config, par exemple /config thinking=false.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é :
--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. Cet exemple exécute un examen, puis envoie des prompts de suivi :
É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