# How to use Cursor CLI: a step-by-step guide

URL: https://agentvera.dev/en/blog/how-to-use-cursor-cli/ · Published: 2026-10-29

How to use Cursor CLI: install the agent command, sign in, switch Agent, Plan and Ask modes, script it with print mode, and set up models, rules and MCP.

**In short:**

- Install Cursor CLI with one curl command (or a PowerShell one-liner on Windows), run agent login, then run agent in a project. The old cursor-agent name still works as an alias.
- agent opens an interactive session with Agent, Plan and Ask modes. agent -p runs one task for scripts and CI; add --force to apply file changes and --output-format json for machine output.
- The CLI uses your Cursor plan’s usage pool, the same rules (.cursor/rules, AGENTS.md, CLAUDE.md) and the same mcp.json as the editor, so setup carries over from Cursor.

To use Cursor CLI, install it with `curl https://cursor.com/install -fsS | bash`, sign in with `agent login`, go to a project folder and run `agent`. You describe a task, and Cursor’s agent reads your code, edits files and runs commands after you approve them. For scripts and CI, `agent -p "your task"` runs one prompt without the interactive screen.

That is the core loop. This guide covers the rest: the three modes, print mode, models, rules files, MCP servers, permissions, how the CLI draws on your Cursor plan, its limits, and how to run it next to other coding CLIs. Everything here follows Cursor’s official docs as of October 2026.

## What Cursor CLI is

Cursor CLI brings the agent from the Cursor editor to the terminal. It uses the same account, the same models, the same rules and the same MCP configuration as the editor, so if your team already uses Cursor, the CLI behaves the way people expect. It runs anywhere a terminal does: a remote server over SSH, a CI runner, or a pane next to another agent.

A note on the name: the command used to be `cursor-agent`. In January 2026 Cursor made `agent` the main entry point, and `cursor-agent` still works as an alias. Older guides and tools that call `cursor-agent` keep working; this guide uses `agent`.

If you are still deciding between Cursor and a terminal-first agent, [Claude Code vs Cursor](/en/blog/claude-code-vs-cursor/ "Claude Code vs Cursor") compares the two. This post assumes you have picked Cursor and want to use it from the terminal.

## Step 1: install Cursor CLI

| Platform | Command |
| --- | --- |
| macOS, Linux, WSL | `curl https://cursor.com/install -fsS \| bash` |
| Windows (PowerShell) | `irm 'https://cursor.com/install?win32=true' \| iex` |

Check the install:

```bash
agent --version
```

If the shell can’t find `agent`, add `~/.local/bin` to your `PATH` and open a new terminal. The CLI updates itself by default; `agent update` updates it by hand.

## Step 2: sign in

```bash
agent login     # opens the browser
agent status    # shows who you are signed in as
agent logout
```

On a machine without a browser, set `NO_OPEN_BROWSER=1` and `agent login` prints the URL instead. For CI and scripts, create an API key in the Cursor dashboard under API Keys and pass it as the `CURSOR_API_KEY` environment variable or with `--api-key`.

## Step 3: the interactive session

Start the agent in a project, with or without a first prompt:

```bash
cd my-project
agent
agent "add input validation to the signup form"
```

The CLI has three modes. Shift+Tab rotates through them:

| Mode | What it does | How to enter it |
| --- | --- | --- |
| Agent | Default. Edits files and runs commands. | Default |
| Plan | Works out an approach with you before any code changes. | Shift+Tab, `/plan`, `--plan` or `--mode=plan` |
| Ask | Read-only. Explores and answers questions about the code. | `/ask` or `--mode=ask` |

A good habit for anything non-trivial: start in Plan, agree on the approach, then switch to Agent and have it build. A few more things you will use every day:

- **`@`** picks files to add to your message.
- **Ctrl+R** reviews the changes the agent made.
- **Shift+Enter** (or Ctrl+J) adds a new line; **Up arrow** walks your earlier messages.
- **Shell commands** need your y/n approval before they run.
- **`/model`** switches models; **`/clear`** starts a fresh chat; **`/summarize`** compresses a long one.
- **Ctrl+D twice** exits.

Chats are saved. `agent ls` lists them, `agent resume` (or `--continue`) picks up the latest one, and `--resume="chat-id"` opens a specific one. Inside a session, `/resume`, `/fork` and `/rewind` do what their names say.

Two extras worth knowing. Prefixing a message with `&` hands the conversation to a Cursor Cloud Agent, which keeps working while you are away; you pick it up at cursor.com/agents. And `-w` (or `--worktree name`) runs the agent in a new Git worktree under `~/.cursor/worktrees/`, so it doesn’t touch your current checkout.

## Step 4: print mode for scripts and CI

Print mode runs one prompt and exits, which makes the CLI usable from scripts, Git hooks and CI pipelines:

