Praison AI

Cursor CLI

Use Cursor Agent CLI as an external agent in PraisonAI

Overview

!Cursor CLI for Code Refactoring

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

bash
# Install via npm
npm install -g cursor-agent

# Or via pipx
pipx install cursor-agent

Authentication

Login with your Cursor account:

bash
cursor-agent login

Or set API key:

bash
export CURSOR_API_KEY=your-api-key

Basic Usage with PraisonAI

bash
# 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

OptionDescriptionDefault
prompt (positional)Initial prompt for the agent–
-v, --versionOutput version number–
-h, --helpDisplay help–

Authentication

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

Output Options

OptionDescriptionDefault
-p, --printPrint responses to console (non-interactive)false
--output-format <format>Output format: text, json, or stream-jsontext
--stream-partial-outputStream partial output as text deltasfalse

Model Selection

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

Execution Modes

OptionDescriptionDefault
-f, --forceForce allow commands unless explicitly deniedfalse
-c, --cloudStart in cloud mode (open composer picker)false
--browserEnable browser automation supportfalse
--approve-mcpsAuto-approve all MCP servers (headless only)false

Workspace

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

Session Management

OptionDescription
--resume [chatId]Resume a chat session

Commands

CommandDescription
cursor-agent [prompt...]Start the Cursor Agent (default)
cursor-agent agent [prompt...]Start the Cursor Agent
cursor-agent loginAuthenticate with Cursor
cursor-agent logoutSign out and clear authentication
cursor-agent status / whoamiView authentication status
cursor-agent update / upgradeUpdate to latest version
cursor-agent mcpManage MCP servers
cursor-agent create-chatCreate new empty chat and return ID
cursor-agent lsList chat sessions
cursor-agent resumeResume latest chat session
cursor-agent install-shell-integrationInstall shell integration to ~/.zshrc
cursor-agent uninstall-shell-integrationRemove shell integration

Examples

Basic Query

bash
# 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

bash
# 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

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

Model Selection

bash
# 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

bash
# 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

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

Session Management

bash
# 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

bash
# Start in cloud mode
cursor-agent -c

Python Integration

python
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

VariableDescription
CURSOR_API_KEYCursor API key
NO_OPEN_BROWSERDisable browser opening during login

Output Formats

Text Format (Default)

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

JSON Format

bash
cursor-agent -p --output-format json "Say hello"
json
{
  "result": "Hello! How can I help you today?",
  "chatId": "abc123",
  "model": "gpt-5"
}

Stream JSON Format

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

Real-time JSON events for each step:

json
{"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:

bash
# 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

bash
# 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