cursor-agent-cli

Cursor CLI Integration Skill

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

What is Cursor CLI?

Cursor provides two CLI tools:

1. cursor - Editor launcher (like code for VS Code) 2. 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

❌ Don't

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:

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 | | & | Send to Cloud Agent |

Resources

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: 1. Analyze current auth code 2. Propose refactoring plan 3. Show file changes 4. Ask for approval 5. 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!

Example 1: Interactive Refactoring

$ agent "refactor the user authentication system"

Agent will: 1. Analyze current auth code 2. Propose refactoring plan 3. Show file changes 4. Ask for approval 5. 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 reads from:

✅ Do

❌ Don't