```bash
# Read-only question, plain text answer
agent -p "summarize what changed in src/billing since the last release"

# Apply changes (without --force, changes are only proposed)
agent -p --force "add JSDoc comments to every exported function in src/utils"

# Machine-readable output for another tool
agent -p --output-format json "list the TODO comments in this repo"
```

The flags that matter here:

- **`--force`** (alias `--yolo`) lets the agent write files and run commands without asking, unless a deny rule blocks them. This is the switch that makes print mode actually change things.
- **`--output-format`** takes `text` (default), `json` or `stream-json`. Add `--stream-partial-output` with `stream-json` to get text as it is generated.
- **`--trust`** trusts the workspace without a prompt; **`--approve-mcps`** approves the configured MCP servers.
- **`--model`** and **`--workspace`** set the model and the folder.

Cursor also documents running the CLI inside GitHub Actions. Treat `--force` in CI the way you would treat any unattended agent: a scoped API key, a throwaway runner, and changes that land on a branch for review.

## Step 5: pick a model

```bash
agent models                   # models your account can use
agent --model <model-id>       # start with a specific model
```

Inside a session, `/model` opens the picker, and `/model grok` filters it. If you don’t pass a model, the CLI uses the one set for your account. Which models you see depends on your plan (see the pricing section below): every paid plan includes Cursor’s own models, while third-party models need Premium or above.

## Step 6: rules, AGENTS.md and CLAUDE.md

Cursor CLI uses the same rules system as the editor. Rules live in `.cursor/rules`, and the CLI also reads `AGENTS.md` and `CLAUDE.md` at the project root and applies them alongside. As of the October 2026 release, nested `AGENTS.md` files apply when the agent edits files in those subfolders.

```markdown
# Project rules

- Package manager: pnpm. Run `pnpm test` before you finish a task.
- TypeScript strict mode; no `any` in new code.
- Never edit files in src/generated/.
```

If several agents work in one repo, `AGENTS.md` is the file they all read, so it is the best home for shared rules. `agent generate-rule` creates a new Cursor rule interactively. For what belongs in these files, see [how to write CLAUDE.md and AGENTS.md](/en/blog/claude-md-agents-md/ "How to write CLAUDE.md and AGENTS.md").

## Step 7: MCP servers

[MCP servers](/en/blog/what-is-mcp-server/ "What is an MCP server") give the agent new tools: a browser, an issue tracker, a database. Cursor CLI reads the same `mcp.json` as the editor: `.cursor/mcp.json` in a project, `~/.cursor/mcp.json` for all projects. Anything you set up in the editor is already there.

```bash
agent mcp list                 # configured servers and their status
agent mcp list-tools <id>      # tools a server exposes
agent mcp login <id>           # sign in to a server that uses OAuth
agent mcp disable <id>         # turn one off without deleting it
```

Inside a session, `/mcp list` shows the same thing. Each server adds its tools to the agent’s context, so keep only the ones you need turned on.

## Step 8: permissions and config

Global settings live in `~/.cursor/cli-config.json` (on Windows, `%USERPROFILE%\.cursor\cli-config.json`). A project can add a `.cursor/cli.json` that holds permissions only. Both are plain JSON, without comments.

```json
{
  "permissions": {
    "allow": ["Shell(git)", "Shell(ls)", "Read(src/**/*.ts)", "Write(package.json)", "Mcp(datadog:*)"],
    "deny": ["Shell(rm)", "Read(.env*)", "Write(**/*.key)"]
  }
}
```

Each entry names a tool and a pattern: `Shell(...)`, `Read(...)`, `Write(...)`, `WebFetch(domain)` and `Mcp(server:tool)`. Deny wins over allow. The global file also sets the approval mode (`allowlist`, `auto-review` or `unrestricted`), sandbox settings and whether commits get a “Made with Cursor” trailer.

## How Cursor CLI ties to your Cursor plan

There is no separate CLI subscription. The CLI uses your Cursor account, and as of October 2026 Cursor is sold as part of The X Subscription, alongside Grok and X. Each paid plan has one usage pool for Cursor’s own models (Grok 4.7, Grok 4.6, Grok 4.5 and Composer 2.5). The editor, the CLI, Cloud Agents and the Grok apps all draw from it, and it refreshes weekly.

| Plan | Price (monthly) | Included usage | Third-party models |
| --- | --- | --- | --- |
| Free | $0 | Limited | Not available |
| Plus | $8 | Base | Not available |
| Premium | $30 | 4x Plus | API list price, from prepaid credit |
| Super | $100 | 15x Plus | API list price, from prepaid credit |
| Ultra | $200 | 50x Plus | API list price, from prepaid credit |
| Teams | $30, $100 or $200 per seat | Matches the seat’s tier | API list price plus Cursor’s token rate |

What this means for CLI use:

