Skip to main content

Cursor CLI Integration

PraisonAI provides integration with Cursor’s CLI (cursor-agent) for headless code automation, file modifications, and streaming output.

Installation

Download and install Cursor from cursor.com, which includes the CLI.
# Verify installation
cursor-agent --version

Quick Start

from praisonai.integrations import CursorCLIIntegration

# Create integration
cursor = CursorCLIIntegration(
    workspace="/path/to/project",
    force=True  # Allow file modifications
)

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

Configuration Options

OptionTypeDefaultDescription
workspacestr”.”Working directory for CLI execution
timeoutint300Timeout in seconds
output_formatstr”json”Output format: “json”, “text”, “stream-json”
forceboolFalseAllow file modifications
modelstrNoneModel to use (e.g., “gpt-5”)
stream_partialboolFalseStream partial output
resume_sessionstrNoneSession ID to resume

Examples

Basic Execution

from praisonai.integrations import CursorCLIIntegration

cursor = CursorCLIIntegration(workspace="/project")

result = await cursor.execute("Explain the main.py file")
print(result)

Force Mode (File Modifications)

cursor = CursorCLIIntegration(
    workspace="/project",
    force=True  # Enable file modifications
)

result = await cursor.execute("Refactor the utils module")

Model Selection

cursor = CursorCLIIntegration(
    workspace="/project",
    model="gpt-5"  # Use GPT-5
)

result = await cursor.execute("Complex refactoring task")

Session Resume

cursor = CursorCLIIntegration(workspace="/project")

# First task
result1 = await cursor.execute("Analyze the codebase")

# Resume with a specific session
cursor_resume = CursorCLIIntegration(
    workspace="/project",
    resume_session="session-abc123"
)

result2 = await cursor_resume.execute("Continue the analysis")

Streaming Output

cursor = CursorCLIIntegration(
    workspace="/project",
    stream_partial=True
)

async for event in cursor.stream("Add comprehensive tests"):
    event_type = event.get("type")
    content = event.get("content", "")
    
    if event_type == "text":
        print(content, end="", flush=True)
    elif event_type == "tool_use":
        print(f"\n[Tool: {event.get('name')}]")
    elif event_type == "result":
        print(f"\nResult: {content}")

As Agent Tool

from praisonai import Agent
from praisonai.integrations import CursorCLIIntegration

cursor = CursorCLIIntegration(
    workspace="/project",
    force=True
)

# Create tool
tool = cursor.as_tool()

# Use with agent
agent = Agent(
    name="Code Assistant",
    role="Software Developer",
    goal="Help with coding tasks",
    tools=[tool]
)

result = agent.start("Add error handling to all functions")

Environment Variables

# API Key (required for headless mode)
export CURSOR_API_KEY=your-key

CLI Flags Used

The integration uses the following Cursor CLI flags:
FlagDescription
-pPrint mode (headless)
--forceAllow file modifications
-mModel selection
--output-format jsonJSON output for parsing
--stream-partial-outputStream partial results
--resumeResume a previous session

Output Formats

JSON Output

{
  "result": "Task completed successfully",
  "files_modified": ["src/main.py", "src/utils.py"],
  "summary": "Refactored 3 functions"
}

Stream JSON Output

{"type": "start", "session_id": "abc123"}
{"type": "text", "content": "Analyzing..."}
{"type": "tool_use", "name": "read_file", "path": "main.py"}
{"type": "text", "content": "Found issues..."}
{"type": "result", "content": "Completed"}

Error Handling

from praisonai.integrations import CursorCLIIntegration

cursor = CursorCLIIntegration(timeout=120)

try:
    result = await cursor.execute("Complex task")
except TimeoutError:
    print("Task timed out")
except Exception as e:
    print(f"Error: {e}")

Authentication

Cursor CLI supports two authentication methods:
# Log in using browser flow
cursor-agent login

# Check authentication status
cursor-agent status

# Log out
cursor-agent logout

API Key

export CURSOR_API_KEY=your-key

Best Practices

  1. Use force=True only when file modifications are needed
  2. Set appropriate model based on task complexity
  3. Use session resume for multi-step tasks
  4. Enable streaming for long-running tasks
  5. Set timeouts appropriate for task complexity
  6. Use JSON output for programmatic processing