Cursor CLI mode headless : --print, --force et scripts qui modifient les fichiers

04-non-interactive a couvert --no-interactive pour que l’Agent aille au bout sans vous attendre. Ce billet va plus loin : mode headless avec -p / --print pour des runs « sortie terminal uniquement », plus --force (ou --yolo) pour que l’Agent modifie réellement les fichiers du projet — adapté à la CI, JSDoc par lot, correction lint auto et génération de rapports.

En bref : pas de fenêtre Cursor, pas de confirmation clavier ; un script appelle la CLI pour modifier le code, puis le script continue.

--print : non interactif, sortie vers le terminal

cursor agent -p "What does this project do?"
# or
cursor agent --print "List all API endpoints under src/"

Sans --force : l’Agent peut lire les fichiers, chercher dans le code et renvoyer une analyse, mais n’écrit pas dans les fichiers — il ne fait que suggérer ou imprimer dans la sortie
Utile pour : Q&A, analyse, écriture de rapports vers stdout, piping ou parsing dans des scripts

Donc -p seul signifie « exécuter jusqu’au bout, sortie vers le terminal » ; s’il modifie des fichiers dépend de l’ajout de --force.

--force : autoriser l’édition directe des fichiers

Avec --print et --force (ou --yolo), l’Agent peut créer, modifier et supprimer des fichiers sans demander O/N :

cursor agent -p --force "Refactor src/utils.js to ES6+ syntax"

Cas d’usage	Exemple
Refactor d’un fichier	`agent -p --force "Refactor src/foo.ts to use async/await"`
Corriger le lint selon la config	`agent -p --force "Fix all auto-fixable errors per .eslintrc"`
JSDoc par lot	Voir l’exemple de script ci-dessous
Générer un fichier dans le projet	`agent -p --force "Generate CONTRIBUTING.md from README"`

⚠️ Avant d’utiliser --force dans des scripts, testez d’abord sur un fichier ou un périmètre restreint pour confirmer le comportement, puis passez à tout le repo.

Exemple de script : JSDoc par lot

#!/bin/bash
# For each .js under src/, ask Agent to add JSDoc and write directly
find src/ -name "*.js" | while read -r file; do
  echo "Processing $file..."
  cursor agent -p --force "Add full JSDoc comments to $file, editing the file in place"
done

Chaque fichier est lu et écrit par l’Agent ; exécutez sur une copie du projet ou une branche, ou testez d’abord sur un ou deux fichiers.

Exemple de script : revue de code auto et écriture du rapport

#!/bin/bash
cursor agent -p --force --output-format text \
  "Do a code review of recent changes: readability, potential bugs, security, best practices. Write conclusions and concrete suggestions to review.txt"

--output-format text garde la sortie en texte brut pour écriture dans un fichier ou piping vers grep/scripts. Le prochain billet couvre json et stream-json.

Environnement : clé API

Le mode headless tourne souvent là où il n’y a pas de fenêtre Cursor (ex. CI, machine distante), donc il faut l’auth :

Variable d’environnement : export CURSOR_API_KEY=your_key
Ou exécutez cursor auth login dans cet environnement d’abord (si supporté)

Sans ça vous aurez des erreurs et l’Agent ne tournera pas.

Différence avec --no-interactive (en bref)

Mode	Usage typique	Modifie les fichiers ?
`--no-interactive`	Run en terminal, voir la sortie pas à pas, pas de touche	Peut modifier, mais peut demander (selon config)
`-p` / `--print`	Scripts, CI, totalement non interactif, sortie vers stdout	Par défaut non
`-p --force`	Idem, mais autoriser l’Agent à modifier les fichiers	Oui, sans demander

Donc : pour des scripts qui « modifient vraiment les fichiers », utilisez -p --force ; pour de l’analyse ou des rapports uniquement vers le terminal, -p suffit.

Résumé

-p / --print : non interactif, sortie vers le terminal à la fin ; par défaut pas d’édition de fichiers
--force / --yolo : en mode print, autoriser l’Agent à modifier les fichiers ; utile pour scripts et CI
En scripts/CI, définissez CURSOR_API_KEY ou complétez le login
Testez sur un petit périmètre avant de lancer sur tout le repo

Suivant : 11-output-ci — Formats de sortie text / json / stream-json et exemples d’intégration CI.