Cursor CLI

Cursor CLI brings Cursor’s Agent to the terminal. It’s designed for two modes: an interactive TUI for hands-on coding sessions, and a non-interactive “print” mode for scripts and CI. The agent can read/write files, search your codebase, and (with approval) run shell commands. It respects the same Rules system as the IDE (.cursor/rules), reads AGENTS.md/CLAUDE.md at the repo root, and supports MCP servers you’ve configured. It works with any model included in your Cursor subscription. The CLI is in beta; use it only in trusted environments.

WHERE YOU CAN USE IT • Local shells (bash/zsh/fish) on macOS, Linux, and Windows via WSL.
• Remote servers, containers, Codespaces, and CI (e.g., GitHub Actions).
• Alongside editors like Neovim or JetBrains—keep your editor, add Cursor’s Agent.

SETUP (QUICK START)

1. Install:
   curl https://cursor.com/install -fsS | bash
   (Then ensure ~/.local/bin or the printed path is on $PATH.)
2. Verify:
   cursor-agent --version
3. Start an interactive session:
   cursor-agent
4. Optional auth for headless/CI: set CURSOR_API_KEY and run with -p/--print.
5. Auto-updates run by default; you can manually upgrade with cursor-agent update.

INTERACTIVE WORKFLOW (TERMINAL UI) • Start with or without an initial prompt:

• cursor-agent
• cursor-agent "refactor the auth module to use JWT" • Steer and review:
• Review diffs with Ctrl+R; use I to add follow-up instructions.
• Select context with @ to include specific files or folders.
• Use /compress to shrink context when you hit token limits.
  • History: cursor-agent ls to list sessions; cursor-agent resume (or --resume <id>) to continue a thread. • Command safety: the CLI asks you to approve (Y) or reject (N) shell commands before execution.

NON-INTERACTIVE / HEADLESS (SCRIPTS & CI) • Print mode for scripts/automation:

• cursor-agent -p -m gpt-5 "find and fix performance issues"
  • Output formats for automation:
• --output-format json emits a single result JSON object.
• --output-format stream-json emits NDJSON events (system init, deltas, tool calls, result)—perfect for progress UI or jq pipelines.
• --output-format text prints human-readable progress lines. • File writes in print mode are gated: pass --force to allow edits (otherwise changes are only proposed). • CI example (GitHub Actions): install the CLI, export CURSOR_API_KEY, and run an agent step with your prompt/model. You can choose full autonomy (agent handles git/PRs) or a restricted model where critical operations remain deterministic in separate steps.

CONFIGURATION & EXTENSIBILITY • Rules: place repo-scoped rules under .cursor/rules/; the CLI also reads AGENTS.md and CLAUDE.md.
• MCP: the CLI auto-discovers your MCP servers (mcp.json) and will invoke tools when relevant; you can list servers and tools via cursor-agent mcp ....
• Permissions: lock down capabilities per project or globally in .cursor/cli.json or ~/.cursor/cli-config.json using allow/deny tokens—e.g., Shell(git), Read(src/**/*.ts), Write(package.json). In print mode, writes still require --force.

TUTORIAL: FROM ZERO TO AUTOMATION

1. Plan before editing: start with “do not write any code” to force a plan. Approve the plan, then drop the guard to allow edits.
2. Interactive refactor: cursor-agent → describe the goal → use @ to add just the modules you need → Ctrl+R to inspect diffs → approve or request changes with I.
3. Structured code review: cursor-agent -p --output-format json "review these changes for security issues" | jq '.result' → save results to a file or post to a PR.
4. Apply changes in batch: find src -name "*.js" | while read f; do cursor-agent -p --force "add JSDoc comments to $f"; done.
5. Streaming dashboards: run with --output-format stream-json and pipe to a small script to track tool events (reads/writes) and total duration in real time.
6. CI with guardrails: configure deny rules for Shell(git) and .env* writes; let the agent only modify docs, then commit/push in a deterministic step.

PRO TIPS • Use model selection (--model <name>) to match the task—faster models for quick edits, frontier models for deep refactors.
• Keep prompts scoped; combine with @ context selection and /compress for long repositories.
• Save time with sessions: ls and resume let you iterate across days while keeping context.
• Encode your conventions in .cursor/rules/ and AGENTS.md so teams get consistent diffs and messages.
• Prefer restricted autonomy + explicit CI steps for production pipelines; reserve full autonomy for sandboxes.

SECURITY NOTE The CLI can read, modify, and delete files, and run commands (interactive approval in TUI; --force required for writes in print mode). Use in trusted environments and apply permission rules for least privilege.