#cursor#cli#ci#output-format#automation

Formats de sortie Cursor CLI et intégration CI

4 min read

Le billet précédent 10-headless-scripts utilisait -p --force pour modifier des fichiers depuis des scripts. Celui-ci porte sur le format de sortie : pour une même exécution de l’Agent vous pouvez choisir « texte final uniquement », « JSON structuré complet » ou « JSON en stream pendant l’exécution » — en CI vous parsez les résultats, mesurez le temps ou affichez la progression avec ces trois formats.

Trois formats de sortie

Format Option Idéal pour
text Par défaut, ou --output-format text Lecture humaine, réponse finale seule, écriture dans un fichier
json --output-format json Parsing dans des scripts, pass/fail CI, extraction de champs
stream-json --output-format stream-json Progression en direct, suivi des appels d’outils, surveillance de runs longs

text : Réponse finale propre

cursor agent -p "What is the entry point of this repo?"

Sans --output-format vous obtenez du texte : la sortie est uniquement la réponse finale, sans tool calls ni étapes intermédiaires — pratique pour coller dans la doc ou comme courte description.

En CI, pour écrire la conclusion de l’Agent dans un fichier :

cursor agent -p "Generate release notes for this version from CHANGELOG" > release_notes.txt

json : Pour scripts et CI

cursor agent -p --output-format json "Analyze src/ dependencies and return JSON: { \"entry\": \"...\", \"deps\": [...] }"

La sortie est du JSON structuré, avec éventuellement result, duration_ms ou des champs demandés dans le prompt.
En CI vous pouvez :

  • Utiliser jq pour extraire des champs, vérifier le vide ou chercher des mots-clés
  • Utiliser le code de sortie et le contenu pour décider du pass/fail du job

Exemple conceptuel :

cursor agent -p --output-format json "Do a short code review; return {\"ok\": true/false, \"summary\": \"...\"}" | jq -r '.result'
# Then use .ok or .summary for next steps or to fail the build

Les champs exacts dépendent de la doc Cursor ; l’idée est « json pour parsing programmatique ».

stream-json : Progression en direct et suivi des outils

cursor agent -p --output-format stream-json --stream-partial-output "Analyze project and write analysis.txt"
  • Chaque ligne est un événement JSON (ex. system, assistant, tool_call, result)
  • --stream-partial-output envoie le texte de l’assistant en deltas incrémentales, pour afficher « nombre de caractères en direct » ou « % de progression »
  • Parsez tool_call started/completed pour voir quel fichier l’Agent lit/écrit et combien de temps ça prend

Utile pour : runs longs, afficher « traitement du fichier N » dans les logs CI ou une UI, ou compter les tool calls et la durée.

Conseils d’intégration CI

Besoin Suggestion
Seulement « est-ce terminé et quelle est la conclusion ? » text + redirection vers fichier ou variable ; vérifier le code de sortie
Pass/fail selon le contenu json + parsing avec jq
Log ou progression en direct stream-json + parsing ligne à ligne par type/sous-type
L’Agent doit modifier des fichiers Ajoutez --force (voir 10-headless-scripts)
Exécution en CI Définissez CURSOR_API_KEY ; utilisez --model pour figer le modèle si besoin

Gestion des échecs

  • Quand l’exécution de l’Agent échoue, la CLI renvoie en général un code de sortie non nul
  • Dans les scripts utilisez if [ $? -ne 0 ]; then exit 1; fi ou set -e pour que la CI échoue correctement
  • Avec json vous pouvez aussi vérifier un champ error ou votre ok: false personnalisé pour plus de sécurité

Résumé

  • text : Par défaut, lisible, sortie minimale ; bon pour écrire dans un fichier ou comme description
  • json : Structuré pour jq ou scripts ; bon pour les décisions CI et l’extraction
  • stream-json + --stream-partial-output : Flux d’événements en direct ; bon pour la progression et le suivi des outils
  • En CI : définissez CURSOR_API_KEY, respectez le code de sortie et parsez le JSON pour pass/fail quand nécessaire

Suivant : 12-sessions-cloud — Reprise de session avec --resume et exécution cloud avec -c.