Mode headless et CI/CD - Référence des commandes

Le mode headless de Claude Code permet d'exécuter des prompts directement depuis le terminal ou un pipeline CI/CD, sans interface interactive. Ce guide de référence détaille la syntaxe du flag -p, les formats de sortie disponibles et les intégrations GitHub Actions pour automatiser vos workflows de développement.

Le mode headless et CI/CD de Claude Code est un ensemble de commandes et flags qui transforment l'agent IA en outil scriptable pour l'automatisation. Claude Code v1.0.33 prend en charge trois formats de sortie (text, json, stream-json) et s'intègre nativement dans les pipelines GitHub Actions, GitLab CI et Jenkins. plus de 40 % des utilisateurs avancés exploitent le mode headless dans au moins un workflow CI/CD.

Quelles sont les commandes headless les plus utilisées ?

Voici le tableau de référence rapide des commandes essentielles du mode headless. Chaque commande fonctionne sans interface interactive et retourne un code de sortie exploitable dans vos scripts.

Pour une vue d'ensemble du fonctionnement général, consultez le guide complet du mode headless et CI/CD qui couvre les concepts fondamentaux.

À retenir : le flag -p (print) est le point d'entrée unique du mode headless - il désactive l'interface interactive et renvoie la réponse sur stdout.

Comment utiliser le flag -p pour exécuter Claude Code en une commande ?

Le flag -p (ou --print) est la commande fondamentale du mode headless. Passez votre prompt entre guillemets directement après le flag. Claude Code traite la requête, affiche la réponse sur stdout, puis termine le processus.

# Prompt simple en une ligne
claude -p "Génère une fonction Python de tri rapide"

# Prompt multi-lignes avec heredoc
claude -p <<'EOF'
Analyse ce code et suggère des améliorations :
- Performance
- Lisibilité
- Tests manquants
EOF

Le flag -p accepte un contexte via stdin. En pratique, cette combinaison avec le pipe Unix couvre 80 % des cas d'usage headless.

# Pipe du contenu d'un fichier
cat src/utils.ts | claude -p "Ajoute les types TypeScript manquants"

# Pipe d'un diff Git pour review automatique
git diff HEAD~1 | claude -p "Review ce diff, liste les problèmes potentiels"

Voici comment combiner plusieurs flags pour un contrôle précis de l'exécution. La référence des commandes de base détaille les flags partagés entre le mode interactif et headless.

Le mode headless retourne un code de sortie 0 en cas de succès et un code non-nul en cas d'erreur, ce qui permet de l'intégrer dans des scripts conditionnels avec && ou ||.

À retenir : combinez -p avec le pipe Unix pour injecter du contexte (fichiers, diffs, logs) directement dans votre prompt.

Comment intégrer Claude Code dans GitHub Actions ?

GitHub Actions est la plateforme CI/CD la plus courante pour automatiser Claude Code en mode headless. Configurez votre workflow YAML en stockant votre clé API dans les secrets du repository. 65 % des projets open-source utilisent GitHub Actions comme pipeline CI principal.

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 code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git diff origin/main...HEAD | claude -p \
            "Review ce diff. Liste les bugs, failles de sécurité et suggestions." \
            --output-format json > review.json

Pour éviter les erreurs fréquentes d'authentification et de permissions, consultez la page des erreurs courantes du mode headless qui recense les messages d'erreur les plus fréquents.

Concrètement, limitez le coût API en ajoutant --max-turns 3 dans vos workflows de review. Chaque tour agentic consomme des tokens supplémentaires - un review de diff standard nécessite rarement plus de 2 tours.

      - name: Generate changelog
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git log --oneline origin/main...HEAD | claude -p \
            "Génère un changelog structuré en Markdown" \
            --max-turns 1 \
            --output-format text > CHANGELOG_PR.md

La variable d'environnement ANTHROPIC_API_KEY est le seul secret requis. Stockez cette clé dans les settings du repository GitHub sous Settings → Secrets and variables → Actions.

À retenir : ajoutez toujours --max-turns dans vos workflows CI pour contrôler les coûts et la durée d'exécution.

Quels sont les formats de sortie disponibles et comment les parser ?

Claude Code en mode headless prend en charge trois formats de sortie distincts. Choisissez le format adapté à votre cas d'usage : text pour la lecture humaine, json pour le parsing programmatique, stream-json pour le traitement en temps réel.

Comment exploiter le format text ?

Le format text est le mode par défaut. La réponse s'affiche directement sur stdout sans enveloppe ni métadonnées. Redirigez la sortie avec > ou parsez-la avec les outils Unix classiques.

# Sortie texte redirigée vers un fichier
claude -p "Génère un README pour ce projet" --output-format text > README.md

# Extraction d'une ligne spécifique
claude -p "Liste les dépendances obsolètes" | grep "CRITICAL"

Comment exploiter le format json ?

Le format json retourne un objet structuré contenant la réponse, les métadonnées de session et les statistiques de tokens. Utilisez jq pour extraire les champs pertinents.

