Mode headless et CI/CD - FAQ

Le mode headless de Claude Code permet d'exécuter des tâches IA directement dans vos pipelines CI/CD sans interaction humaine. Avec le flag -p, vous lancez des prompts en une seule commande, récupérez la sortie en texte, JSON ou flux streaming, et automatisez des workflows complets dans GitHub Actions ou GitLab CI. Ce guide FAQ répond aux questions concrètes pour intégrer Claude Code dans vos chaînes d'automatisation.

Le mode headless de Claude Code est un mode d'exécution non interactif qui permet d'utiliser l'agent IA en ligne de commande sans terminal graphique. ce mode constitue la brique fondamentale pour intégrer Claude Code dans tout pipeline d'intégration et de déploiement continus.

la majorité des équipes utilisant Claude Code en entreprise exploitent le mode headless pour au moins un workflow CI/CD. Le flag -p transforme Claude Code en outil scriptable, capable de traiter un prompt et de retourner un résultat exploitable par d'autres outils.

Comment lancer Claude Code en une seule commande avec le flag -p ?

Utilisez le flag -p suivi de votre prompt entre guillemets pour exécuter Claude Code sans interface interactive.

Le flag -p (pour print) envoie un prompt unique à Claude Code et affiche la réponse directement sur la sortie standard. Ce mode désactive toute interaction utilisateur, ce qui le rend compatible avec les scripts shell, les pipelines CI/CD et les tâches cron.

$ claude -p "Explique la fonction main() dans src/index.ts"

La commande retourne le résultat en texte brut par défaut. Le processus se termine automatiquement après la réponse, avec un code de sortie 0 en cas de succès. Le temps de réponse varie selon la complexité du prompt et le modèle utilisé.

Pour aller plus loin sur les options disponibles, consultez la référence complète des commandes du mode headless qui détaille chaque flag.

À retenir : le flag -p transforme Claude Code en commande Unix classique, compatible avec les pipes et redirections shell.

Comment intégrer Claude Code dans GitHub Actions ?

Ajoutez une étape dans votre workflow YAML qui installe Claude Code et exécute un prompt avec le flag -p.

L'intégration repose sur trois éléments : l'installation de Claude Code via npm, la configuration de la clé API comme secret GitHub, et l'appel en mode headless. Voici un workflow fonctionnel :

name: Claude Code Review
on: [pull_request]

jobs:
 review:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - uses: actions/setup-node@v4
 with:
 node-version: '22'
 - run: npm install -g @anthropic-ai/claude-code
 - name: Code Review
 env:
 ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 run: |
 claude -p "Review the changes in this PR and list potential bugs" \
 --output-format json > review.json

Ce workflow s'exécute à chaque pull request, sa durée dépendant de la taille du diff et du modèle utilisé. Vous pouvez consulter les astuces pour optimiser vos pipelines headless pour réduire les temps d'exécution.

Pour gérer les permissions et la sécurité de vos tokens API dans un contexte CI, stockez systématiquement la clé dans les secrets du repository et non dans le code source.

À retenir : une intégration GitHub Actions complète nécessite Node.js 22+, le package npm et une clé API en secret : trois lignes de configuration suffisent.

Quels formats de sortie sont disponibles en mode headless ?

Claude Code propose trois formats de sortie en mode headless : text, json et stream-json.

Le format par défaut est text, qui retourne la réponse brute sur stdout. Le format json encapsule la réponse dans un objet structuré avec métadonnées. Le format stream-json envoie les tokens un par un au format JSON Lines (NDJSON), idéal pour les traitements en temps réel.

# Format texte (défaut)
$ claude -p "Résume ce fichier" --output-format text

# Format JSON structuré
$ claude -p "Liste les TODO" --output-format json

# Format streaming JSON Lines (requiert --verbose)
$ claude -p "Génère la doc" --output-format stream-json --verbose

Le format json retourne un objet contenant les champs result, session_id, usage et total_cost_usd. En pratique, la plupart des intégrations CI/CD utilisent le format json pour parser le résultat avec jq ou un script Python.

