cursor-agent is now agent
Almost every third-party guide to Cursor CLI still tells you to type cursor-agent. The install script disagrees, in a comment you can read yourself: it creates “symlinks to the Cursor Agent executable (primary: agent, legacy: cursor-agent)”, linking both names at the same binary in ~/.local/bin/. Every current Cursor document uses agent. The legacy name keeps working, and Cursor has published no deprecation date for it — but if a tutorial is still built around cursor-agent, it predates the rename and probably predates other things too.
Cursor describes the product as: “Cursor CLI lets you interact with AI agents directly from your terminal to write, review, and modify code. Whether you prefer an interactive terminal interface or print automation for scripts and CI pipelines, the CLI provides powerful coding assistance right where you work.” This page is about that CLI. If you are comparing the editor instead, Claude Code vs Cursor covers that side, and CmdBrief against Cursor covers the workspace question.
Install and platforms
# macOS, Linux and Windows under WSL
curl https://cursor.com/install -fsS | bash
# Windows, native, in PowerShell
irm 'https://cursor.com/install?win32=true' | iex
agent --version
agent updateThe binary installs to ~/.local/share/cursor-agent/versions/<version>/ and is symlinked into ~/.local/bin/, which may not be on your PATH yet. Cursor publishes the fix verbatim for both shells: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc, and the same line against ~/.bashrc. The CLI also updates itself — “Cursor CLI will try to auto-update by default to ensure you always have the latest version” — which is convenient day to day and worth disabling anywhere you need a pinned build.
The documentation headings are literally “macOS, Linux and Windows (WSL)” and “Windows (native)”. Notably, Cursor does not recommend WSL over native Windows the way OpenCode v1 does — both are presented as first-class. The bash installer itself only accepts Linux* and Darwin*, which is why native Windows has its own entry point.
Plans, and the quota question nobody has answered
| Plan | Price | What the plan says |
|---|---|---|
| Hobby | Free | Limited agent requests, plus access to Composer. |
| Pro | $20/mo | Both usage pools. Explicitly includes MCPs, skills, and hooks, plus cloud agents. |
| Pro+ | $60/mo | Both usage pools, with a larger allowance. |
| Ultra | $200/mo | Both usage pools, with the largest allowance. |
| Teams | $40/user/mo | Team administration on top of Pro-level usage. |
| Start | ₹649/mo, tax inclusive, India only | The Cursor Models pool only. |
| Enterprise | Custom | Contact sales. |
Usage is split into two pools, in Cursor’s own words: “There are two separate usage pools, each resetting with your monthly billing cycle: Cursor Models: Significantly more included usage for Grok 4.7, Grok 4.6, Grok 4.5, and Composer 2.5. Other Models: The pool for third-party models, charged at the model’s API price.” Pro, Pro+ and Ultra include both; Start includes only the first. Current usage-based plans do not include Max Mode, and on legacy request-based plans Max Mode bills at the model’s API rate plus 20 per cent.
Models: Cursor brokers them, and you cannot bring your own key
Authentication is agent login, or an API key passed as --api-key or set as CURSOR_API_KEY. What you cannot do is point the CLI at a provider directly. Cursor brokers all inference, and the model catalogue is what your account can reach — discover it with agent models or --list-models, select with --model <model>.
The catalogue is broad. Cursor’s own models cover the Grok 4.5 through 4.7 line, including a 4.7 Fast and a 4.7 500k variant, plus Composer 2.5. Alongside them sit Anthropic models from Claude 4 Sonnet — including a 1M variant — through the 4.5, 4.6 and 4.7 families to Fable 5, Fable 5.1, Opus 4.8, Opus 5 and Sonnet 5; Google’s Gemini 2.5 through 3.8; OpenAI’s GPT-5 family through GPT-5.6 Luna, Sol and Terra; and Z.ai GLM 5.2, Moonshot Kimi K2.7 Code and K3, and Meta Muse Spark 1.3.
Cursor publishes no per-model context-window figures anywhere we could find. The only signals are the name encodings — “Grok 4.7 500k”, “Claude 4 Sonnet 1M” — and a changelog note that a headless --model selection requiring Max Mode now sends it, “so max-context variants are no longer clamped down”. Community forum posts quoting 200K, 300K or 1M numbers are not primary sources, so this site leaves that cell empty. The six-agent comparison shows how unusual that is: four of the other five publish exact token figures.
Sandbox, hooks and subagents
Cursor CLI is among the better-equipped agents in this cluster on all three, and the hooks story in particular is worth reading even if you never use Cursor as your primary agent.
| Feature | How it works |
|---|---|
| Sandbox | Configure command execution with /sandbox in session or --sandbox <mode> on launch, accepting enabled or disabled. An interactive menu toggles the sandbox and controls network access, and settings persist across sessions. A recent changelog entry adds a read-access boundary and routes sandboxed git-over-SSH on macOS and Linux through a SOCKS proxy, so allowlisted remotes work and denied ones fail with a clear error. |
| Hooks | Defined in hooks.json at project or user level, or installed through plugins. In Cursor’s words, hooks “let you observe, control, and extend the agent loop using custom scripts” and are “spawned processes that communicate over stdio using JSON in both directions”. Events cover session start and end, tool use before, after and on failure, subagent start and stop, shell execution before and after, MCP execution, prompt submission, file reads and edits, agent responses and thoughts, stop and pre-compact. User-level hooks are not loaded in cloud agents. |
| Claude Code hook compatibility | Stated plainly in the documentation: “Cursor supports loading hooks from third-party tools like Claude Code.” If you already maintain a Claude Code hook set, it is portable here. |
| Subagents | A dedicated documentation page: “Subagents are specialized AI assistants that Cursor’s agent can delegate tasks to. Each subagent operates in its own context window… You can use subagents in the editor, CLI, and Cloud Agents.” Foreground and background modes, built-ins including Explore and Bash, and controllable through the subagent hooks above. |
| MCP | Shares the editor’s configuration: “The CLI will automatically detect and respect your mcp.json configuration file, enabling the same MCP servers and tools that you’ve configured for the editor.” Config lives at .cursor/mcp.json or ~/.cursor/mcp.json, with agent mcp login, agent mcp list and agent mcp list-tools, plus an --approve-mcps flag. |
Hook portability is the quiet advantage. Of the six agent CLIs in this cluster, Cursor is the only one that documents reading another vendor’s hook configuration. If you have already built approval gates or logging around Claude Code, the sandbox and permission guide applies to both without a rewrite.
Worktrees and parallel work
# generate a worktree name
agent -w
# name it, and base it on a specific ref
agent --worktree review-fix --worktree-base main
# skip the setup scripts declared in .cursor/worktrees.json
agent --worktree review-fix --skip-worktree-setup
# be explicit about the repository root
agent --worktree review-fix --workspace /path/to/repo-w / --worktree [name] runs the session “in a new Git worktree under ~/.cursor/worktrees/<reponame>/<name>”, generating a name if you omit one. --worktree-base <branch> takes a branch or ref to base it on, defaulting to the current HEAD, and --skip-worktree-setup skips the setup scripts declared in .cursor/worktrees.json. That last file is the piece other agents do not have: a checked-in description of how to prepare a fresh worktree, so a new one arrives with dependencies installed rather than empty.
Combine that with the & prefix — prepending it to any message pushes the conversation to a Cloud Agent — and Cursor’s direction of travel becomes clear. The August 2026 changelog added persistent detachable sessions, self-hosted workers with --computer-use --share-desktop, worker pools via agent worker --pool <name>, durable goals through /goal, sticky skills, custom modes and plugin hooks. This is a CLI being pushed toward long-running fleet work. Running agents in parallel is the same problem approached from the Claude Code and Codex side.
Sessions, resume and headless runs
agent ls # pick a chat
agent resume # resume the latest
agent --continue # alias for --resume=-1
agent --resume="chat-id-here"
agent create-chat # returns a new empty chat id
# detachable persistent sessions
agent persist
agent persist attach
agent persist list
agent persist stop
# headless
export CURSOR_API_KEY=...
agent -p "Analyze this code" --output-format jsonPersistent sessions arrived in the 26 August 2026 release: “Start a persistent session with agent persist, detach with /detach, and reconnect later with agent persist attach. Use agent persist list|stop to manage sessions or agent persist --resume to continue an existing chat.” For scripting, -p / --print “has access to all tools, including write and shell”, --output-format accepts text, json or stream-json and only works alongside --print, --stream-partial-output streams as it goes, and --trust accepts a workspace without prompting in headless mode only.
Other flags worth knowing: -f / --force (also spelled --yolo) force-allows commands unless explicitly denied, --mode <plan|ask> and --plan set the posture, --plugin-dir adds plugins, and -H / --header adds request headers. The subcommand surface includes agent about, agent worker start for a private cloud worker in your own environment, a hidden agent acp, agent generate-rule and agent rule, and shell integration install and uninstall.
Rules: .mdc files, AGENTS.md and CLAUDE.md
Cursor’s native format is version-controlled: “Project rules live in .cursor/rules as .mdc files.” The frontmatter carries description, globs and alwaysApply, and the documentation is explicit about the trap — “A plain .md file in .cursor/rules is ignored by the rules system because it has no frontmatter… If you prefer plain markdown, use AGENTS.md instead.”
The CLI is deliberately generous beyond that: it “also reads AGENTS.md and CLAUDE.md at the project root (if present) and applies them as rules”. That makes Cursor CLI and Grok Build the two agents in this cluster that read both conventions — precisely the opposite choice from OpenCode v2, which recognises AGENTS.md only and dropped the CLAUDE.md fallback on purpose, and from Kimi Code CLI, which never had one.
Where CmdBrief fits
CmdBrief is a Mac workspace that runs Claude Code, Codex, Grok CLI, Kimi CLI, OpenCode and Cursor CLI together (Claude, Codex, Grok and Cursor can lead): per-product workspaces, working, needs-input and done states per pane, diff review and an integrated terminal. For Cursor CLI specifically it reads chats from ~/.cursor/chats, maintains a managed block in ~/.cursor/hooks.json so pane state is driven by the agent rather than guessed, and shows the monthly Cursor Models and Other Models pools by calling Cursor’s dashboard usage endpoint with your local Cursor credential.
One deliberate exclusion: it reads the CLI’s chats, not the editor’s transcripts under projects/*/agent-transcripts. Those are the editor’s record of its own work, and mixing them into a CLI session list would make the history lie about what ran where.
Because Cursor is the only one of the six that will not take your own provider key, it tends to be an addition rather than a replacement. The six-agent comparison shows which capabilities overlap, the usage limits guide covers what happens when a pool runs out mid-task, and the tool comparisons cover the workspaces you would run all of it in.
Questions
Is it cursor-agent or agent?
Both work, but agent is now primary. The install script creates symlinks for both names at the same binary and labels cursor-agent as legacy; every current Cursor document uses agent. Cursor has published no removal date for the legacy name.
How do I install Cursor CLI?
Run curl https://cursor.com/install -fsS | bash on macOS, Linux or Windows under WSL, or irm 'https://cursor.com/install?win32=true' | iex in PowerShell for native Windows. The binary lands in ~/.local/share/cursor-agent/versions/ and is symlinked into ~/.local/bin/, which you may need to add to your PATH. Verify with agent --version and update with agent update.
Does Cursor CLI usage come out of the same quota as the editor?
Cursor does not document an answer. The pricing page, the models-and-pricing documentation, the usage-limits help article and every CLI documentation page are silent on it — the word “CLI” does not appear in any pricing or usage document. The circumstantial evidence points to shared pools: agent login authenticates the Cursor account, agent models lists models for that account, and the usage documentation describes account-level pools with no per-surface split. Confirm it in your own dashboard rather than trusting an inference.
Can I use my own Anthropic or OpenAI key with Cursor CLI?
No. Cursor brokers all inference. You authenticate with a Cursor account through agent login, or with a Cursor API key through --api-key or CURSOR_API_KEY. There is no documented way to supply a third-party provider key — which makes it the only one of the six agent CLIs in this cluster without that option.
Does Cursor CLI support worktrees?
Yes, natively. -w or --worktree [name] runs the session in a new Git worktree under ~/.cursor/worktrees/<reponame>/<name>, generating a name if you omit one. --worktree-base <branch> sets the base ref, defaulting to the current HEAD, and --skip-worktree-setup skips the setup scripts declared in .cursor/worktrees.json.
Still unsure? Write to [email protected] or use the contact form. Contact CmdBrief →
Primary sources
Provider terms and product behavior can change. Confirm plan, pricing, model, and permission details in the current official documentation.