A comprehensive skill for using the Cursor CLI agent for various software engineering tasks (updated for 2026 features, includes tmux automation guide). Use when user wants to run Cursor agent, code with Cursor, or automate development tasks via Cursor CLI.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
A comprehensive skill for using the Cursor CLI agent for various software engineering tasks (updated for 2026 features, includes tmux automation guide). Use when user wants to run Cursor agent, code with Cursor, or automate development tasks via Cursor CLI.
author
Pushpinder Pal Singh
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'
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.
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 environmentexport 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