# Extraction de la réponse uniquement
claude -p "Analyse ce code" --output-format json | jq -r '.result'

# Extraction du coût en tokens
claude -p "Résume ce fichier" --output-format json | jq '.usage'

La structure JSON retournée contient entre 5 et 8 champs selon le contexte. En pratique, le champ .result contient la réponse textuelle et .usage.output_tokens indique le nombre de tokens générés.

Pour aller plus loin sur les combinaisons de commandes, la page d'exemples du mode headless propose des scripts prêts à l'emploi.

Comment exploiter le format stream-json ?

Le format stream-json émet un événement JSON par ligne (NDJSON). Chaque événement contient un type (assistant, tool_use, result) et un payload partiel. Traitez ce flux avec un parser NDJSON comme jq --stream ou une bibliothèque Node.js.

# Lecture du flux en temps réel
claude -p "Refactorise ce module" --output-format stream-json | \
  while IFS= read -r line; do
    echo "$line" | jq -r 'select(.type == "assistant") | .content'
  done

À retenir : utilisez json pour le post-traitement automatisé et stream-json pour les intégrations temps réel (dashboards, notifications).

Comment gérer des sessions multi-turn programmatiques ?

Une session multi-turn permet de maintenir le contexte entre plusieurs appels headless successifs. Récupérez l'identifiant de session après le premier appel, puis réutilisez-le avec --session-id pour poursuivre la conversation.

# Premier appel : récupérer le session ID
RESPONSE=$(claude -p "Analyse l'architecture de ce projet" --output-format json)
SESSION_ID=$(echo "$RESPONSE" | jq -r '.session_id')

# Deuxième appel : poursuivre dans la même session
claude -p "Maintenant, propose un plan de refactoring" \
  --session-id "$SESSION_ID" \
  --output-format json > plan.json

# Troisième appel : demander l'implémentation
claude -p "Implémente le point 1 du plan" \
  --session-id "$SESSION_ID" \
  --max-turns 5

L'identifiant de session est un UUID de 36 caractères. Chaque session conserve l'historique complet des échanges, ce qui augmente la consommation de tokens à chaque tour. En pratique, une session de 5 tours consomme en moyenne 3 fois plus de tokens qu'un appel unique.

Vous pouvez aussi reprendre une session existante depuis l'historique. Consultez l'aide-mémoire des premières conversations pour comprendre la gestion du contexte conversationnel.

Concrètement, les sessions multi-turn sont utiles pour les workflows en plusieurs étapes : analyse → planification → implémentation → validation.

À retenir : limitez vos sessions multi-turn à 5-7 tours maximum pour maîtriser la consommation de tokens et éviter la dégradation du contexte.

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

Au-delà du simple code review, Claude Code en mode headless couvre des scénarios d'automatisation avancés. Voici comment l'utiliser pour la génération de documentation, les tests automatisés et l'analyse de sécurité.

Génération automatique de documentation

# Générer la JSDoc pour tous les fichiers TypeScript modifiés
git diff --name-only origin/main...HEAD -- '*.ts' | \
  xargs -I {} claude -p "Ajoute la JSDoc manquante à ce fichier : $(cat {})" \
  --max-turns 1 > docs_output.txt

Analyse de sécurité automatisée

# Scanner les vulnérabilités dans le diff
git diff origin/main...HEAD | claude -p \
  "Analyse ce diff pour détecter : injection SQL, XSS, secrets exposés, dépendances vulnérables. Format JSON." \
  --output-format json \
  --allowedTools Read \
  --max-turns 2 > security_report.json

La restriction --allowedTools Read garantit que Claude Code ne modifie aucun fichier pendant l'analyse. 70 % des vulnérabilités détectées en CI proviennent de dépendances tierces.

Pour découvrir d'autres automatisations avancées, les astuces des premières conversations partagent des techniques de prompting applicables au mode headless.

Tests et validation automatisés

# Vérifier que le code respecte les conventions
claude -p "Vérifie que ce code respecte les conventions ESLint et Prettier" \
  --allowedTools Bash,Read \
  --max-turns 3

# Générer des tests unitaires pour les fichiers modifiés
git diff --name-only HEAD~1 -- '*.ts' | \
  xargs -I {} claude -p "Génère des tests Jest pour {}" \
  --max-turns 2

SFEIR Institute propose la formation Développeur Augmenté par l'IA – Avancé sur 1 jour, qui couvre précisément l'intégration de Claude Code dans les pipelines CI/CD avec des labs pratiques sur GitHub Actions et GitLab CI.

À retenir : restreignez toujours les outils autorisés (--allowedTools) dans les workflows CI pour garantir la sécurité et la prédictibilité de l'exécution.

Comment combiner les commandes headless les plus fréquentes ?

Voici les one-liners les plus utiles pour vos workflows quotidiens. Chaque combinaison exploite le pipe Unix et les flags headless pour résoudre un problème concret.

# Review de PR complète avec rapport JSON
git diff origin/main...HEAD | claude -p "Code review détaillée" --output-format json | jq '.result' > review.md

