Cursor IDE Agent

# Install
curl https://cursor.com/install -fsS | bash
Login
agent login
Verify
agent --version

Modes

| Mode | Flag | Use Case | |------|------|----------| | Agent | (default) | Full coding — reads, writes, runs commands | | Plan | --plan or --mode=plan | Design approach first, then choose local or cloud execution | | Ask | --mode=ask | Read-only codebase exploration, no edits |

Interactive Mode

# Start interactive session
agent
Start with prompt
agent "refactor the auth module to use JWT tokens"
Start in plan mode
agent --plan "design a caching layer for the API"
Start in ask mode
agent --mode=ask "explain how the auth middleware works"

Non-Interactive Mode (Automation)

# One-shot task (prints result, exits)
agent -p "find and fix all unused imports in src/"
With specific model
agent -p "review this code for security issues" --model gpt-5.2
JSON output for parsing
agent -p "list all TODO comments" --output-format json
Streaming JSON (real-time)
agent -p "run tests and report" --output-format stream-json --stream-partial-output
Force mode (auto-apply changes, no confirmation)
agent -p "fix all linting errors" --force

Cloud Agent Handoff

Push work to Cursor's cloud to continue running while you're away:

# Start directly in cloud
agent -c "refactor the auth module and add comprehensive tests"
Mid-conversation: prepend & to send to cloud
& refactor the auth module and add comprehensive tests

Pick up at cursor.com/agents.

Session Management

agent ls              # List previous conversations
agent resume          # Resume most recent
agent --continue      # Continue previous session
agent --resume="id"   # Resume specific conversation

Slash Commands (Interactive)

| Command | Action | |---------|--------| | /plan | Switch to Plan mode / view current plan | | /ask | Switch to Ask mode | | /models | Switch AI model | | /compress | Summarize conversation, free context | | /rules | Create/edit rules | | /commands | Create/edit custom commands | | /mcp enable | Enable MCP server | | /mcp disable | Disable MCP server | | /sandbox | Configure sandbox mode | | /max-mode [on\|off] | Toggle Max Mode | | /resume | Resume previous conversation |

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Shift+Tab | Rotate modes (Agent → Plan → Ask) | | Shift+Enter | Insert newline (multi-line prompt) | | Ctrl+R | Review changes (i for instructions, arrows to navigate) | | Ctrl+D | Exit (double-press for safety) | | ArrowUp | Cycle previous messages |

Context & Rules

The CLI automatically loads:

Use @filename or @directory/ in interactive mode to include context.

⚠️ Using CLI from OpenClaw (PTY Required)

Cursor CLI is an interactive TUI — it needs a real terminal. Use pty:true:

# ✅ Correct — with PTY
exec pty:true command:"agent -p 'Your task'" workdir:/path/to/project
✅ Background for longer tasks
exec pty:true background:true command:"agent -p 'Build REST API'" workdir:/path/to/project
❌ Wrong — will hang
exec command:"agent -p 'Your task'"

For long tasks, use background + poll:

# Start
exec pty:true background:true workdir:~/project command:"agent -p 'Add comprehensive tests for the auth module' --force"
Check progress
process action:log sessionId:XXX
Check if done
process action:poll sessionId:XXX

Sandbox Controls

# Start with sandbox enabled
agent --sandbox enabled
Start with sandbox disabled
agent --sandbox disabled
Configure interactively
/sandbox

Sandbox supports granular network access controls — define which domains the agent can reach.