# Extraire uniquement le résultat avec jq
$ claude -p "Analyse ce code" --output-format json | jq -r '.result'

Pour comprendre comment exploiter ces formats dans des sessions multi-turn programmatiques, consultez le guide dédié au mode headless.

À retenir : choisissez text pour le debug rapide, json pour l'intégration programmatique et stream-json pour le feedback temps réel.

Comment créer des sessions multi-turn programmatiques ?

Utilisez le flag --resume combiné avec -p pour maintenir le contexte entre plusieurs appels successifs.

Une session multi-turn permet d'enchaîner plusieurs prompts en conservant l'historique de la conversation. Claude Code stocke le contexte et le recharge automatiquement quand vous reprenez une session avec --resume.

# Premier appel : analyser le code (récupérer le session_id)
RESULT=$(claude -p "Analyse les fichiers dans src/" --output-format json)
SESSION=$(echo "$RESULT" | jq -r '.session_id')

# Deuxième appel : le contexte précédent est conservé
$ claude -p "Quels bugs as-tu trouvés dans l'analyse précédente ?" \
 --resume "$SESSION"

# Troisième appel : demander un fix
$ claude -p "Corrige le bug le plus critique" --resume "$SESSION"

La taille de la fenêtre de contexte est une propriété du modèle utilisé : les modèles Claude actuels offrent une fenêtre de 200 000 tokens. La consommation d'une session dépend du nombre de tours et de la quantité de code analysé.

Concrètement, les sessions multi-turn sont utiles pour les workflows en plusieurs étapes : analyse, correction, vérification. Vous trouverez des exemples supplémentaires dans le cheatsheet du mode headless avec des scripts prêts à copier.

Le mécanisme de session fonctionne aussi dans GitHub Actions en passant le session_id entre les étapes du workflow via la sortie JSON.

À retenir : le flag --resume transforme des appels isolés en conversation continue, idéal pour les pipelines multi-étapes.

Comment parser la sortie JSON de Claude Code dans un script ?

Combinez le flag --output-format json avec un outil de parsing comme jq pour extraire les données structurées.

La sortie JSON de Claude Code suit un schéma stable avec les champs principaux result (la réponse textuelle), session_id (l'identifiant de session), usage (tokens consommés) et total_cost_usd (coût de l'appel). Ce schéma est documenté dans la référence du mode headless.

# Extraire le résultat texte
$ claude -p "Résume ce PR" --output-format json | jq -r '.result'

# Extraire le coût de l'appel
$ claude -p "Analyse ce code" --output-format json | jq '.total_cost_usd'

# Vérifier le nombre de tokens utilisés
$ claude -p "Documente cette fonction" --output-format json \
  | jq '.usage.input_tokens + .usage.output_tokens'

En Python, le parsing est direct :

import subprocess
import json

result = subprocess.run(
 ["claude", "-p", "Liste les fichiers modifiés", "--output-format", "json"],
 capture_output=True, text=True
)
data = json.loads(result.stdout)
print(f"Réponse : {data['result']}")
print(f"Coût : {data['total_cost_usd']}$")

Pour les développeurs qui découvrent la ligne de commande Claude Code, la FAQ d'installation et premier lancement couvre les prérequis techniques. La structure JSON est identique que vous exécutiez Claude Code en local ou dans un conteneur Docker.

À retenir : la sortie JSON suit un schéma stable. Utilisez jq en bash ou json.loads() en Python pour extraire result, usage et total_cost_usd.

Quels sont les cas d'usage CI/CD avancés avec Claude Code ?

Les cas d'usage avancés incluent la revue de code automatique, la génération de tests, la documentation automatisée et la détection de vulnérabilités de sécurité.

les équipes qui automatisent la revue de code avec Claude Code allègent la charge de review manuelle et détectent les problèmes plus tôt dans le cycle. Voici les cinq cas d'usage les plus fréquents :

Concrètement, un pipeline de génération de tests unitaires ressemble à ceci :

$ claude -p "Génère des tests unitaires pour les fonctions sans couverture \
 dans src/utils/" --output-format json \
 --max-turns 5 | jq -r '.result' > tests/generated.test.ts

