cursor-cli-headless

name	cursor-cli-headless
description	Execute coding tasks using the Cursor CLI in headless print mode. Use when delegating code writing, refactoring, analysis, or review tasks to a headless Cursor agent process, running automated code changes, or batch-processing files with the agent CLI.

Cursor CLI Headless

Execute coding tasks using the Cursor CLI in non-interactive (print) mode via the wrapper script for scripts, automation, and batch processing.

Prerequisites

• Cursor CLI installed: Run agent --version. If missing, install: curl https://cursor.com/install -fsS | bash (macOS/Linux/WSL) or see Installation.
• Authenticated: Set CURSOR_API_KEY in the environment for scripts, or run agent login interactively once. Check if already logged in with agent status or agent whoami.

Quick start

Use scripts/run-task.sh with either an inline prompt or a prompt file:

# Prompt from file (stream progress by default)
./scripts/run-task.sh -f prompt.txt

# Inline prompt, run in a specific project directory
./scripts/run-task.sh -p "Add tests for auth module" -d /path/to/project

Wrapper script: run-task.sh

scripts/run-task.sh runs the Cursor agent in headless mode. Recommended: keep file modifications and stream progress on (default). Use --no-force only with tmux for interactive mode (agent proposes changes for review). Use --no-stream for plain output.

Arguments:

• -p "prompt" — inline prompt (mutually exclusive with -f)
• -f prompt-file.txt — read prompt from file (for long prompts)
• -d dir — working directory (default: current directory)
• -o format — text, json, or stream-json (with default streaming, format is stream-json)
• -m model — model name
• --mode mode — agent, plan, or ask
• --force — allow file modifications (default)
• --no-force — do not modify files; agent only proposes changes
• --stream — stream-json with progress display (default; requires jq for progress)
• --no-stream — plain output only; use with -o text or -o json

Output formats:

Format	Use when
(default stream)	Live progress (model, tool calls, chars); NDJSON on stdout, progress on stderr
-o text --no-stream	Only the final assistant message
-o json --no-stream	Single JSON object with result, duration_ms, etc.; parse with jq -r '.result'

Examples:

# Task from file, apply changes, stream progress (default)
./scripts/run-task.sh -f tasks/refactor-auth.txt

# Inline prompt, specific project, JSON result only
./scripts/run-task.sh -p "Summarize README.md" -d /path/to/repo --no-stream -o json

# Plain text output, no progress
./scripts/run-task.sh -f tasks/review.txt --no-stream -o text

Working directory

The agent runs in the script’s working directory. Use -d /path/to/project so the agent sees that project as the root.

Error handling

• Exit code: Non-zero means the run failed; check stderr for the error message.
• With -o json, on failure no JSON is emitted; only stderr.
• In scripts, check $? after the wrapper and exit accordingly.

Additional resources

• For detailed output schemas and event types: reference.md
• Official docs: Using Headless CLI, Output format