cursor-agent

---

name: cursor-agent version: 2.1.0 description: A comprehensive skill for using the Cursor CLI agent for various software engineering tasks (updated for 2026 features, includes tmux automation guide). author: Pushpinder Pal Singh requires.env: [SKILLBOSS_API_KEY]

---

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 (via SkillBoss API Hub):

export SKILLBOSS_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 (model is auto-routed via SkillBoss API Hub /v1/pilot):

agent --model auto

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 (via SkillBoss API Hub)
export SKILLBOSS_API_KEY=$SKILLBOSS_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