Pour comprendre comment Claude Code raisonne sur votre code source, consultez l'article sur le coding agentique et ses principes. Les workflows avancés combinent souvent le mode headless avec le système de mémoire CLAUDE.md pour donner du contexte projet à chaque exécution.

À retenir : la revue de code automatisée et la génération de tests sont les deux cas d'usage CI/CD les plus rentables, avec un ROI mesurable dès la première semaine.

Comment gérer les erreurs et les codes de retour en mode headless ?

Vérifiez le code de sortie du processus : 0 indique un succès, tout autre code signale une erreur.

Claude Code retourne 0 en cas de succès et un code non nul en cas d'échec. La documentation officielle ne garantit pas de sémantique fine par code de retour : testez $? -ne 0 et inspectez le champ is_error de la sortie JSON pour distinguer les cas. Le code 124 ne provient pas de Claude Code lui-même mais de la commande Unix timeout lorsque vous l'utilisez pour borner la durée d'exécution.

$ claude -p "Analyse ce fichier" --output-format json
if [ $? -eq 0 ]; then
 echo "Succès"
else
 echo "Erreur code: $?"
 exit 1
fi

Dans un pipeline GitHub Actions, utilisez continue-on-error: true si vous souhaitez que le workflow continue malgré une erreur de Claude Code. En pratique, des prompts bien formulés et un périmètre clair réduisent sensiblement les erreurs en production.

Pour le format json, l'échec est signalé par le champ booléen is_error. Testez systématiquement jq '.is_error' avant de traiter le résultat. Les commandes slash essentielles incluent des options de debug utiles pour diagnostiquer les erreurs récurrentes.

À retenir : traitez toujours le code de retour dans vos scripts : un $? non vérifié peut masquer des erreurs silencieuses dans votre pipeline.

Comment limiter les coûts API dans un pipeline CI/CD ?

Configurez le flag --max-turns et surveillez le champ total_cost_usd de la sortie JSON pour maîtriser votre budget.

Chaque appel en mode headless consomme des tokens facturés. Le coût par revue dépend de la taille du diff et du modèle utilisé : mesurez-le via le champ total_cost_usd de la sortie JSON plutôt que de vous fier à une estimation. Le flag --max-turns limite le nombre d'itérations de l'agent, ce qui plafonne la consommation.

# Limiter à 3 tours maximum
$ claude -p "Refactorise src/utils.ts" --max-turns 3 --output-format json

# Extraire le coût pour monitoring
$ claude -p "Review ce PR" --output-format json | jq '.total_cost_usd'

Voici comment budgétiser vos pipelines :

• Le coût d'une revue de code par PR dépend de la taille du diff et du modèle
• La génération de tests consomme davantage de tokens à mesure que le fichier grandit
• Une analyse de sécurité complète est généralement le poste le plus coûteux
• Pour un budget hebdomadaire fiable, cumulez les total_cost_usd réels plutôt que des estimations

SFEIR Institute recommande de centraliser le monitoring des coûts dans un dashboard. Agrégez les valeurs total_cost_usd de chaque exécution dans un fichier CSV ou une base de données pour suivre la tendance.

Pour approfondir la configuration et les bonnes pratiques, découvrez la formation Claude Code de SFEIR. En une journée, vous pratiquerez l'intégration CI/CD avec des labs concrets et apprendrez à optimiser vos prompts pour réduire la consommation de tokens.

À retenir : utilisez --max-turns pour plafonner les coûts et surveillez total_cost_usd dans chaque réponse JSON pour un suivi budgétaire précis.

Comment utiliser Claude Code en mode headless avec Docker ?

Exécutez Claude Code dans un conteneur Docker en passant la clé API comme variable d'environnement.

L'exécution dans Docker garantit un environnement reproductible pour vos pipelines CI/CD. Une image basée sur Node.js 22 Alpine reste légère, l'installation de Claude Code ajoutant le package npm et ses dépendances.

FROM node:22-alpine
RUN npm install -g @anthropic-ai/claude-code
WORKDIR /app
COPY . .
ENTRYPOINT ["claude", "-p"]