- **Different models drain the pool at different rates.** Your remaining usage and the next reset show up in the editor settings and in the usage dashboard.
- **Claude, GPT and Gemini are not in the pool.** On Premium and above you pay their API list price from prepaid credit from the first request. Plus and Free can’t use them.
- **Plus leaves out Cloud Agents and Auto.** The `&` handoff to a Cloud Agent needs Premium or above.
- **Older plans still work.** Pro, Pro+, Ultra, Start and Teams Standard or Premium seats are legacy plans that keep their two monthly pools and on-demand usage.

## Limits worth knowing

- **Shell Mode has a 30-second timeout.** `/shell` runs commands directly, but it can’t run long-lived servers or interactive prompts, and `cd` doesn’t carry over between commands.
- **Print mode is careful by default.** Without `--force` it proposes changes instead of writing them, which surprises people the first time.
- **Config files are strict JSON.** A comment or trailing comma in `cli-config.json` breaks it.
- **One chat per terminal.** The CLI has worktrees and Cloud Agents, but no built-in view of several local agents at once.

## Common pitfalls

- **`command not found: agent`.** `~/.local/bin` isn’t on your `PATH`.
- **A tool still calls `cursor-agent`.** That’s fine; the alias stays. Only the docs moved to `agent`.
- **The model you want isn’t in the list.** It is a third-party model and your plan is Free or Plus.
- **Rules ignored.** Check that `AGENTS.md` or `CLAUDE.md` sits at the project root, or that the rule in `.cursor/rules` applies to the files being edited.
- **CI hangs on a prompt.** Add `--trust`, use `CURSOR_API_KEY`, and pass `--approve-mcps` if MCP servers are configured.

## Running Cursor CLI next to other CLIs

Cursor CLI is a good pick when your team already lives in Cursor: same models, rules and MCP servers in the editor and the terminal. If you want deep terminal extension points such as hooks, skills and plugins, Claude Code is stronger there; and if you are leaving Cursor altogether, our list of the [best Cursor alternatives](/en/blog/best-cursor-alternatives/ "Best Cursor alternatives") covers the options honestly.

Many people end up running Cursor CLI alongside Claude Code, Codex or Gemini CLI, each on a different task. In plain terminals that means one tab per agent and `-w` worktrees to keep them apart. AgentVera is a desktop app that runs these CLIs side by side in real terminals, with your own installs and logins. Its [Cursor support](/en/agents/cursor-agent/ "Cursor in AgentVera") works like this:

- **Its own chat per agent.** Every new Cursor agent gets an empty chat (`cursor-agent create-chat`) and always returns to it, so several Cursor agents can work in one project without mixing up. The Cursor editor doesn’t need to be open.
- **Your login and models.** It uses Cursor CLI’s own sign-in; left empty, the model comes from your Cursor settings.
- **Rules, not role prompts.** Cursor CLI has no extra-instructions flag, so the agent’s Role field doesn’t reach it. Put lasting instructions in `AGENTS.md` or rule files.
- **MCP from one place.** MCP servers you add in AgentVera, plus its browser, are added as a local plugin and approved for the run.
- **Grid, accounts and servers.** Run Cursor in the [workspace](/en/features/workspace/ "Workspace") grid next to other agents, with automatic code review when a turn ends. Under Settings → Accounts you can add [several Cursor accounts](/en/features/account-switching/ "Account switching") as a fallback order, and a Cursor agent can also run on a saved SSH server.

To try it, [download AgentVera](/en/download/ "Download AgentVera").

## Wrapping up

To use Cursor CLI: install it, run `agent login`, and run `agent` in a project. Plan with Shift+Tab before big changes, use `agent -p --force` for scripts, and keep your rules in `AGENTS.md` or `.cursor/rules` and your tools in `mcp.json`. Your Cursor plan sets how far the usage goes, so pick models with the weekly pool in mind.

## Frequently asked questions

**Is the Cursor CLI command agent or cursor-agent?** Both work. As of October 2026 the main command is agent, and cursor-agent still works as an alias for older scripts and tools. Check your install with agent --version.

**Is Cursor CLI free?** The CLI itself costs nothing to install, and it works on Cursor’s Free plan with limited usage. Paid plans give a weekly usage pool for Cursor’s own models that the editor, the CLI and Cloud Agents share. Third-party models such as Claude, GPT and Gemini need Premium or above and are billed at API list price from prepaid credit.

**Does Cursor CLI read AGENTS.md and CLAUDE.md?** Yes. Besides the rules in .cursor/rules, the CLI reads AGENTS.md and CLAUDE.md at the project root and applies them as rules. Nested AGENTS.md files apply when the agent edits files in those subfolders.

**Why does agent -p not change my files?** In print mode, file changes are only proposed unless you add --force (or its alias --yolo). Use agent -p --force in scripts that should write files, and keep it to repos and machines where you are fine with that.

**Does the Cursor editor need to be installed or open?** No. Cursor CLI is a separate install and runs on its own in any terminal on macOS, Linux, WSL or Windows. It shares your account, rules and MCP settings with the editor, but it does not need the editor running.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/