Cursor headless (`cursor-agent -p`)

Drive Cursor Agent CLI non-interactively. The commands below were checked with cursor-agent 2026.09.02-c22c1a3.

Core call

cursor-agent -p --trust --auto-review --sandbox disabled "<task>" \
  --model cursor-grok-4.6-high-fast --output-format json 2>err.log > out.json

stdout carries exactly one JSON object — keep stderr redirected away from it.
Read from the JSON: .result (final answer), .session_id, .is_error, .subtype (success), .usage (token counts), .request_id.
Pipe input via stdin: echo "data" | cursor-agent -p --trust --auto-review --sandbox disabled --model cursor-grok-4.6-high-fast "<prompt about the piped input>". Stdin is appended to the prompt argument.
Exit codes: 0 success, 1 error (bad model, missing trust, auth failure) with the reason on stderr. Check both the exit code and .is_error.
--trust is mandatory headless. Without it the run dies with exit 1 and a "Workspace Trust Required" prompt on stderr.
Install: curl https://cursor.com/install -fsS | bash (lands in ~/.local/bin as cursor-agent and agent). Update with cursor-agent update. Auth: cursor-agent login (browser) or CURSOR_API_KEY env var for CI.