Cursor CLI Agent

Cursor Agent Skill

Execute coding tasks using Cursor CLI (agent command). Supports multiple frontier models (GPT-5, Claude Opus/Sonnet, Gemini, Grok, etc.).

⚠️ PTY Mode Required!

Cursor Agent is an interactive terminal application that requires PTY to work correctly.

# ✅ Correct
bash pty:true command:"agent 'Your prompt'"
❌ Wrong - will hang without PTY
bash command:"agent 'Your prompt'"

Bash Tool Parameters

| Parameter | Type | Description | | ------------ | ------- | ----------------------------------------------------- | | command | string | Shell command to execute | | pty | boolean | Required! Allocates pseudo-terminal for interactive CLIs | | workdir | string | Working directory (agent only sees this folder's context) | | background | boolean | Run in background, returns sessionId for monitoring | | timeout | number | Timeout in seconds (kills process on expiry) | | elevated | boolean | Run on host instead of sandbox (if allowed) |

Quick Start

# Check status and login
agent status
agent login
List available models
agent --list-models
Quick task (interactive mode)
bash pty:true command:"agent 'Add error handling to the API calls'"
Specify working directory
bash pty:true workdir:~/Projects/myproject command:"agent 'Build a snake game'"

The Pattern: workdir + background + pty

For longer tasks, use background mode:

# Start background task
bash pty:true workdir:~/project background:true command:"agent --yolo 'Refactor the auth module'"
Returns sessionId, monitor with process tool
process action:list
process action:log sessionId:XXX
process action:poll sessionId:XXX
Send input
process action:submit sessionId:XXX data:"yes"
Terminate
process action:kill sessionId:XXX

Why workdir matters: Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).

Command Flags Reference

| Flag | Description | |------|-------------| | prompt | Initial prompt for the agent | | --yolo / --force | Auto-approve all operations (dangerous but fast) | | --model | Specify model (gpt-5, sonnet-4, opus-4, gemini, grok, etc.) | | --workspace | Working directory | | -w, --worktree [name] | Run in isolated git worktree | | --print | Non-interactive mode, output to console | | --mode | Execution mode: plan (read-only planning), ask (Q&A) | | --plan | Plan mode (read-only, no file modifications) | | --cloud | Cloud mode | | --resume | Resume previous session | | --trust | Trust workspace (headless mode only) |

Execution Modes

Interactive Mode (default)

bash pty:true workdir:~/project command:"agent 'Build a dark mode toggle'"

Auto-Execute Mode (--yolo)

# Auto-approve all operations, fast execution
bash pty:true workdir:~/project command:"agent --yolo 'Refactor the auth module'"

Plan Mode (--plan)

# Read-only mode, generate plan without executing
bash pty:true workdir:~/project command:"agent --plan 'Analyze the codebase structure'"

Ask Mode (--mode ask)

# Q&A only, no file modifications
bash pty:true command:"agent --mode ask 'Explain how the auth flow works'"

Non-Interactive Mode (--print) ⭐ Unique Feature

Cursor's unique --print mode, ideal for scripting and CI/CD:

# Non-interactive execution, output to console
bash pty:true command:"agent --print 'Generate a summary of the codebase'"
JSON output (ideal for parsing)
bash pty:true command:"agent --print --output-format json 'List all API endpoints'"
Streaming JSON (real-time processing)
bash pty:true command:"agent --print --output-format stream-json 'Analyze the project'"

Use cases:

Git Worktree Isolation

For parallel processing of multiple independent tasks:

# Run in isolated worktree
bash pty:true workdir:~/project command:"agent -w fix-issue-78 'Fix the login bug'"
Specify base branch
bash pty:true workdir:~/project command:"agent -w feature-x --worktree-base develop 'Add feature X'"

Parallel Issue Fixing

Use git worktrees to fix multiple issues simultaneously:

# 1. Create worktrees for each issue
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main
2. Launch agent in each worktree (background + PTY)
bash pty:true workdir:/tmp/issue-78 background:true command:"agent --yolo 'Fix issue #78: login bug. Commit and push.'"
bash pty:true workdir:/tmp/issue-99 background:true command:"agent --yolo 'Fix issue #99: API timeout. Commit and push.'"
3. Monitor progress
process action:list
process action:log sessionId:XXX
4. Create PRs
cd /tmp/issue-78 && git push -u origin fix/issue-78
gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."
5. Cleanup
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99

Batch PR Reviews

⚠️ NEVER review PRs in OpenClaw's own project directory!

# Clone to temp directory
REVIEW_DIR=$(mktemp -d)
git clone https://github.com/user/repo.git $REVIEW_DIR
cd $REVIEW_DIR && gh pr checkout 130
Review in plan mode (read-only)
bash pty:true workdir:$REVIEW_DIR command:"agent --plan 'Review this PR for security issues and code quality'"
Cleanup
trash $REVIEW_DIR

Batch Review Multiple PRs

# Fetch all PR refs
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'
Launch multiple agents in parallel
bash pty:true workdir:~/project background:true command:"agent --plan 'Review PR #86. git diff origin/main...origin/pr/86'"
bash pty:true workdir:~/project background:true command:"agent --plan 'Review PR #87. git diff origin/main...origin/pr/87'"
Monitor
process action:list
Post results to GitHub
gh pr comment 86 --body ""

Process Tool (Background Task Management)

| Action | Description | |--------|-------------| | list | List all running sessions | | poll | Check if session is still running | | log | Get session output (supports offset/limit) | | write | Send raw data to stdin | | submit | Send data + newline (simulate Enter) | | send-keys | Send key presses | | paste | Paste text | | kill | Terminate session |

Model Selection

# List available models
agent --list-models
Specify model
bash pty:true command:"agent --model opus-4 'Complex refactoring task'"
bash pty:true command:"agent --model gpt-5 'Build a CLI tool'"
bash pty:true command:"agent --model gemini 'Analyze this Python codebase'"

Auto-Notify on Completion

For long-running tasks, append a wake trigger to your prompt:

bash pty:true workdir:~/project background:true command:"agent --yolo 'Build a REST API for todos.
When completely finished, run: openclaw system event --text \"Done: Built todos REST API\" --mode now'"

This triggers immediate notification instead of waiting for heartbeat.

Authentication

# Check login status
agent status
Login
agent login
Logout
agent logout
View account info
agent about

⚠️ Rules

1. Always use pty:true - Will hang without PTY 2. Use background for long tasks - Don't block main thread 3. --yolo for building - Auto-approve changes 4. --plan for reviewing - Read-only analysis 5. --print for scripting - Non-interactive, parseable output 6. Use -w worktree for isolation - Parallel task processing 7. NEVER start in ~/.openclaw/ - It'll read your soul docs! 8. Notify user on completion - Don't leave user guessing

Progress Updates

When spawning background agents:

Learnings

# Check status and login
agent status
agent login
List available models
agent --list-models
Quick task (interactive mode)
bash pty:true command:"agent 'Add error handling to the API calls'"
Specify working directory
bash pty:true workdir:~/Projects/myproject command:"agent 'Build a snake game'"