$ docker build -t claude-ci .
$ docker run -e ANTHROPIC_API_KEY="sk-..." claude-ci "Analyse le code dans /app/src"

Cette approche isole Claude Code du système hôte. Chaque exécution démarre dans un environnement propre, ce qui élimine les problèmes de cache ou de dépendances résiduelles.

Pour les équipes qui débutent avec la conteneurisation de leurs outils IA, la formation Développeur Augmenté par l'IA de SFEIR couvre en deux jours l'intégration d'outils IA dans les workflows DevOps, avec des exercices pratiques sur Docker et les pipelines CI.

Consultez le guide complet du mode headless pour les options avancées de configuration Docker, notamment le montage de volumes et la gestion des caches.

À retenir : Docker + Claude Code en mode headless = environnement reproductible ; passez la clé API via -e et montez votre code source en volume.

Peut-on combiner le mode headless avec le fichier CLAUDE.md ?

Oui, Claude Code charge automatiquement le fichier CLAUDE.md du répertoire courant, même en mode headless.

Le fichier CLAUDE.md est un mécanisme de mémoire projet qui donne du contexte persistant à Claude Code. En mode headless, ce fichier est lu à chaque appel si il est présent dans le répertoire de travail. Cela permet de standardiser les instructions projet pour tous les appels CI/CD.

# CLAUDE.md (à la racine du projet)
- Convention de code : TypeScript strict, ESLint Airbnb
- Tests : Vitest, couverture minimum 80%
- Ne jamais modifier les fichiers dans /config/production/

# Claude Code lira automatiquement CLAUDE.md
$ cd /mon-projet && claude -p "Génère des tests pour src/auth.ts"

En pratique, les équipes qui utilisent CLAUDE.md en CI/CD obtiennent des résultats plus cohérents avec leurs standards de code. Vous trouverez les détails de configuration dans la FAQ sur le système de mémoire CLAUDE.md.

Le fichier CLAUDE.md supporte aussi les instructions de sécurité. Ajoutez des directives comme « Ne jamais exposer de secrets » ou « Ne pas modifier les fichiers de production » pour sécuriser vos pipelines automatisés.

À retenir : placez un fichier CLAUDE.md à la racine de votre repo pour que chaque exécution headless respecte automatiquement vos conventions projet.

Comment automatiser la revue de code sur chaque pull request ?

Créez un workflow GitHub Actions déclenché sur l'événement pull_request qui exécute Claude Code sur le diff.

La revue automatisée analyse le diff de la PR et produit un commentaire structuré. Le temps d'exécution dépend de la taille du diff et du modèle utilisé.

name: AI Code Review
on:
 pull_request:
 types: [opened, synchronize]

jobs:
 review:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 with:
 fetch-depth: 0
 - uses: actions/setup-node@v4
 with:
 node-version: '22'
 - run: npm install -g @anthropic-ai/claude-code
 - name: Review PR
 env:
 ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
 run: |
 DIFF=$(git diff origin/main...HEAD)
 echo "$DIFF" | claude -p "Analyse ce diff et liste : \
 1. Bugs potentiels \
 2. Problèmes de sécurité \
 3. Suggestions d'amélioration" \
 --output-format json | jq -r '.result' > review.md
 - name: Post Comment
 uses: actions/github-script@v7
 with:
 script: |
 const fs = require('fs');
 const review = fs.readFileSync('review.md', 'utf8');
 github.rest.issues.createComment({
 owner: context.repo.owner,
 repo: context.repo.repo,
 issue_number: context.issue.number,
 body: `## 🔍 Revue IA\n${review}`
 });

Ce workflow utilise fetch-depth: 0 pour accéder à l'historique complet du diff. Adaptez le prompt à vos conventions en référençant les règles de votre CLAUDE.md.

Explorez les conversations avec Claude Code pour apprendre à formuler des prompts de revue efficaces qui maximisent la pertinence des retours.

À retenir : automatisez la revue de code avec un workflow de 30 lignes YAML : le diff est passé via pipe et le résultat est posté en commentaire de PR.

