Cursor CLI modo headless: --print, --force y scripts que editan archivos

04-non-interactive cubrió --no-interactive para que el Agent corra hasta el final sin esperarte. Este post va más allá: modo headless con -p / --print para ejecuciones "solo salida a terminal", más --force (o --yolo) para que el Agent modifique de verdad los archivos del proyecto — adecuado para CI, JSDoc por lotes, arreglo de lint automático y generación de informes.

En resumen: sin ventana de Cursor, sin confirmaciones por tecla; un script invoca la CLI para cambiar código y el script sigue.

--print: No interactivo, salida a terminal

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

Sin --force: El Agent puede leer archivos, buscar en el código y devolver análisis, pero no escribe en archivos — solo sugiere o imprime en la salida
Útil para: preguntas y respuestas, análisis, escribir informes a stdout, piping o parseo en scripts

Así que -p sola significa "ejecutar hasta el final, salida a terminal"; si cambia archivos depende de si añades --force.

--force: Permitir edición directa de archivos

Con --print y --force (o --yolo), el Agent puede crear, editar y borrar archivos sin preguntar Y/N:

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

Caso de uso	Ejemplo
Refactor de un archivo	`agent -p --force "Refactor src/foo.ts to use async/await"`
Arreglar lint según config	`agent -p --force "Fix all auto-fixable errors per .eslintrc"`
JSDoc por lotes	Ver ejemplo de script abajo
Generar archivo en el proyecto	`agent -p --force "Generate CONTRIBUTING.md from README"`

⚠️ Antes de usar --force en scripts, prueba en un archivo o ámbito pequeño para confirmar el comportamiento y luego escala al repo completo.

Ejemplo de script: JSDoc por lotes

#!/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

Cada archivo lo lee y escribe el Agent; ejecuta en una copia del proyecto o en una rama, o prueba con uno o dos archivos primero.

Ejemplo de script: Code review automático y escribir informe

#!/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 deja la salida en texto plano para escribir a archivo o pipe a grep/scripts. El siguiente post cubre json y stream-json.

Entorno: API key

El modo headless suele ejecutarse donde no hay ventana de Cursor (p. ej. CI, máquina remota), así que hace falta autenticación:

Variable de entorno: export CURSOR_API_KEY=your_key
O ejecuta cursor auth login en ese entorno antes (si está soportado)

Sin ello obtendrás errores y el Agent no correrá.

Diferencia con --no-interactive (breve)

Modo	Uso típico	¿Edita archivos?
`--no-interactive`	Ejecutar en terminal, ver salida paso a paso, sin pulsar tecla	Puede editar, pero puede preguntar (según config)
`-p` / `--print`	Scripts, CI, totalmente no interactivo, salida a stdout	Por defecto no
`-p --force`	Igual, pero permitir que el Agent edite archivos	Sí, sin preguntar

Para scripts que "realmente cambian archivos" usa -p --force; para análisis o informes solo a terminal, basta -p.

Resumen

-p / --print: No interactivo, salida a terminal al terminar; por defecto no edita archivos
--force / --yolo: En modo print, permitir que el Agent edite archivos; útil para scripts y CI
En scripts/CI, configura CURSOR_API_KEY o completa el login
Prueba en un ámbito pequeño antes de ejecutar en todo el repo

Siguiente: 11-output-ci — Formatos de salida text / json / stream-json e integración en CI.