{"skill":{"slug":"cursor-agent","displayName":"Cursor CLI Agent","summary":"A comprehensive skill for using the Cursor CLI agent for various software engineering tasks (updated for 2026 features, includes tmux automation guide).","description":"---\nname: cursor-agent\nversion: 2.1.0\ndescription: A comprehensive skill for using the Cursor CLI agent for various software engineering tasks (updated for 2026 features, includes tmux automation guide).\nauthor: Pushpinder Pal Singh\n---\n\n# Cursor CLI Agent Skill\n\nThis skill provides a comprehensive guide and set of workflows for utilizing the Cursor CLI tool, including all features from the January 2026 update.\n\n## Installation\n\n### Standard Installation (macOS, Linux, Windows WSL)\n\n```bash\ncurl https://cursor.com/install -fsS | bash\n```\n\n### Homebrew (macOS only)\n\n```bash\nbrew install --cask cursor-cli\n```\n\n### Post-Installation Setup\n\n**macOS:**\n- Add to PATH in `~/.zshrc` (zsh) or `~/.bashrc` (bash):\n  ```bash\n  export PATH=\"$HOME/.local/bin:$PATH\"\n  ```\n- Restart terminal or run `source ~/.zshrc` (or `~/.bashrc`)\n- Requires macOS 10.15 or later\n- Works on both Intel and Apple Silicon Macs\n\n**Linux/Ubuntu:**\n- Restart your terminal or source your shell config\n- Verify with `agent --version`\n\n**Both platforms:**\n- Commands: `agent` (primary) and `cursor-agent` (backward compatible)\n- Verify installation: `agent --version` or `cursor-agent --version`\n\n## Authentication\n\nAuthenticate via browser:\n\n```bash\nagent login\n```\n\nOr use API key:\n\n```bash\nexport CURSOR_API_KEY=your_api_key_here\n```\n\n## Update\n\nKeep your CLI up to date:\n\n```bash\nagent update\n# or\nagent upgrade\n```\n\n## Commands\n\n### Interactive Mode\n\nStart an interactive session with the agent:\n\n```bash\nagent\n```\n\nStart with an initial prompt:\n\n```bash\nagent \"Add error handling to this API\"\n```\n\n**Backward compatibility:** `cursor-agent` still works but `agent` is now the primary command.\n\n### Model Switching\n\nList all available models:\n\n```bash\nagent models\n# or\nagent --list-models\n```\n\nUse a specific model:\n\n```bash\nagent --model gpt-5\n```\n\nSwitch models during a session:\n\n```\n/models\n```\n\n### Session Management\n\nManage your agent sessions:\n\n- **List sessions:** `agent ls`\n- **Resume most recent:** `agent resume`\n- **Resume specific session:** `agent --resume=\"[chat-id]\"`\n\n### Context Selection\n\nInclude specific files or folders in the conversation:\n\n```\n@filename.ts\n@src/components/\n```\n\n### Slash Commands\n\nAvailable during interactive sessions:\n\n- **`/models`** - Switch between AI models interactively\n- **`/compress`** - Summarize conversation and free up context window\n- **`/rules`** - Create and edit rules directly from CLI\n- **`/commands`** - Create and modify custom commands\n- **`/mcp enable [server-name]`** - Enable an MCP server\n- **`/mcp disable [server-name]`** - Disable an MCP server\n\n### Keyboard Shortcuts\n\n- **`Shift+Enter`** - Add newlines for multi-line prompts\n- **`Ctrl+D`** - Exit CLI (requires double-press for safety)\n- **`Ctrl+R`** - Review changes (press `i` for instructions, navigate with arrow keys)\n- **`ArrowUp`** - Cycle through previous messages\n\n### Non-interactive / CI Mode\n\nRun the agent in a non-interactive mode, suitable for CI/CD pipelines:\n\n```bash\nagent -p 'Run tests and report coverage'\n# or\nagent --print 'Refactor this file to use async/await'\n```\n\n**Output formats:**\n\n```bash\n# Plain text (default)\nagent -p 'Analyze code' --output-format text\n\n# Structured JSON\nagent -p 'Find bugs' --output-format json\n\n# Real-time streaming JSON\nagent -p 'Run tests' --output-format stream-json --stream-partial-output\n```\n\n**Force mode (auto-apply changes without confirmation):**\n\n```bash\nagent -p 'Fix all linting errors' --force\n```\n\n**Media support:**\n\n```bash\nagent -p 'Analyze this screenshot: screenshot.png'\n```\n\n### ⚠️ Using with AI Agents / Automation (tmux required)\n\n**CRITICAL:** When running Cursor CLI from automated environments (AI agents, scripts, subprocess calls), the CLI requires a real TTY. Direct execution will hang indefinitely.\n\n**The Solution: Use tmux**\n\n```bash\n# 1. Install tmux if not available\nsudo apt install tmux  # Ubuntu/Debian\nbrew install tmux      # macOS\n\n# 2. Create a tmux session\ntmux kill-session -t cursor 2>/dev/null || true\ntmux new-session -d -s cursor\n\n# 3. Navigate to project\ntmux send-keys -t cursor \"cd /path/to/project\" Enter\nsleep 1\n\n# 4. Run Cursor agent\ntmux send-keys -t cursor \"agent 'Your task here'\" Enter\n\n# 5. Handle workspace trust prompt (first run)\nsleep 3\ntmux send-keys -t cursor \"a\"  # Trust workspace\n\n# 6. Wait for completion\nsleep 60  # Adjust based on task complexity\n\n# 7. Capture output\ntmux capture-pane -t cursor -p -S -100\n\n# 8. Verify results\nls -la /path/to/project/\n```\n\n**Why this works:**\n- tmux provides a persistent pseudo-terminal (PTY)\n- Cursor's TUI requires interactive terminal capabilities\n- Direct `agent` calls from subprocess/exec hang without TTY\n\n**What does NOT work:**\n```bash\n# ❌ These will hang indefinitely:\nagent \"task\"                    # No TTY\nagent -p \"task\"                 # No TTY  \nsubprocess.run([\"agent\", ...])  # No TTY\nscript -c \"agent ...\" /dev/null # May crash Cursor\n```\n\n## Rules & Configuration\n\nThe agent automatically loads rules from:\n- `.cursor/rules`\n- `AGENTS.md`\n- `CLAUDE.md`\n\nUse `/rules` command to create and edit rules directly from the CLI.\n\n## MCP Integration\n\nMCP servers are automatically loaded from `mcp.json` configuration.\n\nEnable/disable servers on the fly:\n\n```\n/mcp enable server-name\n/mcp disable server-name\n```\n\n**Note:** Server names with spaces are fully supported.\n\n## Workflows\n\n### Code Review\n\nPerform a code review on the current changes or a specific branch:\n\n```bash\nagent -p 'Review the changes in the current branch against main. Focus on security and performance.'\n```\n\n### Refactoring\n\nRefactor code for better readability or performance:\n\n```bash\nagent -p 'Refactor src/utils.ts to reduce complexity and improve type safety.'\n```\n\n### Debugging\n\nAnalyze logs or error messages to find the root cause:\n\n```bash\nagent -p 'Analyze the following error log and suggest a fix: [paste log here]'\n```\n\n### Git Integration\n\nAutomate git operations with context awareness:\n\n```bash\nagent -p 'Generate a commit message for the staged changes adhering to conventional commits.'\n```\n\n### Batch Processing (CI/CD)\n\nRun automated checks in CI pipelines:\n\n```bash\n# Set API key in CI environment\nexport CURSOR_API_KEY=$CURSOR_API_KEY\n\n# Run security audit with JSON output\nagent -p 'Audit this codebase for security vulnerabilities' --output-format json --force\n\n# Generate test coverage report\nagent -p 'Run tests and generate coverage report' --output-format text\n```\n\n### Multi-file Analysis\n\nUse context selection to analyze multiple files:\n\n```bash\nagent\n# Then in interactive mode:\n@src/api/\n@src/models/\nReview the API implementation for consistency with our data models\n```\n","tags":{"latest":"2.1.0"},"stats":{"comments":0,"downloads":11777,"installsAllTime":94,"installsCurrent":94,"stars":17,"versions":2},"createdAt":1768337198656,"updatedAt":1779147011553},"latestVersion":{"version":"2.1.0","createdAt":1768339191701,"changelog":"Add tmux automation guide for AI agents - Cursor CLI requires real TTY for automated execution","license":null},"metadata":null,"owner":{"handle":"swiftlysingh","userId":"s172v8dwtevweqy5xqnkq7yfyd884py9","displayName":"swiftlysingh","image":"https://avatars.githubusercontent.com/u/47032662?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779913397161}}