# Cursor CLI (2026): the agent binary, worktrees, hooks and quota

> Cursor’s terminal agent, now installed as the “agent” binary. Install, plans, sandbox modes, worktrees, hooks, subagents and session resume, checked September 2026.

- **Category:** Workflows
- **Updated:** 2026-09-22
- **Reading time:** 10 min
- **Canonical page:** https://cmdbrief.com/guides/cursor-cli

## 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](https://cmdbrief.com/guides/claude-vs-cursor) covers that side, and [CmdBrief against Cursor](https://cmdbrief.com/compare/cursor) covers the workspace question.

> **Tip:** There is no public repository for the CLI and no release feed. The only machine-readable version signal is the pinned download URL in the install script, which on 22 September 2026 carried `2026.09.18-9a7762b` — a string that encodes 18 September 2026. The published CLI changelog’s most recent entry was 26 August 2026, so the changelog lags the shipping build by around three weeks.

## Install and platforms

**Install Cursor CLI**

```bash
# 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 update
```

The 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](https://cmdbrief.com/guides/opencode) — 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. |

*Cursor pricing, read 22 September 2026, and cross-checked against the schema.org offers embedded in the page. Cursor states that subscriptions are only sold directly through cursor.com and that it authorises no resellers or third-party sellers.*

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.

> **Warning:** Here is the thing no Cursor document states: whether CLI usage draws on the same pools as the editor. We checked the pricing page, the models-and-pricing documentation, the usage-limits help article and every CLI documentation page — the string “CLI” never appears in a pricing or usage document, and no CLI document mentions plans, quotas or free-tier eligibility. The circumstantial evidence points one way: `agent login` authenticates your Cursor account, `agent models` is documented as listing models “for this account”, and the usage documentation describes account-level pools with no per-surface split. Treat that as an inference, not a fact, and confirm it against your own dashboard before you plan around it. The same gap means no document says whether the CLI works at all on the free Hobby plan.

## 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](https://cmdbrief.com/guides/agent-cli-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. |

*Read from the Cursor CLI and hooks documentation on 22 September 2026.*

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](https://cmdbrief.com/guides/claude-code-sandbox) applies to both without a rewrite.

## Worktrees and parallel work

**Run in an isolated worktree**

```bash
# 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](https://cmdbrief.com/guides/run-claude-code-and-codex-in-parallel) is the same problem approached from the Claude Code and Codex side.

## Sessions, resume and headless runs

**Session and headless flags**

```bash
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 json
```

Persistent 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](https://cmdbrief.com/guides/grok-cli) 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](https://cmdbrief.com/guides/kimi-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](https://cmdbrief.com/guides/agent-cli-comparison) shows which capabilities overlap, [the usage limits guide](https://cmdbrief.com/guides/claude-code-usage-limits) covers what happens when a pool runs out mid-task, and [the tool comparisons](https://cmdbrief.com/compare) 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`.

## Primary sources

Provider terms and product behavior can change. Confirm plan, pricing, model, and permission details in the current official documentation.

- [Cursor CLI overview](https://cursor.com/docs/cli/overview)
- [Cursor CLI installation](https://cursor.com/docs/cli/installation)
- [Cursor CLI parameter reference](https://cursor.com/docs/cli/reference/parameters)
- [Cursor CLI headless usage](https://cursor.com/docs/cli/headless)
- [Cursor CLI changelog](https://cursor.com/docs/cli/changelog)
- [Cursor hooks](https://cursor.com/docs/hooks)
- [Cursor subagents](https://cursor.com/docs/subagents)
- [Cursor rules](https://cursor.com/docs/rules)
- [Cursor MCP](https://cursor.com/docs/mcp)
- [Cursor models and pricing](https://cursor.com/docs/models-and-pricing)
- [Cursor usage limits](https://cursor.com/help/models-and-usage/usage-limits)
- [Cursor pricing](https://cursor.com/pricing)

## Keep reading

- Comparisons: [Agent CLI comparison (2026): six terminal coding agents](https://cmdbrief.com/guides/agent-cli-comparison)
- Comparisons: [Claude Code vs Cursor (2026): terminal agent or editor workflow?](https://cmdbrief.com/guides/claude-vs-cursor)
- Workflows: [OpenCode in 2026: v1 vs v2, plans, and which one you mean](https://cmdbrief.com/guides/opencode)

---

Markdown mirror of https://cmdbrief.com/guides/cursor-cli, generated at build time from the same data the HTML page renders. Machine-readable index: https://cmdbrief.com/llms.txt