The Cursor CLI and headless runs

Running the agent headless puts it into scripts and pipelines, where safety defaults matter even more.

Cursor also has a command-line agent, the agent command, for terminals and automation. Install it with curl https://cursor.com/install -fsS | bash on macOS, Linux and WSL (Windows PowerShell has its own one-line installer in the docs). Run agent in a project for an interactive terminal session with the same agent, rules and MCP configuration.

For scripts and CI (automated jobs on each push), use print mode:

agent -p "prompt" runs non-interactively and prints the result.
--output-format chooses text (default), json or stream-json; --stream-partial-output adds incremental output with stream-json.
Authenticate with the CURSOR_API_KEY environment variable, stored as a CI secret.

Writing files is opt-in. Without --force (alias --yolo), print mode only proposes changes and does not apply them. With --force it modifies files without confirmation, so pair it with a clean git checkout, a branch, and a review step before anything merges.

Good uses: a nightly job that summarizes recent changes, a review pass that writes findings to a file, a bulk refactor run on a branch and opened as a PR. For CI also consider:

run in an isolated container with minimal credentials,
pin the task with a precise prompt and point at rules or a plan file,
parse json output with a tool like jq instead of scraping text,
treat agent output as untrusted input to later pipeline steps.

For heavier parallel work without your own runners, Cloud Agents and their API are the managed alternative.

Example

# install (macOS / Linux / WSL)
curl https://cursor.com/install -fsS | bash

export CURSOR_API_KEY="$CURSOR_API_KEY_FROM_CI_SECRET"

# read-only question: prints an answer, changes nothing
agent -p "Summarize what changed in src/ since the last release tag"

# allowed to write files: run on a throwaway branch, review before merging
git switch -c chore/agent-review
agent -p --force --output-format text \
  "Review the recent changes and write the findings to review.txt"

# machine-readable result
agent -p --output-format json "List the public API endpoints" | jq -r '.result'

Remember

The agent CLI runs Cursor's agent in a terminal; -p for non-interactive runs
--output-format text|json|stream-json; CURSOR_API_KEY authenticates
Without --force it only proposes changes; with it, isolate and review

Watch out for

Running agent -p --force in CI against the main branch with broad credentials and no review gate.

Check yourself

In print mode without --force, what happens to file changes the agent wants to make?

Official docs: cursor.com/docs/cli/headless

Example

Remember

Watch out for

Check yourself

Builds on

Unlocks