Cursor CLI Agent

A comprehensive skill for using the Cursor CLI agent for various software engineering tasks (updated for 2026 features, includes tmux automation guide).

Security Scan

The skill's documentation largely matches its stated purpose, but the run instructions include automation patterns (automatically accepting 'workspace trust' and using --force to auto-apply changes) and recommend piping a remote install script to bash — together these raise practical safety concerns that users should understand before installing or automating.

Purpose & Capability

Name, description, and SKILL.md content are consistent: this is an instruction-only skill for using the Cursor CLI (installation, interactive/non-interactive usage, tmux automation, MCP/rules). The required/declared metadata requests no unrelated credentials or system access.

Instruction Scope

The instructions include step-by-step tmux automation that sends keystrokes (tmux send-keys) to accept prompts (e.g., sending "a" to trust a workspace) and recommends using --force to auto-apply changes. These actions effectively automate interactive confirmations and can enable unattended code changes or acceptance of security prompts — behavior that goes beyond passive guidance and could be abused if run on sensitive projects or by untrusted automation.

Install Mechanism

Although there's no formal install spec in the registry, SKILL.md recommends running a remote install script via curl https://cursor.com/install -fsS | bash. Piping a remote script to the shell is common but high-risk because it executes fetched code without a local review. A Homebrew option is provided (safer), but the curl|bash recommendation should be treated with caution and the installer reviewed before execution.

Credentials

The skill declares no required environment variables or credentials. The README/SKILL.md mention an optional CURSOR_API_KEY or browser login for the Cursor CLI — this is proportional and expected for a CLI that can authenticate to a service. No unrelated secrets are requested.

Persistence & Privilege

The skill does not request always: true and contains no install-time hooks in the registry metadata. However, the documentation explicitly shows how to automate the CLI (tmux automation, --force), which increases risk if the agent invoking this skill is allowed autonomous operation. Consider limiting autonomous invocation or restricting the environments where automation runs.

What to consider before installing

This skill appears to be a legitimate Cursor CLI guide, but pay attention to three risky patterns before using it: - Review the installer before running it: the SKILL.md recommends curl https://cursor.com/install | bash. Avoid piping remote scripts straight to your shell unless you inspect the script first; prefer package-manager installs (Homebrew) or verified releases. - Be cautious with automation that accepts prompts: the tmux examples send keystrokes to automatically 'trust' a workspace and recommend --force to auto-apply changes. That bypasses interactive confirmation and can cause unattended modifications or acceptance of insecure prompts. Do not run these automation steps in sensitive repos or on machines you don't fully control. - Limit exposure when integrating with agents: if you enable autonomous agent invocation or run these flows in CI, ensure the environment is isolated, the API key (if used) is scoped and rotated, and a human reviews any auto-applied changes. If you plan to use this skill: inspect the installer URL contents, remove or modify the auto-trust / auto-apply steps to require manual confirmation, test in a disposable repo/VM first, and avoid exposing high-privilege secrets to the environment where you run automated Cursor sessions.

Cursor CLI Agent Skill

This skill provides a comprehensive guide and set of workflows for utilizing the Cursor CLI tool, including all features from the January 2026 update.

Installation

Standard Installation (macOS, Linux, Windows WSL)

curl https://cursor.com/install -fsS | bash

Homebrew (macOS only)

brew install --cask cursor-cli

Post-Installation Setup

macOS:

• Add to PATH in ~/.zshrc (zsh) or ~/.bashrc (bash):

  export PATH="$HOME/.local/bin:$PATH"
  

• Restart terminal or run source ~/.zshrc (or ~/.bashrc)
• Requires macOS 10.15 or later
• Works on both Intel and Apple Silicon Macs

Linux/Ubuntu:

• Restart your terminal or source your shell config
• Verify with agent --version

Both platforms:

• Commands: agent (primary) and cursor-agent (backward compatible)
• Verify installation: agent --version or cursor-agent --version

Authentication

Authenticate via browser:

agent login

Or use API key:

export CURSOR_API_KEY=your_api_key_here

Update

Keep your CLI up to date:

agent update
# or
agent upgrade

Commands

Interactive Mode

Start an interactive session with the agent:

agent

Start with an initial prompt:

agent "Add error handling to this API"

Backward compatibility: cursor-agent still works but agent is now the primary command.

Model Switching

List all available models:

agent models
# or
agent --list-models

Use a specific model:

agent --model gpt-5

