Delegate work to a Cursor agent from the shell without the IDE chat. Use when the user wants another agent to call, ask, invoke, or run Cursor on a task.
Global script: ~/.agents/skills/cursor-cli/scripts/cursor-agent.mjs
Optional launcher: cursor-agent
Requires agent on PATH. Local dev: agent login once. CI/servers: CURSOR_API_KEY.
When to use
| Situation | Use this |
|---|---|
| User says "call cursor", "ask cursor", "invoke cursor", etc. | cursor-agent "…" |
| Already inside Cursor IDE chat | Task tool — not CLI |
| Long-lived typed service | @cursor/sdk |
Quick start
# Check auth + CLI version
cursor-agent
# Invoke (read-only by default — no file edits)
cursor-agent "explain the backend routing"
# Allow edits
cursor-agent --force "add a regression test for auth"
# Typed JSON response
cursor-agent \
--schema-json '{"type":"object","required":["verdict"],"properties":{"verdict":{"type":"string"}}}' \
"Review auth.ts"
# Continue a session
cursor-agent --resume <session-id> "follow up"
Caller flow: parse stdout → check status → read structuredOutput or result → save sessionId for --resume.
If the launcher is not installed, call the script directly:
node ~/.agents/skills/cursor-cli/scripts/cursor-agent.mjs "your task"
Output
Default format is TOON on stdout (token-efficient). Use --format json when debugging.
Success example:
status: completed
sessionId: uuid
durationMs: 8783
usageSummary: 45271 in, 76 out
result: truncated answer preview…
help[1]: Run `cursor-agent --resume <id> "follow up"` to continue
With --schema / --schema-json:
status: completed
sessionId: uuid
structuredOutput:
verdict: pass
summary: …
Errors also go to stdout (not stderr):
status: failed
error: prompt is required
help[1]: Run `cursor-agent "your task"` or --prompt-file / --stdin
Exit codes: 0 success, 1 error, 2 usage.
Envelope fields
| Field | When |
|---|---|
status |
completed, failed, timed_out |
sessionId |
Resume with --resume |
result |
Answer text (~800 char preview; use --full for all) |
structuredOutput |
With --schema — validated JSON |
error |
Failure message |
help |
Suggested next commands |
usageSummary |
Token counts when available |
Flags
| Flag | Purpose |
|---|---|
--force |
Allow file/shell changes (off by default) |
--model <id> |
e.g. composer-2.5 |
--mode plan|ask |
Read-only modes |
--workspace <path> |
Repo root (default: cwd) |
--resume <id> |
Continue a session |
--schema <path> |
JSON Schema file |
--schema-json '<json>' |
Inline schema (mutually exclusive with --schema) |
--format toon|json |
Output format (default: toon) |
--full |
Untruncated result |
--verbose |
Include raw usage object |
--max-runtime-ms <n> |
Overall wall-clock limit (default: 30 minutes) |
--idle-timeout-ms <n> |
Optional no-output timeout; disabled by default because Cursor may be silent while tools run |
--quiet |
Suppress stdout |
--prompt-file, --stdin |
Prompt input |
--sandbox enabled|disabled |
Sandbox override |
The wrapper always passes --trust --approve-mcps to Cursor CLI. Use --force only when the delegated agent should edit files or run mutating commands.
Structured output
Cursor CLI has no native JSON-schema mode. The wrapper injects schema instructions into the prompt, parses JSON from the answer, and validates a basic subset (type, required, properties, items, enum).
--schema— reusable schema file in the repo--schema-json— one-off inline schema
On success with a schema, prefer structuredOutput over result.
Auth
| Context | What you need |
|---|---|
Your machine (after agent login) |
Nothing extra |
| CI / headless server | CURSOR_API_KEY |
Verify: agent status
Install globally
Install the skill folder at ~/.agents/skills/cursor-cli. Node 18+, no npm dependencies.
Optional launcher:
mkdir -p ~/.local/bin
ln -sf ~/.agents/skills/cursor-cli/scripts/cursor-agent.mjs ~/.local/bin/cursor-agent
chmod +x ~/.agents/skills/cursor-cli/scripts/cursor-agent.mjs
Ensure ~/.local/bin is on PATH.
Raw CLI escape hatch
agent -p --trust --approve-mcps --workspace . "prompt"
agent -p --force "apply changes"