Cursor Cli

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  "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  "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 | e.g. composer-2.5 | | --mode plan\|ask | Read-only modes | | --workspace | Repo root (default: cwd) | | --resume | Continue a session | | --schema | JSON Schema file | | --schema-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 | Overall wall-clock limit (default: 30 minutes) | | --idle-timeout-ms | 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ferueda
• Source: ferueda/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.