Cursor CLI

Use Cursor Agent CLI as an external agent in PraisonAI

Overview

Cursor Agent CLI is Cursor’s AI-powered coding assistant that provides intelligent code assistance, file operations, and browser automation. PraisonAI integrates with Cursor CLI to use it as an external agent.

Installation

# Install via npm
npm install -g cursor-agent

# Or via pipx
pipx install cursor-agent

Authentication

Login with your Cursor account:

cursor-agent login

Or set API key:

export CURSOR_API_KEY=your-api-key

Basic Usage with PraisonAI

--external-agent cursor invokes Cursor CLI via a manager Agent by default. The manager reasons and calls Cursor as a subagent tool. Use --external-agent-direct for pass-through proxy behavior.

# Manager delegation (default — manager reasons + calls cursor as subagent tool)
praisonai "Fix the bug in auth.py" --external-agent cursor

# Direct proxy (escape hatch — no manager, passes prompt straight to cursor)
praisonai "Fix the bug in auth.py" --external-agent cursor --external-agent-direct

# With verbose output
praisonai "Refactor this module" --external-agent cursor --verbose

CLI Options Reference

Core Options

Option	Description	Default
prompt (positional)	Initial prompt for the agent	-
-v, --version	Output version number	-
-h, --help	Display help	-

Authentication

Option	Description
--api-key <key>	API key (or use CURSOR_API_KEY env var)
-H, --header <header>	Add custom header (format: Name: Value)

Output Options

Option	Description	Default
-p, --print	Print responses to console (non-interactive)	false
--output-format <format>	Output format: text, json, or stream-json	text
--stream-partial-output	Stream partial output as text deltas	false

Model Selection

Option	Description
--model <model>	Model to use (e.g., gpt-5, sonnet-4, sonnet-4-thinking)

Execution Modes

Option	Description	Default
-f, --force	Force allow commands unless explicitly denied	false
-c, --cloud	Start in cloud mode (open composer picker)	false
--browser	Enable browser automation support	false
--approve-mcps	Auto-approve all MCP servers (headless only)	false

Workspace

Option	Description
--workspace <path>	Workspace directory (defaults to current directory)

Session Management

Option	Description
--resume [chatId]	Resume a chat session

Commands

Command	Description
cursor-agent [prompt...]	Start the Cursor Agent (default)
cursor-agent agent [prompt...]	Start the Cursor Agent
cursor-agent login	Authenticate with Cursor
cursor-agent logout	Sign out and clear authentication
cursor-agent status / whoami	View authentication status
cursor-agent update / upgrade	Update to latest version
cursor-agent mcp	Manage MCP servers
cursor-agent create-chat	Create new empty chat and return ID
cursor-agent ls	List chat sessions
cursor-agent resume	Resume latest chat session
cursor-agent install-shell-integration	Install shell integration to ~/.zshrc
cursor-agent uninstall-shell-integration	Remove shell integration

Examples

Basic Query

# Simple question
praisonai "What files are in this directory?" --external-agent cursor

# Code analysis
praisonai "Analyze the code quality" --external-agent cursor

Non-Interactive Mode

# Print mode for scripts
cursor-agent -p "Explain this codebase"

# With specific workspace
cursor-agent -p --workspace /path/to/project "Fix all bugs"

Force Mode

# Allow all commands (use with caution)
cursor-agent -p -f "Refactor and run tests"

Model Selection

# Use GPT-5
cursor-agent -p --model gpt-5 "Complex analysis"

# Use Sonnet 4
cursor-agent -p --model sonnet-4 "Code review"

# Use Sonnet 4 with thinking
cursor-agent -p --model sonnet-4-thinking "Debug this issue"

Output Formats

# Text output (default)
cursor-agent -p --output-format text "Say hello"

# JSON output
cursor-agent -p --output-format json "List functions"

# Streaming JSON
cursor-agent -p --output-format stream-json "Analyze code"

# With partial output streaming
cursor-agent -p --output-format stream-json --stream-partial-output "Long analysis"

Browser Automation

# Enable browser support
cursor-agent -p --browser "Test the login flow in the browser"

Session Management

# Create a new chat
cursor-agent create-chat

# Resume specific chat
cursor-agent --resume abc123 "Continue from where we left off"

# Resume latest chat
cursor-agent resume

# List all chats
cursor-agent ls

Cloud Mode

# Start in cloud mode
cursor-agent -c

Python Integration

from praisonai.integrations import CursorCLIIntegration

# Create integration
cursor = CursorCLIIntegration(
    workspace="/path/to/project",
    output_format="json",
    force=True
)

# Execute a task
result = await cursor.execute("Fix the authentication bug")
print(result)

# With specific model
cursor_gpt5 = CursorCLIIntegration(model="gpt-5")
result = await cursor_gpt5.execute("Complex analysis")

# Stream output
async for event in cursor.stream("Add error handling"):
    print(event)

Environment Variables

Variable	Description
CURSOR_API_KEY	Cursor API key
NO_OPEN_BROWSER	Disable browser opening during login

Output Formats

Text Format (Default)

cursor-agent -p --output-format text "Say hello"
# Output: Hello! How can I help you today?

JSON Format

cursor-agent -p --output-format json "Say hello"

{
  "result": "Hello! How can I help you today?",
  "chatId": "abc123",
  "model": "gpt-5"
}

Stream JSON Format

cursor-agent -p --output-format stream-json "Analyze code"

Real-time JSON events for each step:

{"type": "start", "chatId": "abc123"}
{"type": "content", "delta": "Analyzing..."}
{"type": "tool_use", "tool": "read_file", "args": {"path": "main.py"}}
{"type": "content", "delta": "Found 5 functions..."}
{"type": "end", "result": "Analysis complete"}

Shell Integration

Install shell integration for easier access:

# Install to ~/.zshrc
cursor-agent install-shell-integration

# Remove from ~/.zshrc
cursor-agent uninstall-shell-integration

After installation, you can use cursor command directly in your terminal.

MCP Server Management

# List MCP servers
cursor-agent mcp list

# Add MCP server
cursor-agent mcp add my-server

# Remove MCP server
cursor-agent mcp remove my-server

Related

• External Agents Overview
• Claude CLI
• Gemini CLI
• Codex CLI