Mode headless et CI/CD - Aide-memoire

Cet aide-mémoire rassemble toutes les commandes pour utiliser Claude Code en mode headless dans vos pipelines CI/CD. Retrouvez la syntaxe du flag -p, les formats de sortie, les intégrations GitHub Actions et les sessions programmatiques multi-turn. Gardez cette fiche pratique sous la main pour automatiser vos workflows sans intervention humaine.

Le mode headless de Claude Code est la capacité d'exécuter l'outil en ligne de commande non interactive, sans interface conversationnelle, pour l'intégrer dans des scripts et des pipelines d'automatisation. cette fonctionnalité transforme Claude Code en brique d'automatisation pour la CI/CD, le linting IA et la revue de code automatisée.

Comment lancer Claude Code en mode headless avec le flag -p ?

Le flag -p (pour print) est le point d'entrée du mode headless. Il permet d'envoyer un prompt unique à Claude Code et de récupérer la réponse sur la sortie standard, sans ouvrir l'interface interactive. Exécutez cette commande pour un premier test :

claude -p "Explique ce que fait ce fichier" --file src/index.ts

Claude Code traite le prompt, génère la réponse et quitte immédiatement. Le code de sortie reflète le succès (0) ou l'échec (1) de l'exécution. En pratique, 90 % des usages CI/CD reposent sur ce seul flag.

Pour découvrir chaque option en détail, consultez la référence complète des commandes du mode headless qui couvre l'intégralité des flags disponibles.

À retenir : le flag -p transforme Claude Code en outil CLI classique compatible avec tout pipeline d'automatisation.

Quels sont les formats de sortie disponibles pour le parsing ?

Claude Code v1.0.33+ propose trois formats de sortie via --output-format. Choisissez le format adapté à votre cas d'usage pour parser la réponse efficacement.

Format text (défaut)

claude -p "Explique cette fonction" --output-format text

Le format text renvoie la réponse brute en texte plein. Utilisez-le pour les cas simples où vous redirigez la sortie vers un fichier ou l'affichez dans les logs CI.

Format json

claude -p "Analyse ce code" --output-format json

La sortie JSON est un objet unique contenant le résultat complet. Voici la structure type :

{
  "type": "result",
  "result": "Votre réponse ici",
  "cost_usd": 0.042,
  "duration_ms": 3200,
  "num_turns": 1
}

Le champ cost_usd affiche le coût en dollars de l'appel. Le champ duration_ms indique la durée totale en millisecondes. En pratique, un appel simple coûte entre 0,01 et 0,15 USD selon la taille du contexte.

Format stream-json

claude -p "Revois ce PR" --output-format stream-json | jq '.type'

Le format stream-json émet des objets JSON ligne par ligne (NDJSON). Chaque événement possède un champ type distinct. Ce format permet de traiter la réponse en temps réel sans attendre la fin de l'exécution.

Pour maîtriser la gestion des sorties dans vos scripts, la fiche pratique sur la gestion du contexte vous donne les patterns de parsing réutilisables.

À retenir : utilisez json pour les scripts automatisés et stream-json pour le feedback en temps réel.

Comment intégrer Claude Code dans GitHub Actions ?

L'intégration GitHub Actions repose sur un workflow YAML qui installe Claude Code puis l'exécute avec -p. plus de 60 % des équipes utilisant Claude Code en CI l'intègrent via GitHub Actions. Créez un fichier .github/workflows/claude-review.yml :

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

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Revois les changements de ce PR et liste les problèmes potentiels" \
            --output-format json > review.json

Le secret ANTHROPIC_API_KEY est la clé API Anthropic stockée dans les secrets GitHub. Configurez-la dans Settings → Secrets → Actions de votre dépôt. La durée moyenne d'une revue de code par Claude Code est de 15 à 45 secondes selon la taille du diff.

Pour sécuriser les permissions de l'outil en CI, consultez la fiche sur les permissions et la sécurité qui détaille le mode --allowedTools.

À retenir : stockez votre clé API dans les secrets GitHub et limitez les outils autorisés avec --allowedTools en CI.

Comment gérer des sessions multi-turn programmatiques ?

Une session multi-turn permet d'enchaîner plusieurs prompts dans un même contexte conversationnel. Utilisez les flags --session-id et --resume pour maintenir la continuité entre les appels.

# Premier appel : démarrer une session
claude -p "Analyse l'architecture du projet" \
  --output-format json \
  --session-id "ci-review-42" > step1.json

# Deuxième appel : continuer dans la même session
claude -p "Maintenant propose des améliorations" \
  --resume --session-id "ci-review-42" \
  --output-format json > step2.json

Le --session-id est un identifiant arbitraire que vous choisissez. Le flag --resume indique à Claude Code de charger le contexte de la session existante. Chaque session conserve jusqu'à 200 000 tokens de contexte (environ 150 000 mots).

En pratique, les sessions multi-turn consomment 30 à 50 % de tokens supplémentaires par rapport à des appels isolés. Limitez le nombre de tours avec --max-turns pour maîtriser les coûts.

Pour structurer vos conversations programmatiques, la fiche sur vos premières conversations explique les patterns conversationnels fondamentaux que vous retrouverez en mode headless.

À retenir : nommez vos sessions avec --session-id et reprenez-les avec --resume pour des workflows multi-étapes.

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

Le mode headless de Claude Code couvre des scénarios bien au-delà de la simple revue de code. Voici concrètement les cas d'usage les plus courants en 2026.

Génération automatique de tests

claude -p "Génère des tests unitaires pour src/auth.ts avec vitest" \
  --allowedTools Read,Write \
  --max-turns 5 \
  --output-format json

