pages/cli/headless.txt

route: /docs/cli/headless
title: Using Headless CLI
description: Run Cursor CLI in headless mode for automation and CI/CD pipelines. Configure non-interactive usage with API keys and scripting support.

Using Headless CLI
Use Cursor CLI in scripts and automation workflows for code analysis, generation, and refactoring tasks.
How it works
Use print mode (-p, --print) for non-interactive scripting and automation.
File modification in scripts
Combine --print with --force (or --yolo) to modify files in scripts:
# Enable file modifications in print mode
agent -p --force "Refactor this code to use modern ES6+ syntax"
# Without --force, changes are only proposed, not applied
agent -p "Add JSDoc comments to this file" # Won't modify files
# Batch processing with actual file changes
find src/ -name "*.js" | while read file; do
agent -p --force "Add comprehensive JSDoc comments to $file"
done
The --force flag allows the agent to make direct file changes without
confirmation
Setup
See Installation and Authentication for complete setup details.
# Install Cursor CLI (macOS, Linux, WSL)
curl https://cursor.com/install -fsS | bash
# Install Cursor CLI (Windows PowerShell)
irm 'https://cursor.com/install?win32=true' | iex
# Set API key for scripts
export CURSOR_API_KEY=your_api_key_here
agent -p "Analyze this code"
Example scripts
Use different output formats for different script needs. See Output format for details.
Searching the codebase
By default, --print uses text format for clean, final-answer-only responses:
#!/bin/bash
# Simple codebase question - uses text format by default
agent -p "What does this codebase do?"
Automated code review
Use --output-format json for structured analysis:
#!/bin/bash
# simple-code-review.sh - Basic code review script
echo "Starting code review..."
# Review recent changes
agent -p --force --output-format text \
"Review the recent code changes and provide feedback on:
- Code quality and readability
- Potential bugs or issues
- Security considerations
- Best practices compliance
Provide specific suggestions for improvement and write to review.txt"
if [ $? -eq 0 ]; then
echo "✅ Code review completed successfully"
else
echo "❌ Code review failed"
exit 1
fi
Real-time progress tracking
Use --output-format stream-json for message-level progress tracking, or add --stream-partial-output for incremental streaming of deltas:
$55
Working with images
To send images, media files, or other binary data to the agent, include file paths in your prompts. The agent can read any files through tool calling, including images, videos, and other formats.
Including file paths in prompts
Simply reference file paths in your prompt text. The agent will automatically read the files when needed:
# Analyze an image
agent -p "Analyze this image and describe what you see: ./screenshot.png"
# Process multiple media files
agent -p "Compare these two images and identify differences: ./before.png ./after.png"
# Combine file paths with text instructions
agent -p "Review the code in src/app.ts and the design mockup in designs/homepage.png. Suggest improvements to match the design."
How it works
When you include file paths in your prompt:
The agent receives your prompt with the file path references
The agent uses tool calling to read the files automatically
Images are handled transparently
You can reference files using relative or absolute paths
Example: Image analysis script
#!/bin/bash
# analyze-image.sh - Analyze images using the headless CLI
IMAGE_PATH="./screenshots/ui-mockup.png"
agent -p --output-format json \
"Analyze this image and provide a detailed description: $IMAGE_PATH" | \
jq -r '.result'
Example: Batch media processing
#!/bin/bash
# process-media.sh - Process multiple media files
for image in images/*.png; do
echo "Processing $image..."
agent -p --output-format text \
"Describe what's in this image: $image" > "${image%.png}.description.txt"
done
File paths can be relative to the current working directory or absolute paths.
The agent will read files through tool calls, so ensure the files exist and
are accessible from where you run the command.