Cursor Headless CLI Automation

Summary

• Document explains using Cursor Headless CLI for scripting, automation, and batch tasks.
• Key features: non-interactive print mode, file modifications with --force, output formats, streaming progress, and media/file support.
• Examples include setup, file modification loops, automated code review, real-time progress tracking, and image/media processing.

Action Items

• (setup – user) Install Cursor CLI and set CURSOR_API_KEY for scripts.
• (immediate – user) Use cursor-agent -p for non-interactive prompts in automation.
• (immediate – user) Add --force when you want the agent to apply file changes.
• (next – user) Choose appropriate --output-format (text, json, stream-json) per use case.
• (next – user) For streaming progress, add --stream-partial-output and parse stream-json events.

How It Works

• Use print mode (-p, --print) for non-interactive scripting and automation.
• Agents can modify files when run with --force; without it, changes are proposed only.
• Including file paths in prompts causes the agent to read files via tool calling.
• Images and other binary files are read transparently through tool calls.
• Output formats control structure and streaming: text, json, stream-json, plus partial output.

Setup

• Install CLI:
  • curl https://cursor.com/install -fsS | bash
• Configure API key:
  • export CURSOR_API_KEY=your_api_key_here
• Verify by running a simple prompt with cursor-agent -p "Analyze this code"

File Modification In Scripts

• Combine --print (-p) with --force to enable automated edits.
• Example pattern:
  • cursor-agent -p --force "Refactor this code to use modern ES6+ syntax"
• Batch example:
  • find src/ -name ".js" | while read file; do cursor-agent -p --force "Add comprehensive JSDoc comments to $file"; done

Example Scripts And Use Cases

• Simple question (text):
  • cursor-agent -p "What does this codebase do?"
• Automated code review (structured output):
  • Use --output-format text or json; write feedback to review.txt
• Batch media processing:
  • for image in images/.png; do cursor-agent -p --output-format text "Describe what's in this image: $image" > "${image%.png}.description.txt"; done

Real-Time Progress Tracking

• Use --output-format stream-json for message-level progress.
• Optionally add --stream-partial-output for incremental deltas.
• Stream events include types: system (init/model), assistant (content deltas), tool_call (started/completed), result (final stats).
• Scripts parse JSON stream (jq) to extract model, tool actions, lines created/read, and duration.

Working With Images And Files

• Reference file paths directly in prompt text; agent reads via tool calls.
• Supported file types include images, videos, and other binaries.
• Paths can be relative or absolute; ensure files are accessible at runtime.
• Example image analysis:
  • cursor-agent -p --output-format json "Analyze this image and provide a detailed description: ./screenshots/ui-mockup.png" | jq -r '.result'

Decisions

• Use print mode (-p) for all non-interactive automation tasks.
• Require --force to allow automatic file edits.
• Prefer stream-json with partial output for live progress feedback.

Open Questions

• None recorded in the provided transcript.

Structured Details