Ton premier claude -p : une question, une réponse, puis du JSON

Vérifier que tout est prêt

Ouvre un terminal dans un de tes projets. Deux commandes suffisent, les mêmes dans Bash et dans PowerShell :

claude --version
claude auth status

La première affiche ta version de Claude Code. Si elle est ancienne, claude update la met à jour. La seconde affiche ta connexion en JSON, un format de texte structuré en paires « nom : valeur » que tous les langages savent lire. Regarde le champ authMethod :

• claude.ai : tu passes par ton abonnement ;
• api_key : tu passes par une clé API de la Console, facturée à chaque appel ;
• none : tu n'es pas connecté. Lance claude une fois et suis la connexion dans ton navigateur.

Une question, une réponse

claude -p "En trois phrases, à quoi sert ce projet ?"

Claude lit les fichiers dont il a besoin, écrit sa réponse dans le terminal, puis s'arrête. Aucune session ne reste ouverte, aucune question ne t'est posée. Les lectures de fichiers dans ton dossier de travail ne demandent pas d'autorisation, donc tout passe.

Chaque exécution rend aussi un code de sortie : 0 si tout s'est bien passé, un autre nombre en cas d'échec. Un script peut décider de la suite d'après ce code. Pour le voir :

claude -p "En une phrase, à quoi sert ce projet ?"
echo "Code de sortie : $?"

claude -p "En une phrase, à quoi sert ce projet ?"
Write-Host "Code de sortie : $LASTEXITCODE"

Un détail qui surprend : si l'échec arrive pendant l'exécution, une connexion manquante par exemple, Claude Code écrit le message d'échec à la place de la réponse. Fie-toi donc au code de sortie, pas seulement au texte affiché.

Lui envoyer un texte par un tuyau

Un tuyau (« pipe », le caractère |) envoie la sortie d'une commande dans la suivante. claude -p lit ce qui arrive par ce tuyau. Tu peux lui passer un journal d'erreurs, le résultat d'un test, ou un diff (la liste des lignes modifiées, affichée par git diff).

git diff | claude -p "Relis ces modifications et signale seulement les fautes de frappe"

La documentation note un avantage : le texte arrive par le tuyau, donc Claude n'a pas besoin de la permission de lancer git lui-même. Une limite : 10 Mo au plus par le tuyau. Au-delà, écris le contenu dans un fichier et donne son chemin dans ta demande.

Sous Windows PowerShell 5.1 : les accents

Le PowerShell installé avec Windows (la version 5.1) envoie par défaut le texte d'un tuyau en ASCII, un jeu de caractères sans accents. Un « é » arrive alors sous la forme d'un point d'interrogation. Ces deux lignes passent ta fenêtre en UTF-8, le jeu de caractères qui garde les accents :

$OutputEncoding = [System.Text.UTF8Encoding]::new()
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()

La première règle ce que PowerShell envoie par le tuyau. La seconde règle la façon dont il relit ce que les programmes lui répondent. Elles valent pour la fenêtre ouverte : mets-les en tête de tes scripts.

Une réponse en JSON

Le texte libre est fait pour toi. Pour un script, il faut une réponse en JSON :

claude -p "En une phrase, à quoi sert ce projet ?" --output-format json > reponse.json

Le fichier contient un seul objet JSON. Les champs qui servent tout de suite :

• result : le texte de la réponse ;
• session_id : l'identifiant de la conversation, pour la reprendre plus tard ;
• is_error : true si l'exécution a échoué ;
• num_turns : le nombre de tours de travail ;
• total_cost_usd : le coût estimé, en dollars.

Ce coût est calculé sur ta machine, au prix public de l'API. Avec un abonnement Pro ou Max, la documentation précise que ce chiffre ne compte pas pour la facturation : ton usage est compris dans l'abonnement. Il reste utile pour comparer deux exécutions.

Pour lire ces champs dans Bash, l'outil courant s'appelle jq. Installe-le avec brew install jq sur macOS, sudo apt-get install jq sur Debian ou Ubuntu, winget install jqlang.jq sous Windows, puis :

jq -r '.result' reponse.json
jq '.total_cost_usd' reponse.json

PowerShell sait lire le JSON sans rien installer :

$reponse = claude -p "En une phrase, à quoi sert ce projet ?" --output-format json | Out-String | ConvertFrom-Json
$reponse.result
$reponse.total_cost_usd

Une réponse dans la forme que tu imposes

Même en JSON, result reste un texte libre. Pour une réponse dont la forme est garantie, ajoute --json-schema. Un schéma JSON décrit la forme attendue : quels champs, de quel type. Claude Code range alors la réponse dans le champ structured_output.

claude -p "Liste les commandes déclarées dans package.json" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"commandes":{"type":"array","items":{"type":"string"}}},"required":["commandes"]}' \
  | jq '.structured_output.commandes'

Si le schéma n'est pas valide, Claude Code s'arrête tout de suite avec le message Error: --json-schema is not a valid JSON Schema.

Ce que ça change vraiment

Avec une forme imposée, un script peut prendre une décision d'après l'avis de Claude. Voici un exemple, à lancer avant un commit : il bloque si Claude repère une ligne de débogage oubliée.

oubli=$(git diff --cached | claude -p "Ces modifications laissent-elles une ligne de débogage oubliée, comme console.log, print ou var_dump ?" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"oubli":{"type":"boolean"},"lignes":{"type":"array","items":{"type":"string"}}},"required":["oubli","lignes"]}' \
  | jq -r '.structured_output.oubli')

if [ "$oubli" = "true" ]; then
  echo "Une ligne de débogage semble oubliée : relis avant de commiter."
  exit 1
fi

git diff --cached montre ce que tu t'apprêtes à commiter. Claude répond true ou false, jamais une phrase à interpréter. C'est la brique de base de tout le reste de la formation.

Ce que la suite t'apporte

Tu sais maintenant lancer Claude sans session et lire sa réponse dans un script. La suite te montre comment le faire sans mauvaise surprise :

• les options qui bornent une exécution : outils permis, mode de permission, nombre de tours, budget, modèle, et ce qu'il charge au démarrage ;
• l'enchaînement de plusieurs appels qui partagent la même conversation, dans un pipeline avec un contrôle entre chaque étape ;
• une relecture automatique de chaque demande de fusion avec GitHub Actions, secrets et permissions compris ;
• les boucles et les tâches planifiées, ce qui est stable et ce qui est en préversion ;
• les garde-fous, puis la vérification d'un travail fait sans toi.

Sources

Pages officielles vérifiées le 19 octobre 2026 :

• Lancer Claude Code en mode non interactif
• Référence de la ligne de commande
• L'authentification et l'ordre des identifiants
• Suivre les coûts
• Télécharger jq
• PowerShell : la variable $OutputEncoding
• PowerShell : passer des arguments avec des guillemets