> ## Documentation Index > Fetch the complete documentation index at: https://docs.praison.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Install via npm npm install -g cursor-agent # Or via pipx pipx install cursor-agent ``` ## Authentication Login with your Cursor account: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} cursor-agent login ``` Or set API key: ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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. ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 ` | API key (or use `CURSOR_API_KEY` env var) | | `-H, --header
` | Add custom header (format: `Name: Value`) | ### Output Options | Option | Description | Default | | -------------------------- | ----------------------------------------------- | ------- | | `-p, --print` | Print responses to console (non-interactive) | `false` | | `--output-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 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 ` | 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 ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Allow all commands (use with caution) cursor-agent -p -f "Refactor and run tests" ``` ### Model Selection ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Enable browser support cursor-agent -p --browser "Test the login flow in the browser" ``` ### Session Management ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # Start in cloud mode cursor-agent -c ``` ## Python Integration ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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) ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} cursor-agent -p --output-format text "Say hello" # Output: Hello! How can I help you today? ``` ### JSON Format ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} cursor-agent -p --output-format json "Say hello" ``` ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "result": "Hello! How can I help you today?", "chatId": "abc123", "model": "gpt-5" } ``` ### Stream JSON Format ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} cursor-agent -p --output-format stream-json "Analyze code" ``` Real-time JSON events for each step: ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} {"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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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 theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} # 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](/docs/cli/cli) * [Claude CLI](/docs/cli/claude-cli) * [Gemini CLI](/docs/cli/gemini-cli) * [Codex CLI](/docs/cli/codex-cli)