Skill: daxingplay/cursor-cli-headless (version 1.1.0)

--- name: cursor-cli-headless description: Execute coding tasks using the Cursor CLI in headless print mode. Use when delegating code writing, refactoring, analysis, or review tasks to a headless Cursor agent process, running automated code changes, or batch-processing files with the agent CLI. --- # Cursor CLI Headless Execute coding tasks using the Cursor CLI in non-interactive (print) mode via the wrapper script for scripts, automation, and batch processing. ## Prerequisites - **Cursor CLI installed**: Run `agent --version`. If missing, install: `curl https://cursor.com/install -fsS | bash` (macOS/Linux/WSL) or see [Installation](https://cursor.com/docs/cli/installation). - **Authenticated**: Set `CURSOR_API_KEY` in the environment for scripts, or run `agent login` interactively once. Check if already logged in with `agent status` or `agent whoami`. ## Quick start Use `scripts/run-task.sh` with either an inline prompt or a prompt file: ```bash # Prompt from file (stream progress by default) ./scripts/run-task.sh -f prompt.txt # Inline prompt, run in a specific project directory ./scripts/run-task.sh -p "Add tests for auth module" -d /path/to/project ``` ## Wrapper script: run-task.sh `scripts/run-task.sh` runs the Cursor agent in headless mode. **Recommended:** keep file modifications and stream progress **on** (default). Use `--no-force` only with tmux for interactive mode (agent proposes changes for review). Use `--no-stream` for plain output. **Arguments:** - `-p "prompt"` — inline prompt (mutually exclusive with `-f`) - `-f prompt-file.txt` — read prompt from file (for long prompts) - `-d dir` — working directory (default: current directory) - `-o format` — `text`, `json`, or `stream-json` (with default streaming, format is stream-json) - `-m model` — model name - `--mode mode` — `agent`, `plan`, or `ask` - `--force` — allow file modifications (default) - `--no-force` — do not modify files; agent only proposes changes - `--stream` — stream-json with progress display (default; requires `jq` for progress) - `--no-stream` — plain output only; use with `-o text` or `-o json` **Output formats:** | Format | Use when | |--------|----------| | (default stream) | Live progress (model, tool calls, chars); NDJSON on stdout, progress on stderr | | `-o text --no-stream` | Only the final assistant message | | `-o json --no-stream` | Single JSON object with `result`, `duration_ms`, etc.; parse with `jq -r '.result'` | **Examples:** ```bash # Task from file, apply changes, stream progress (default) ./scripts/run-task.sh -f tasks/refactor-auth.txt # Inline prompt, specific project, JSON result only ./scripts/run-task.sh -p "Summarize README.md" -d /path/to/repo --no-stream -o json # Plain text output, no progress ./scripts/run-task.sh -f tasks/review.txt --no-stream -o text ``` ## Working directory The agent runs in the script’s working directory. Use `-d /path/to/project` so the agent sees that project as the root. ## Error handling - **Exit code**: Non-zero means the run failed; check stderr for the error message. - With `-o json`, on failure no JSON is emitted; only stderr. - In scripts, check `$?` after the wrapper and exit accordingly. ## Additional resources - For detailed output schemas and event types: [reference.md](reference.md) - Official docs: [Using Headless CLI](https://cursor.com/docs/cli/headless), [Output format](https://cursor.com/docs/cli/reference/output-format)


Security scan verdicts — ClawScan: clean | static analysis:  | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)