cursor-agent-cli

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.

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

bash

# 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

bash

# 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)

bash

# 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

text

/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:

bash

# 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

bash

# 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)

bash

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

Sandbox Control

bash

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

# Interactive sandbox menu
/sandbox

Workspace & Worktree

bash

# 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

bash

# 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

bash

# 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

bash

# Login
agent login

# Check status
agent status
agent whoami

# Logout
agent logout

Session Management

bash

# Create new empty chat
agent create-chat

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

# Resume latest
agent resume
agent --continue

Cursor Rules Generation

bash

# Interactive rule generation
agent generate-rule
agent rule

MCP (Model Context Protocol) Management

bash

# Manage MCP servers
agent mcp

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

Shell Integration

bash

# Install shell integration
agent install-shell-integration

# Uninstall
agent uninstall-shell-integration

Use Cases

1. Code Refactoring

bash

agent "refactor the authentication module to use modern patterns"

2. Bug Fixing

bash

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

3. Feature Development

bash

agent "implement user profile editing with validation"

4. Code Review

bash

# 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

bash

agent "add comprehensive JSDoc comments to all functions"

6. Testing

bash

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

7. Performance Optimization

bash

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

8. Migration

bash

agent "migrate from Express to Fastify maintaining all functionality"

CI/CD Integration

bash

#!/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

javascript

// 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:

javascript

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

Troubleshooting

Check version

bash

agent --version

Update to latest

bash

agent update

View system info

bash

agent about

Authentication issues

bash

# Re-authenticate
agent logout
agent login

Workspace trust

If prompted about workspace trust in headless mode:

bash

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

bash

$ 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

bash

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

Non-interactive, auto-approved test generation.

Example 3: Code Review in CI

yaml

# .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

bash

$ 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!