l'ajout de tests générés par IA couvre en moyenne 72 % des branches de code non testées. Limitez les outils à Read,Write pour empêcher l'exécution de commandes non contrôlées.

Linting et correction automatique

claude -p "Corrige les erreurs ESLint dans src/ sans changer la logique" \
  --allowedTools Read,Write \
  --output-format text

Un pipeline de correction automatique réduit le temps de résolution des erreurs de lint de 85 % en moyenne. Vérifiez toujours le diff généré avant de merger automatiquement.

Documentation automatique

claude -p "Génère la JSDoc pour toutes les fonctions exportées de lib/" \
  --allowedTools Read,Write \
  --max-turns 10

Pour explorer d'autres exemples concrets de pipelines, la page exemples du mode headless propose des workflows prêts à l'emploi.

Le guide complet du mode headless et CI/CD détaille chaque scénario avec des architectures de pipeline complètes.

À retenir : restreignez toujours les outils autorisés (--allowedTools) en CI pour limiter la surface d'action de l'IA.

Comment sécuriser l'exécution de Claude Code en CI/CD ?

La sécurité en CI/CD exige de restreindre les capacités de Claude Code. Appliquez ces 5 règles systématiquement.

1. Limitez les outils avec --allowedTools Read,Write - jamais Bash en CI automatique
2. Stockez la clé API dans un gestionnaire de secrets (GitHub Secrets, Vault, AWS SSM)
3. Fixez --max-turns à une valeur raisonnable (3 à 10) pour éviter les boucles infinies
4. Validez la sortie JSON avec un schéma avant d'agir sur le résultat
5. Auditez chaque exécution en conservant les logs (--verbose > claude-audit.log)

claude -p "Revois ce code" \
  --allowedTools Read \
  --max-turns 3 \
  --verbose \
  --output-format json 2>claude-audit.log

Le coût moyen d'une exécution CI avec Claude Code est de 0,03 à 0,20 USD par run. Sur un projet avec 50 PRs par semaine, le budget mensuel se situe entre 6 et 40 USD.

Pour comprendre le modèle de permissions en profondeur, la fiche sur les permissions et la sécurité vous guide pas à pas. Pensez aussi à consulter les erreurs courantes du mode headless pour anticiper les pièges fréquents.

À retenir : le trio --allowedTools, --max-turns et --verbose constitue le socle de sécurité minimal en CI.

Quels raccourcis et variables d'environnement connaître ?

En mode headless, les raccourcis clavier n'existent pas (pas d'interface interactive). En revanche, plusieurs variables d'environnement contrôlent le comportement de Claude Code en CI.

Définissez ces variables dans votre fichier CI pour éviter de répéter les flags :

export ANTHROPIC_API_KEY="sk-ant-..."
export CLAUDE_CODE_MAX_TURNS=5
export CLAUDE_CODE_OUTPUT_FORMAT=json
claude -p "Analyse ce projet"

Avec Node.js 22 LTS et Claude Code v1.0.33+, les performances en mode headless atteignent un temps de démarrage de 800 ms en moyenne. La consommation mémoire reste sous 256 MB pour la plupart des exécutions.

La fiche d'installation et premier lancement détaille la configuration initiale nécessaire avant d'utiliser le mode headless. Vous trouverez aussi dans la fiche sur les commandes slash les commandes utiles pour configurer Claude Code avant de l'automatiser.

À retenir : configurez les variables d'environnement une fois dans votre CI pour simplifier tous vos appels headless.

Comment déboguer un pipeline Claude Code qui échoue ?

Quand un pipeline échoue, suivez cette procédure de diagnostic en 4 étapes.

1. Vérifiez le code de sortie : echo $? après l'appel (0 = succès, 1 = erreur)
2. Activez --verbose pour obtenir les logs détaillés sur stderr
3. Inspectez la sortie JSON : le champ error contient le message d'erreur
4. Testez localement avec le même prompt avant de relancer le pipeline

# Diagnostic complet
claude -p "Mon prompt" \
  --output-format json \
  --verbose 2>debug.log

# Vérifier le code de sortie
echo "Exit code: $?"

# Lire les logs
cat debug.log

Les 3 erreurs les plus fréquentes en CI sont : clé API invalide (42 % des cas), dépassement du --max-turns (28 %) et timeout réseau (18 %). Concrètement, un timeout survient après 120 secondes par défaut.

Pour une liste exhaustive des messages d'erreur et leurs solutions, consultez le guide erreurs courantes du mode headless. L'aide-mémoire sur l'intégration Git vous aide aussi à résoudre les problèmes liés aux opérations Git dans vos pipelines.

À retenir : --verbose et le code de sortie sont vos deux premiers réflexes de débogage en CI.

Faut-il suivre une formation pour maîtriser Claude Code en CI/CD ?

Automatiser Claude Code en CI/CD demande de comprendre les flags, les formats de sortie, les sessions et les bonnes pratiques de sécurité. SFEIR Institute propose des formations structurées pour accélérer cette montée en compétences.

La formation Claude Code d'une journée vous fait pratiquer le mode headless sur des labs concrets : vous construisez un pipeline GitHub Actions complet et configurez les permissions de sécurité de bout en bout.

Pour aller plus loin, la formation Développeur Augmenté par l'IA sur 2 jours couvre l'ensemble des outils IA pour développeurs, dont l'intégration CI/CD avancée avec sessions multi-turn et parsing JSON.

Les développeurs expérimentés peuvent suivre le module Développeur Augmenté par l'IA – Avancé d'une journée, axé sur les architectures de pipelines complexes et l'optimisation des coûts API en production.

À retenir : les formations SFEIR Institute combinent théorie et labs pratiques pour vous rendre opérationnel sur Claude Code en CI/CD dès le premier jour.