Cursor CLI Headless Mode: --print, --force, and Scripts That Edit Files

04-non-interactive covered --no-interactive so the Agent runs to completion without waiting for you. This post goes further: headless mode with -p / --print for “output to terminal only” runs, plus --force (or --yolo), so the Agent actually modifies files in your project—suitable for CI, batch JSDoc, auto lint fixes, and report generation.

In short: no Cursor window, no key confirmations; a script invokes the CLI to change code, then the script continues.

--print: Non-interactive, output to terminal

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

Without --force: The Agent can read files, search the codebase, and return analysis, but won’t write to files—it only “suggests” or prints content in the output
Good for: Q&A, analysis, writing reports to stdout, piping or parsing in scripts

So -p by itself means “run to completion, output to terminal”; whether it changes files depends on whether you add --force.

--force: Allow direct file edits

With --print and --force (or --yolo), the Agent can create, edit, and delete files without asking Y/N:

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

Use case	Example
Single-file refactor	`agent -p --force "Refactor src/foo.ts to use async/await"`
Fix lint per config	`agent -p --force "Fix all auto-fixable errors per .eslintrc"`
Batch JSDoc	See script example below
Generate file in project	`agent -p --force "Generate CONTRIBUTING.md from README"`

⚠️ Before using --force in scripts, run on a single file or small scope first to confirm behavior, then scale to the whole repo.

Script example: Batch JSDoc

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

Each file is read and written by the Agent, so run on a project copy or branch, or try one or two files first.

Script example: Auto code review and write report

#!/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 keeps output plain text for writing to a file or piping to grep/scripts. The next post covers json and stream-json.

Environment: API key

Headless mode often runs where there’s no Cursor window (e.g. CI, remote machine), so you need auth:

Set env: export CURSOR_API_KEY=your_key
Or run cursor auth login in that environment first (if supported)

Without it you’ll get errors and the Agent won’t run.

Difference from --no-interactive (brief)

Mode	Typical use	Edits files?
`--no-interactive`	Run in terminal, watch output step by step, no key press	Can edit, but may still ask (per settings)
`-p` / `--print`	Scripts, CI, fully non-interactive, output to stdout	By default no
`-p --force`	Same, but allow Agent to edit files	Yes, no prompt

So: for scripts that “really change files,” use -p --force; for analysis or reports to the terminal only, -p is enough.

Summary

-p / --print: Non-interactive, output to terminal when done; by default no file edits
--force / --yolo: In print mode, allow the Agent to edit files; good for scripts and CI
In scripts/CI, set CURSOR_API_KEY or complete login
Try on a small scope before running on the whole repo

Next: 11-output-ci — Output formats text / json / stream-json and CI integration examples.