Quels sont les prérequis techniques pour le mode headless ?

Le mode headless nécessite Node.js 18 ou supérieur, le package npm @anthropic-ai/claude-code et une clé API Anthropic valide.

Voici la liste complète des prérequis au moment de la rédaction :

• Node.js : version 18+ (recommandé : Node.js 22 LTS)
• npm : version 9+ (inclus avec Node.js 18+)
• Claude Code : dernière version stable
• Clé API : variable d'environnement ANTHROPIC_API_KEY
• Système d'exploitation : Linux, macOS ou Windows (WSL2)
• RAM minimale : 512 MB disponibles
• Réseau : accès HTTPS sortant vers api.anthropic.com

# Vérifier les prérequis
$ node --version # v22.x.x attendu
$ npm --version # 10.x.x attendu
$ claude --version # un numéro de version s'affiche

La FAQ d'installation et premier lancement détaille la procédure complète, y compris les cas particuliers comme l'installation derrière un proxy d'entreprise. L'installation complète prend moins de 2 minutes sur une connexion standard.

Pour les développeurs qui souhaitent aller plus loin, la formation Développeur Augmenté par l'IA – Avancé de SFEIR (1 jour) approfondit les architectures CI/CD avec IA intégrée, le tuning de prompts pour les pipelines et les stratégies de monitoring avancées.

À retenir : Node.js 22 + npm + clé API Anthropic : vérifiez ces trois éléments avant toute intégration CI/CD.

Comment sécuriser la clé API dans un environnement CI/CD ?

Stockez la clé API exclusivement dans le gestionnaire de secrets de votre plateforme CI (GitHub Secrets, GitLab CI Variables, AWS Secrets Manager).

La clé API Anthropic (ANTHROPIC_API_KEY) donne accès à votre compte et votre quota. En mode headless, elle doit être injectée comme variable d'environnement sans jamais apparaître dans le code source, les logs ou les artefacts de build.

# GitHub Actions - clé stockée dans les secrets du repo
env:
 ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

# GitLab CI - clé définie dans Settings > CI/CD > Variables
variables:
 ANTHROPIC_API_KEY: $CI_ANTHROPIC_KEY

Les fuites de secrets en CI/CD proviennent souvent de logs non filtrés. Activez le masquage automatique des secrets dans votre plateforme CI pour limiter la verbosité des logs.

Pour une vue complète des bonnes pratiques de sécurité avec Claude Code, consultez la FAQ sur les permissions et la sécurité. Les règles de sécurité définies dans votre CLAUDE.md s'appliquent aussi en mode headless.

À retenir : jamais de clé API en clair dans le code : utilisez les secrets natifs de votre plateforme CI et activez le masquage dans les logs.

Y a-t-il des limites de rate limiting en mode headless ?

Les limites de débit dépendent de votre niveau d'usage Anthropic Console et de votre abonnement, et non du conteneur ou de la machine. À noter : le plan gratuit Claude.ai n'inclut pas l'accès à Claude Code. Consultez votre tableau de bord Anthropic pour connaître vos quotas exacts.

En mode headless dans un pipeline CI/CD, vous pouvez atteindre ces limites si plusieurs jobs s'exécutent en parallèle. Le rate limiting s'applique au niveau de la clé API, pas au niveau de la machine ou du conteneur.

Implémentez un mécanisme de retry avec backoff exponentiel pour gérer les erreurs 429 (Too Many Requests) :

MAX_RETRIES=3
for i in $(seq 1 $MAX_RETRIES); do
 claude -p "Review ce code" --output-format json && break
 echo "Rate limited, retry $i/$MAX_RETRIES..."
 sleep $((2 ** i))
done

En pratique, un projet avec 50 PR par semaine et 3 jobs CI par PR consomme environ 150 requêtes par semaine, un volume qui reste généralement bien en dessous des quotas courants. Retrouvez d'autres astuces d'optimisation dans les tips du mode headless.

À retenir : surveillez vos quotas via le dashboard Anthropic et implémentez un retry avec backoff exponentiel pour absorber les pics de charge en CI/CD.