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.

What This Skill Does

The cursor-agent skill empowers developers to leverage the Cursor CLI for a wide range of software engineering tasks directly from their terminal. It facilitates code generation, refactoring, debugging, testing, and more, with advanced features like model switching, session management, and context selection. The skill also includes guidance on integrating with tmux for enhanced productivity and provides a streamlined experience for both interactive and non-interactive (CI/CD) environments.

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"

Model Switching

List all available models:

agent models
# or
agent --list-models

Use a specific model:

agent --model gpt-5

Session Management

• 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

Keyboard Shortcuts

• Shift+Enter - Add newlines for multi-line prompts
• Ctrl+D - Exit CLI (requires double-press for safety)
• Ctrl+R - Review changes
• 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'

Use Cases

• Code Generation: "Create a React component for a user profile card."
• Code Refactoring: "Refactor the getUserData function to use async/await and add proper error handling."
• Debugging: "Analyze the logs and identify the cause of the NullPointerException in OrderService."
• Test Writing: "Write unit tests for the PaymentProcessor class, covering success and failure scenarios."
• Documentation: "Generate a README.md file for this project, explaining the installation and usage."

Example Prompts

1. "Generate a Python script that scrapes data from example.com/products and saves it to a CSV file. Include error handling for network issues and missing elements."
2. "Review the current implementation of the authentication module and suggest improvements for security and performance. Focus on OWASP Top 10 vulnerabilities."
3. "Write a bash script to automate the deployment process for my Node.js application. It should include steps for building, testing, and deploying to a staging server, and also handle rollbacks."

Tips & Limitations

• Tmux Integration: For an enhanced terminal experience, consider integrating agent with tmux. You can create custom tmux layouts to dedicate panes for agent interactions, code editing, and terminal commands simultaneously. This allows for a fluid workflow where you can ask the agent questions, review its suggestions, and implement changes without leaving your tmux session.
• Context is Key: The quality of the agent's output is highly dependent on the context provided. Use context selection (@file or @folder) effectively to guide the agent.
• Iterative Refinement: Complex tasks may require multiple prompts and iterative refinement. Don't expect perfect results on the first try; use the interactive mode to guide the agent.
• Model Choice: Experiment with different models (agent --model) to find the one that best suits your task and budget.
• CI/CD: The non-interactive mode is powerful for automating tasks in CI/CD pipelines, but ensure your prompts are precise and unambiguous.
• Rate Limits & Costs: Be mindful of potential API rate limits and costs associated with different AI models.
• Review Changes: Always use Ctrl+R to review code changes before committing.