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 toute option CLI :

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 fonctionnent avec -p, notamment :

• --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?"

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 :

claude --bare -p "Summarize this file" --allowedTools "Read"

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 :

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. Bedrock, Vertex et Foundry utilisent leurs identifiants de fournisseur habituels.

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 :

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.

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

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"]}'

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

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'

Quand une requête API échoue avec une erreur réessayable, Claude Code émet un événement 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 CLAUDE_CODE_SYNC_PLUGIN_INSTALL est défini, auquel cas les événements plugin_install le précèdent. 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 :

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. 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. 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 :

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

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é :

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

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. 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"

É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