name: cursor-agent-cli description: Cursor Agent CLI integration - AI-powered coding agent for terminal. Use when user mentions Cursor Agent, agent CLI, AI coding, code generation, refactoring, or interactive programming sessions. metadata: openclaw: requires: bins: ["agent", "cursor"] optional: bins: ["git", "gh"] version: "1.0.0" author: "OpenClaw Community" license: "MIT" tags: ["cursor", "cursor-agent", "ai-coding", "automation", "developer-tools"]

Cursor CLI Integration Skill

🤖 Cursor Agent - AI-powered coding assistant directly in your terminal.

What is Cursor CLI?

Cursor provides two CLI tools:

cursor - Editor launcher (like code for VS Code)
agent ⭐ - Interactive AI coding assistant with full tool access

Installation

# macOS, Linux, WSL
curl https://cursor.com/install -fsS | bash

# Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex

# Verify installation
agent --version

Quick Start

Interactive Mode

# Start interactive session
agent

# Start with initial prompt
agent "refactor the auth module to use JWT tokens"

# Resume latest session
agent resume

# Continue previous session
agent --continue

# List all sessions
agent ls

Non-Interactive Mode (Scripts/CI)

# Run with specific prompt
agent -p "find and fix performance issues" --model "gpt-5.2"

# Code review
agent -p "review these changes for security issues" --output-format text

# JSON output for parsing
agent -p "analyze this codebase structure" --output-format json

Modes

Mode	Description	Usage
Agent	Full access - can modify code	Default
Plan	Read-only planning and analysis	`--plan` or `/plan`
Ask	Q&A without making changes	`--mode=ask` or `/ask`

Switch modes mid-conversation

/plan        # Switch to plan mode
/ask         # Switch to ask mode
Shift+Tab    # Toggle plan mode

Cloud Agent (Background Execution)

Run tasks in the cloud while you're away:

# Start in cloud mode
agent -c "refactor the auth module and add comprehensive tests"

# Send to cloud mid-conversation
& refactor the auth module and add comprehensive tests

Track at: cursor.com/agents

Models

# List available models
agent --list-models

# Use specific model
agent --model "gpt-5.2"
agent --model "sonnet-4"
agent --model "sonnet-4-thinking"

Advanced Options

Force Mode (Auto-approve)

# Auto-approve all commands
agent --force "build the feature"
agent --yolo "build the feature"  # Alias

Sandbox Control

# Enable/disable sandbox
agent --sandbox enabled
agent --sandbox disabled

# Interactive sandbox menu
/sandbox

Workspace & Worktree

# Specify workspace
agent --workspace /path/to/project

# Start in isolated git worktree
agent -w feature-branch
agent --worktree feature-branch --worktree-base main

Custom Headers & API Key

# Set API key
export CURSOR_API_KEY="your-key"
agent --api-key "your-key"

# Add custom headers
agent -H "X-Custom-Header: value"

Output Formats

# Text output (default)
agent -p "analyze code" --output-format text

# JSON output
agent -p "list functions" --output-format json

# Streaming JSON
agent -p "generate code" --output-format stream-json --stream-partial-output

Authentication

# Login
agent login

# Check status
agent status
agent whoami

# Logout
agent logout

Session Management

# Create new empty chat
agent create-chat

# Resume specific chat
agent --resume="chat-id-here"

# Resume latest
agent resume
agent --continue

Cursor Rules Generation

# Interactive rule generation
agent generate-rule
agent rule

MCP (Model Context Protocol) Management

# Manage MCP servers
agent mcp

# Auto-approve MCP servers
agent --approve-mcps

Shell Integration

# Install shell integration
agent install-shell-integration

# Uninstall
agent uninstall-shell-integration

Use Cases

1. Code Refactoring

agent "refactor the authentication module to use modern patterns"

2. Bug Fixing

agent -p "find and fix the memory leak in server.js"

3. Feature Development

agent "implement user profile editing with validation"

4. Code Review

# Review uncommitted changes
git diff | agent -p "review these changes for security issues"

# Review specific file
agent "review api/auth.js for security vulnerabilities"

5. Documentation

agent "add comprehensive JSDoc comments to all functions"

6. Testing

agent "generate unit tests for the auth module with 90% coverage"

7. Performance Optimization

agent "analyze and optimize database queries in user-service.js"

8. Migration

agent "migrate from Express to Fastify maintaining all functionality"

CI/CD Integration

#!/bin/bash
# .github/workflows/code-review.yml

# Automated code review on PR
agent -p "review changed files for security and performance issues" \
  --output-format json \
  --trust \
  > review-report.json

Best Practices

✅ Do

Use --plan mode first for complex changes
Review proposed changes before approving
Use --workspace to specify project directory
Save important sessions (they auto-save)
Use --force only in trusted environments

❌ Don't

Use --yolo on production code without review
Share your API key
Run in untrusted workspaces with --trust
Ignore security warnings

OpenClaw Integration

Call agent from OpenClaw

// Interactive session
exec({ command: "agent 'refactor auth module'", pty: true })

// Non-interactive
exec({ command: "agent -p 'analyze code' --output-format json" })

Use in subagents

When spawning coding agents, you can use Cursor agent as an alternative:

sessions_spawn({
  runtime: "acp",
  agentId: "cursor",  // If configured
  task: "Refactor authentication module"
})

Troubleshooting

Check version

agent --version

Update to latest

agent update

View system info

agent about

Authentication issues

# Re-authenticate
agent logout
agent login

Workspace trust

If prompted about workspace trust in headless mode:

agent --trust -p "your prompt"

Configuration

Cursor agent reads from:

~/.cursor/ - Configuration and cache
~/.cursor/worktrees/ - Git worktrees
Environment variables: CURSOR_API_KEY, NO_OPEN_BROWSER

Keyboard Shortcuts (Interactive Mode)

Shortcut	Action
`Shift+Tab`	Toggle plan mode
`/plan`	Switch to plan mode
`/ask`	Switch to ask mode
`/sandbox`	Open sandbox menu
`/max-mode on`	Enable max mode
`& <prompt>`	Send to Cloud Agent

Resources

📖 Official Docs: https://cursor.com/docs/cli/overview
🌐 Cloud Agent: https://cursor.com/agents
💬 Community: https://forum.cursor.com

Version

Current Version: 2026.02.27-e7d2ef6

Check for updates: agent update

Examples

Example 1: Interactive Refactoring

$ agent "refactor the user authentication system"

Agent will:

Analyze current auth code
Propose refactoring plan
Show file changes
Ask for approval
Execute changes

Example 2: Automated Testing

$ agent -p "generate comprehensive tests for src/api/*.js" --force

Non-interactive, auto-approved test generation.

Example 3: Code Review in CI

# .github/workflows/review.yml
- name: AI Code Review
  run: |
    agent -p "review changes for security issues" \
      --output-format json \
      --trust \
      > review.json

Example 4: Cloud Background Task

$ agent -c "implement payment gateway integration with Stripe"
# Go do other work, check back later at cursor.com/agents

Pro Tip: Use agent ls frequently to review and resume past sessions. Context is preserved across sessions!

cursor-agent-cli

Description