Switch models during a session:

/models

Session Management

Manage your agent sessions:

• List sessions: agent ls
• Resume most recent: agent resume
• Resume specific session: agent --resume="[chat-id]"

Context Selection

Include specific files or folders in the conversation:

@filename.ts
@src/components/

Slash Commands

Available during interactive sessions:

• /models - Switch between AI models interactively
• /compress - Summarize conversation and free up context window
• /rules - Create and edit rules directly from CLI
• /commands - Create and modify custom commands
• /mcp enable [server-name] - Enable an MCP server
• /mcp disable [server-name] - Disable an MCP server

Keyboard Shortcuts

• Shift+Enter - Add newlines for multi-line prompts
• Ctrl+D - Exit CLI (requires double-press for safety)
• Ctrl+R - Review changes (press i for instructions, navigate with arrow keys)
• ArrowUp - Cycle through previous messages

Non-interactive / CI Mode

Run the agent in a non-interactive mode, suitable for CI/CD pipelines:

agent -p 'Run tests and report coverage'
# or
agent --print 'Refactor this file to use async/await'

Output formats:

# Plain text (default)
agent -p 'Analyze code' --output-format text

# Structured JSON
agent -p 'Find bugs' --output-format json

# Real-time streaming JSON
agent -p 'Run tests' --output-format stream-json --stream-partial-output

Force mode (auto-apply changes without confirmation):

agent -p 'Fix all linting errors' --force

Media support:

agent -p 'Analyze this screenshot: screenshot.png'

⚠️ Using with AI Agents / Automation (tmux required)

CRITICAL: When running Cursor CLI from automated environments (AI agents, scripts, subprocess calls), the CLI requires a real TTY. Direct execution will hang indefinitely.

The Solution: Use tmux

# 1. Install tmux if not available
sudo apt install tmux  # Ubuntu/Debian
brew install tmux      # macOS

# 2. Create a tmux session
tmux kill-session -t cursor 2>/dev/null || true
tmux new-session -d -s cursor

# 3. Navigate to project
tmux send-keys -t cursor "cd /path/to/project" Enter
sleep 1

# 4. Run Cursor agent
tmux send-keys -t cursor "agent 'Your task here'" Enter

# 5. Handle workspace trust prompt (first run)
sleep 3
tmux send-keys -t cursor "a"  # Trust workspace

# 6. Wait for completion
sleep 60  # Adjust based on task complexity

# 7. Capture output
tmux capture-pane -t cursor -p -S -100

# 8. Verify results
ls -la /path/to/project/

Why this works:

• tmux provides a persistent pseudo-terminal (PTY)
• Cursor's TUI requires interactive terminal capabilities
• Direct agent calls from subprocess/exec hang without TTY

What does NOT work:

# ❌ These will hang indefinitely:
agent "task"                    # No TTY
agent -p "task"                 # No TTY  
subprocess.run(["agent", ...])  # No TTY
script -c "agent ..." /dev/null # May crash Cursor

Rules & Configuration

The agent automatically loads rules from:

• .cursor/rules
• AGENTS.md
• CLAUDE.md

Use /rules command to create and edit rules directly from the CLI.

MCP Integration

MCP servers are automatically loaded from mcp.json configuration.

Enable/disable servers on the fly:

/mcp enable server-name
/mcp disable server-name

Note: Server names with spaces are fully supported.

Workflows

Code Review

Perform a code review on the current changes or a specific branch:

agent -p 'Review the changes in the current branch against main. Focus on security and performance.'

Refactoring

Refactor code for better readability or performance:

agent -p 'Refactor src/utils.ts to reduce complexity and improve type safety.'

Debugging

Analyze logs or error messages to find the root cause:

agent -p 'Analyze the following error log and suggest a fix: [paste log here]'

Git Integration

Automate git operations with context awareness:

agent -p 'Generate a commit message for the staged changes adhering to conventional commits.'

Batch Processing (CI/CD)

Run automated checks in CI pipelines:

# Set API key in CI environment
export CURSOR_API_KEY=$CURSOR_API_KEY

# Run security audit with JSON output
agent -p 'Audit this codebase for security vulnerabilities' --output-format json --force

# Generate test coverage report
agent -p 'Run tests and generate coverage report' --output-format text

Multi-file Analysis

Use context selection to analyze multiple files:

agent
# Then in interactive mode:
@src/api/
@src/models/
Review the API implementation for consistency with our data models