# Commit message automatique basé sur le diff
git diff --staged | claude -p "Génère un message de commit conventionnel (type: description)" --max-turns 1

# Résumé d'un fichier de logs
tail -n 500 app.log | claude -p "Résume les erreurs critiques des 500 dernières lignes" --output-format text

# Conversion de code avec contrainte de modèle
cat legacy.py | claude -p "Convertis ce code Python 2 en Python 3.12" -m claude-sonnet-4-6 --max-turns 1

# Documentation API automatique
cat src/api/routes.ts | claude -p "Génère la documentation OpenAPI 3.1 en YAML" > openapi.yaml

Exécutez ces combinaisons directement dans votre terminal ou intégrez-les dans des Makefiles. La référence des commandes slash complète cette liste avec les commandes disponibles en mode interactif.

Vous pouvez aussi enchaîner les commandes avec des conditions. Concrètement, un pipeline de validation en 3 étapes tient en une seule ligne :

# Pipeline : lint → review → test generation
claude -p "Lint ce fichier" --max-turns 1 && \
claude -p "Review les problèmes restants" --max-turns 2 && \
claude -p "Génère les tests manquants" --max-turns 3

À retenir : chaînez vos commandes headless avec && pour créer des pipelines séquentiels robustes - chaque étape ne s'exécute que si la précédente réussit.

Quels raccourcis clavier accélèrent le workflow headless ?

En mode headless, les raccourcis clavier s'appliquent principalement lors de la phase de développement et de test des prompts en mode interactif, avant de les porter dans vos scripts.

Activez l'autocomplétion pour gagner du temps sur la saisie des flags. L'aide-mémoire d'installation explique comment configurer le script de complétion pour votre shell.

Vous pouvez aussi créer des alias shell pour vos commandes headless fréquentes. Ajoutez ces lignes à votre .zshrc ou .bashrc :

# Alias pour les commandes headless fréquentes
alias cr='claude -p "Code review du diff staged" --max-turns 2'
alias cfix='claude -p "Corrige les erreurs dans ce fichier" --max-turns 3'
alias cdoc='claude -p "Génère la documentation" --max-turns 1'
alias ctest='claude -p "Génère des tests unitaires" --max-turns 2'

La formation SFEIR Claude Code d'une journée vous permet de pratiquer ces commandes headless avec des exercices guidés, du premier flag -p jusqu'à l'intégration CI/CD complète.

À retenir : créez des alias shell pour vos 5 commandes headless les plus fréquentes - vous gagnerez en moyenne 15 secondes par invocation.

Comment configurer les permissions et la sécurité en CI/CD ?

La sécurité en mode headless repose sur trois mécanismes : la restriction des outils, les variables d'environnement et les timeouts. Configurez ces paramètres avant tout déploiement en production.

# Exécution sécurisée : outils limités + timeout
timeout 120 claude -p "Analyse ce code" \
  --allowedTools Read,Grep,Glob \
  --max-turns 2 \
  --no-user-prompt

Le flag --no-user-prompt empêche Claude Code de demander une confirmation utilisateur, ce qui bloquerait un pipeline non-interactif. Le timeout système (120 secondes dans cet exemple) protège contre les exécutions infinies.

Vérifiez que votre clé API dispose des permissions minimales nécessaires. En pratique, une clé dédiée CI avec un budget mensuel plafonné à 50 USD couvre la plupart des workflows de review et documentation.

Pour configurer les commandes personnalisées utilisables en headless, la référence des commandes personnalisées et skills détaille la syntaxe des fichiers de configuration.

Pour maîtriser l'ensemble de ces techniques d'automatisation, la formation Développeur Augmenté par l'IA sur 2 jours couvre l'intégration complète de l'IA dans votre workflow de développement, des fondamentaux aux patterns CI/CD avancés.

À retenir : isolez toujours vos clés API CI dans des secrets dédiés et plafonnez le budget pour éviter les surprises de facturation.

Peut-on déboguer les exécutions headless qui échouent ?

Le débogage en mode headless suit une approche systématique. Activez le mode verbose, vérifiez les codes de sortie et inspectez les logs pour identifier la cause de l'échec.

# Mode verbose pour le diagnostic
claude -p "Commande qui échoue" --verbose 2> debug.log

# Vérifier le code de sortie
claude -p "Test" --max-turns 1; echo "Exit code: $?"

Les codes de sortie suivent la convention Unix : 0 signifie succès, 1 signifie erreur générale, 2 signifie erreur d'arguments. 85 % des erreurs headless proviennent de trois causes : clé API invalide, timeout dépassé ou outil non autorisé.

Consultez la liste complète des messages d'erreur dans la page des erreurs courantes du mode headless pour un diagnostic rapide.

Testez vos prompts en mode interactif avant de les déployer en CI. Les astuces pour vos conversations proposent des techniques de formulation qui réduisent les erreurs de 30 % en moyenne.

À retenir : testez systématiquement vos commandes headless en local avec --verbose avant de les intégrer dans un pipeline CI/CD.

---