Cursor CLI: install the agent command and run it in scripts

The Cursor CLI is Cursor’s agent in the terminal: you install it with one command, sign in, and run agent interactively or with -p in scripts and CI, according to Cursor’s CLI docs.

Applies to: Cursor CLI (agent command), per Cursor’s CLI documentation. Last checked: October 28, 2026.

On this page

Install the Cursor CLI

Cursor’s installation page gives one command per platform.

macOS, Linux and Windows (WSL):

curl https://cursor.com/install -fsS | bash

Windows (native), in PowerShell:

irm 'https://cursor.com/install?win32=true' | iex

Check the install:

agent --version

The same page says to add ~/.local/bin to your PATH after installing. For bash:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

For zsh:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Cursor says the CLI tries to auto-update by default; to update by hand, run agent update (installation).

Sign in

Cursor recommends the browser flow (authentication):

# Log in using browser flow
agent login

# Check authentication status
agent status

# Log out and clear stored authentication
agent logout

If the browser doesn’t open, the docs say to run NO_OPEN_BROWSER=1 agent login and open the printed URL yourself.

For scripts and CI, Cursor documents a user API key generated in the Cursor Dashboard under API Keys, passed as an environment variable (the recommended option) or with --api-key:

export CURSOR_API_KEY=your_api_key_here
agent "implement user authentication"

Run the agent interactively

Start a session, with or without a first prompt (overview):

# Start interactive session
agent

# Start with initial prompt
agent "refactor the auth module to use JWT tokens"

The CLI has the same modes as the editor (using Agent in CLI):

Before running terminal commands, the CLI asks you to approve (y) or reject (n) them (using Agent in CLI). Ctrl+R opens a review of changes, and @ adds files and folders to context.

To work in a separate Git worktree instead of your current checkout, pass -w or --worktree; Cursor creates these under ~/.cursor/worktrees/:

# Create a temporary worktree from the current repository with a generated name
agent --worktree "upgrade the test runner and fix any broken snapshots"

Resume sessions and hand off to the cloud

From the overview:

# Open previous chats and resume one
agent ls

# Resume latest conversation
agent resume

# Continue the previous session
agent --continue

# Resume specific conversation
agent --resume="chat-id-here"

Prepending & to a message sends the conversation to a Cloud Agent, which you can pick up on web or mobile at cursor.com/agents.

Rules, AGENTS.md and MCP

The CLI uses the same rules system as the editor: rules in .cursor/rules load automatically, and the CLI also reads AGENTS.md and CLAUDE.md at the project root and applies them as rules (using Agent in CLI). For how those files are written, see the Cursor rules and AGENTS.md guide.

MCP servers configured in mcp.json work in both the editor and the CLI. The CLI MCP page lists the management commands:

agent mcp list
agent mcp list-tools <identifier>
agent mcp login <identifier>
agent mcp enable <identifier>
agent mcp disable <identifier>

For servers that document a Cursor setup, see best MCP servers for Cursor.

Use the CLI in scripts and CI

Print mode (-p, --print) runs the agent without the interactive interface (headless CLI). By default it prints text; --output-format json gives structured output and --output-format stream-json gives message-level progress.

agent -p "What does this codebase do?"

Cursor’s headless page says that without --force, changes in print mode are only proposed, not applied, and that “The --force flag allows the agent to make direct file changes without confirmation”:

# Enable file modifications in print mode
agent -p --force "Refactor this code to use modern ES6+ syntax"

# Without --force, changes are only proposed, not applied
agent -p "Add JSDoc comments to this file"  # Won't modify files

Treat --force (also --yolo) as an opt-in for a specific job, not a default. The documented way to narrow what runs without prompts is a permissions list.

Limit what the agent may do

Permissions live in ~/.cursor/cli-config.json (global) or .cursor/cli.json in the project (permissions reference). Tokens cover shell commands (Shell(git)), reads (Read(src/**/*.ts)), writes (Write(package.json)), web fetches (WebFetch(docs.github.com)) and MCP tools (Mcp(datadog:*)), and deny rules take precedence over allow rules. This is Cursor’s example:

{
  "permissions": {
    "allow": [
      "Shell(ls)",
      "Shell(git)",
      "Read(src/**/*.ts)",
      "Write(package.json)",
      "WebFetch(docs.github.com)",
      "WebFetch(*.github.com)",
      "Mcp(datadog:*)"
    ],
    "deny": [
      "Shell(rm)",
      "Read(.env*)",
      "Write(**/*.key)",
      "WebFetch(malicious-site.com)"
    ]
  }
}

The CLI also has sandbox controls: /sandbox or --sandbox with enabled or disabled toggles sandbox mode and network access, and the setting persists across sessions (overview). For editor-side guardrails, see Cursor hooks; for what each plan includes, see Cursor AI pricing.