Cursor CLI Skill
Usage
Ask a question (auto model selection)
node .claude/skills/omega-cursor-cli/scripts/ask-cursor.mjs "How should I structure this React component?" --yolo --trust
Specific model
node .claude/skills/omega-cursor-cli/scripts/ask-cursor.mjs "Review this API design" --model claude-4.6-opus --yolo --trust
With timeout
node .claude/skills/omega-cursor-cli/scripts/ask-cursor.mjs "Refactor authentication" --yolo --trust --timeout-ms 180000
JSON output
node .claude/skills/omega-cursor-cli/scripts/ask-cursor.mjs "Generate types" --json --yolo --trust
Availability Check
node .claude/skills/omega-cursor-cli/scripts/verify-setup.mjs
# Exit 0 = available (CLI found)
# Exit 1 = not available
When to Use
- Multi-model perspective via Cursor's auto routing
- IDE-aware code generation (Cursor has workspace context)
- When a non-Claude, non-OpenAI perspective is desired
- Tasks where Cursor's composer models excel
Iron Laws
- ALWAYS use --yolo --trust for headless mode (otherwise blocks on approval prompts)
- NEVER assume CLI is available -- most restrictive subscription requirement
- ALWAYS include --timeout-ms for production usage
- NEVER attempt to detect subscription status programmatically (not possible)
- ALWAYS handle WSL issues on Windows (some configurations require WSL)
Anti-Patterns
| Anti-Pattern | Why Bad | Correct Approach |
|---|
| Running without --yolo | Blocks on tool approval prompts | Always pass --yolo |
| Running without --trust | Blocks on workspace trust prompt | Always pass --trust |
| Assuming auto model is available | Depends on subscription tier | Check with cursor-agent --list-models |
| Hardcoding cursor-agent path | PATH differs across OS/install methods | Wrapper handles resolution |
| Ignoring WSL requirements | Some Windows installs are WSL-only | Document in setup instructions |
Scripts
| Script | Purpose |
|---|
ask-cursor.mjs | Core headless wrapper -- prompt as last positional arg |
parse-args.mjs | Argument parser (--model, --json, --yolo, --trust, --timeout-ms) |
verify-setup.mjs | Availability check (multi-path resolution) |
format-output.mjs | Output normalization |
Exit Codes
| Code | Meaning |
|---|
| 0 | Success |
| 1 | Error (CLI failure, subscription issue) |
| 124 | Timeout (--timeout-ms exceeded) |
Integration Notes
- Subscription: Cursor Pro or Business required for agent/headless mode
- Stdin limit:
ASK_CURSOR_MAX_STDIN_BYTES env var (default 50MB) - Available models: claude-4.6-opus, claude-4.6-sonnet, composer-1.5, gemini-3.1-pro, gpt-5.3-codex, auto
- Platform: Partial cross-platform (WSL issues on some Windows configurations)
- PATH resolution order: agent -> cursor-agent -> %LOCALAPPDATA%\cursor-agent\cursor-agent.cmd -> npx @cursor/agent
Memory Protocol
Before work: Read .claude/context/memory/learnings.md After work: Append findings to learnings or issues as needed.
*Note: Use pnpm search:code to discover references to this skill codebase-wide.*
