Cursor Agent

Cursor Agent CLI — Composer + admitted Grok lane

Headless Cursor Agent from any terminal. Announced 2025-08-07; docs: cursor.com/docs/cli.

Default model: composer-2.5 (also composer-2.5-fast). Exact Cursor-native Grok 4.5 slugs are an opt-in read-only review lane: cursor-grok-4.5-{low,medium,high} and matching trailing -fast variants. Cursor subscription auth — not xAI API, llmx, or claude -p. Never pass generic proxied models (opus/gpt/claude/gemini/sonnet) or bare grok-4.5; the guard admits Composer plus only those exact live Grok slugs. For Opus/GPT use claude -p / codex exec / llmx.

Install & auth

curl https://cursor.com/install -fsSL | bash   # installs ~/.local/bin/agent
agent login                                     # once; NO_OPEN_BROWSER=1 for headless
agent status                                    # must show logged-in email
agent update                                    # bump CLI (pin version in eval manifests)
agent models                                    # list account models

Binary aliases: agent → cursor-agent (same binary).

The three invocation shapes

Flags that matter

• -p / --print — headless; stdout is the deliverable (scripts/CI).
• --trust — skip workspace-trust prompt (required with -p).
• --mode ask|plan — read-only; default agent mode edits + runs shell.
• --model MODEL — pin composer-2.5, composer-2.5-fast, or an exact live cursor-grok-4.5-* slug; omit → account default (often Composer fast).
• --workspace PATH — isolate cwd (use a throwaway dir for evals/dispatch).
• --output-format text|json — json for usage/token forensics in evals.
• --force / --yolo — auto-approve shell unless explicitly denied.
• --sandbox enabled|disabled — override sandbox; eval probes use default sandbox + ask mode.
• --resume / --continue — session continuity across calls.

Modes (same as editor)

Composer 2.5 dispatch patterns

Screening probe (cheap, deterministic)

agent -p --mode ask --trust --model composer-2.5 \
  --workspace /tmp/cursor-probe-empty \
  --output-format text \
  "Reply with exactly: COMPOSER_OK"

Grok 4.5 repo-read probe (opt-in, fail closed)

agent models | rg '^cursor-grok-4\.5-high - '
agent -p --mode ask --trust --model cursor-grok-4.5-high \
  --workspace "$PWD" --output-format text \
  "Read the current git HEAD with read-only tools and report its first 12 hex characters."

The critique harness enforces exact registry + an unrevealed repo-HEAD canary before every grok axis dispatch. Current evidence covers ask-mode repo review; it does not license Grok for autonomous writes.

Uniform eval arm (evals repo)

~/Projects/evals/bin/dispatch-cursor-arm.sh \
  <workspace> composer-2.5 ask "<prompt>" out.txt [manifest.json]

Reads out.txt; optional manifest records CLI version + prompt hash.

Parallel terminals

Each shell is an independent session — no shared context unless --resume:

agent -p --trust --model composer-2.5 --workspace ~/Projects/foo "task A" &
agent -p --trust --model composer-2.5-fast --workspace ~/Projects/bar "task B" &
wait

Cloud handoff (interactive only): prefix message with & → continues on cursor.com/agents.

When to use vs other lanes

Measured screening eval: ~/Projects/evals/composer_cli_probe/ — ask-mode deterministic tasks, composer-2.5 vs composer-2.5-fast.

Footguns

1. Forgot --trust with -p — hangs on workspace prompt in scripts.
2. Ask mode for writes — agent can read/grep but won't edit; use default agent mode + --force for implementation arms.
3. Default model drift — always pass the exact model when comparing. Grok slugs put effort before an optional trailing -fast; there is no xhigh slug, and bare grok-4.5 is xAI API rather than Cursor subscription.
4. Empty stdout — check exit code + stderr; wrap with timeout in orchestrators (timeout 120 agent …). Observed 2026-06-18: --mode plan returned empty -p stdout 2/3 runs (exit 0, no stderr) on open-ended critique prompts; --mode ask --trust was 2/2 reliable. For headless review/critique TEXT, prefer --mode ask; treat a 1-byte output as a silent failure and re-run (or use --output-format json and check is_error).
5. Sandbox vs network — ask-mode file reads are local; web fetch depends on sandbox config. Don't assume search works headlessly without probing.
6. Beta security — CLI can read/write/delete and run shell (blog disclaimer). Trusted environments only; isolate with --workspace throwaways.
7. Don't confuse with Cursor IDE Tab — this is the Agent product line, model family Composer.
8. Cost is usage-METERED, not $0 — do NOT analogize from codex-cli/claude-cli. Those subscription CLIs are genuinely $0-marginal within rate limits; Cursor is different: calls draw from the "Auto + Composer" included-usage pool, then bill usage-based (Composer ~$0.50/M in, $2.50/M out; -fast $3/$15; proxied frontier models at their own rates). Near-free within the monthly pool, then metered. (We shipped a "$0 marginal" claim across 5 docs by analogizing without checking — corrected 2026-06-14. Verify vendor pricing at cursor.com/pricing before asserting cost.) Full: agent-infra research/2026-06-14-cursor-cli-composer-integration.md.
9. --approve-mcps auto-trusts ALL MCP servers; auto-update drift. Never pass --approve-mcps in automation (a global MCP config could be auto-trusted). cursor-agent auto-updates itself + flags evolve (beta) — pin or smoke-test scripted transports on a schedule, and prefer --output-format json + check is_error over trusting non-empty text.

Quick diagnose

agent status && agent about
agent -p --mode ask --trust --model composer-2.5 "Reply with exactly: PING"

Exit non-zero → read stderr; re-run with --output-format json for structured error.

$ARGUMENTS