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

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 compares the two. This post assumes you have picked Cursor and want to use it from the terminal.

Step 1: install Cursor CLI

Check the install:

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

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:

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

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

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:

# 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

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.

# 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.

Step 7: MCP servers

MCP servers 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.

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.

{
  "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.

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 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 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 grid next to other agents, with automatic code review when a turn ends. Under Settings → Accounts you can add several Cursor accounts as a fallback order, and a Cursor agent can also run on a saved SSH server.

To try it, 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.