cursor-cli

name	cursor-cli
description	Run Cursor Agent headlessly and delegate work to another Cursor agent over the CLI. Use when the user asks to call, ask, invoke, run, or delegate to Cursor (e.g. "call cursor", "ask cursor", "invoke cursor agent"); when automating Cursor from scripts or agent-to-agent flows; or when the user mentions `agent -p`, headless Cursor CLI, or `cursor-agent.mjs`.

Cursor CLI (Headless)

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"

Docs: https://cursor.com/docs/cli