Getting started

Introduction

Cursor CLI is Cursor's coding agent for the terminal, installed as agent. This reference covers the TUI, print mode, and cli-config.json.

Install

macOS, Linux, and WSL

curl https://cursor.com/install -fsS | bash  # macOS, Linux, WSL
agent --version                              # verify the install
agent update                                 # upgrade in place

Windows

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

On macOS, Linux, and WSL the installer symlinks agent into ~/.local/bin; add it to PATH if it is missing.

See: Installation

Sign in

agent           # first run opens a browser login
agent login     # sign in again
agent status    # show account and endpoint
agent logout    # clear stored credentials

For scripts, export CURSOR_API_KEY or pass --api-key. NO_OPEN_BROWSER=1 agent login prints the URL instead of opening it.

See: Authentication

Sessions

agent                     # start the interactive TUI
agent "explain this repo" # start with a prompt
agent ls                  # list recent chats, resume one
agent resume              # resume the latest chat
agent --continue          # alias for --resume=-1
agent --resume <chat-id>  # resume a specific chat

agent create-chat makes an empty chat and prints its ID; pass it to --resume.

See: Parameters

CLI reference

Commands

Chats

CommandDescription
agent [prompt]Start the interactive agent
agent lsPick a previous chat to resume
agent resumeResume the latest chat
agent create-chatCreate an empty chat, print its ID

Setup

CommandDescription
agent loginSign in with a browser
agent logoutClear stored credentials
agent statusShow auth status (whoami)
agent aboutVersion, system, and account info
agent modelsList models for this account
agent updateUpdate to the latest build
agent generate-ruleGenerate a .cursor/rules file

Integrations

CommandDescription
agent mcpManage MCP servers
agent sandboxConfigure the sandbox, or run in it
agent acpRun as an ACP server over stdio
agent workerRun a private Cloud Agent worker
agent install-shell-integrationAdd shell integration to ~/.zshrc

See: Parameters

Flags

FlagDescription
-p, --printRun non-interactively
--output-format <fmt>text, json, or stream-json
--stream-partial-outputStream text deltas
--model <model>Choose the model
--list-modelsList available models
--mode <mode>plan or ask
--planStart in Plan mode
--resume [chatId]Resume a chat
--continueResume the previous chat
-f, --forceRun what is not explicitly denied
--sandbox <mode>enabled or disabled
--workspace <path>Workspace directory to use
-w, --worktree [name]Run in a new Git worktree

See: Parameters

Other flags

FlagDescription
--api-key <key>API key instead of a stored login
-H, --header <header>Add a request header, repeatable
--approve-mcpsApprove every MCP server
--trustTrust the workspace without prompting
--worktree-base <ref>Base ref for the new worktree
--skip-worktree-setupSkip .cursor/worktrees.json setup
--plugin-dir <path>Load a local plugin directory
--yoloAlias for --force
-v, --versionPrint the version
-h, --helpShow help for a command

See: Parameters

agent -p "find and fix performance issues"
agent -p --model gpt-5 "review this diff for bugs"
agent -p --output-format json "list the TODOs" | jq .result
agent -p --force "upgrade the test runner"

Print mode follows session approval rules but cannot ask: allowlisted edits run, the rest is rejected.

Add --force to run what it would reject; outside-workspace writes stay blocked.

See: Using headless CLI

Output formats

agent -p --output-format json "explain src/auth.ts"
agent -p --output-format stream-json "fix the tests"

Formats

FormatOutput
textOnly the final message (default)
jsonOne object with result and session_id
stream-jsonNewline-delimited events

stream-json emits system, user, assistant, tool_call, and result events.

Add --stream-partial-output for text deltas; skip assistant events carrying model_call_id.

See: Output format

Slash commands

Chat

CommandDescription
/newStart a fresh chat
/resumePick a recent chat to resume
/forkFork the current chat
/rename <name>Rename the chat
/rewindJump back to an earlier message
/summarizeSummarize to free up context

/new also answers to /clear, /new-chat, and /newchat; /summarize to /compress.

See: Slash commands

Control

CommandDescription
/plan [prompt]Switch to Plan mode
/askToggle Ask mode
/debug [prompt]Toggle Debug mode
/goal [objective]Set a durable objective
/model [filter]Choose a model
/max-modeToggle Max Mode
/run-everythingToggle Run Everything
/sandboxConfigure sandbox and network
/configEdit CLI settings
/vimToggle Vim keys

/auto-run aliases /run-everything. /goal keeps the objective across idle runs.

See: Slash commands

Inspect

CommandDescription
/mcpManage servers, list their tools
/pluginManage plugins and marketplaces
/logsShow the debug log path
/copyCopy a previous message
/copy-request-idCopy the last request ID
/copy-conversation-idCopy the conversation ID
/help [command]Show help

See: Slash commands

Interface

CommandDescription
/setup-terminalFix newline keybindings
/line-numbersToggle line numbers
/show-thinkingToggle thinking blocks
/status-indicatorsToggle terminal title status
/openOpen the repo root in Cursor

See: Slash commands

Account

CommandDescription
/aboutVersion, system, and account info
/feedback <message>Send feedback to the team
/logoutSign out
/quitExit (also /exit)

See: Slash commands

Interactive mode

Modes

ModeHow to enter
AgentDefault
PlanShift+Tab, /plan, --plan
Ask/ask, --mode=ask

Plan mode designs before editing and asks clarifying questions; Ask mode reads without changing files.

See: Modes

Keyboard shortcuts

ShortcutAction
Shift+TabRotate Agent, Plan, Ask
Shift+EnterNewline (iTerm2, Ghostty, Kitty, Warp)
Ctrl+JNewline in any terminal
\+EnterNewline in any terminal
Ctrl+RReview the turn's changes
ArrowUpRecall earlier messages
Ctrl+OExpand truncated output
EnterSteer a running turn
EscLeave shell mode
Ctrl+DExit (press twice)

Shift+Enter needs a terminal that reports the modifier; tmux and SSH sessions fall back to Ctrl+J. /setup-terminal configures Option+Enter.

See: Terminal setup

Input modes

InputEffect
@Attach files and folders
/Run a slash command
&Hand the prompt to a Cloud Agent

Pick a skill from / and press Enter to attach it once, or Option+Enter to keep it as a custom mode.

See: Using Agent in CLI

Shell mode

/shell                        # enter shell mode
cd packages/web && npm test   # chain cd, it does not persist

Commands run in your login shell for up to 30 seconds. Servers and interactive prompts are not supported; Ctrl+O expands output and Esc exits.

See: Shell mode

Reviewing changes

KeyAction
Ctrl+ROpen the review
iAdd follow-up instructions
← →Switch files
↑ ↓Scroll

See: Using Agent in CLI

Model selection

Choosing a model

agent --list-models               # what this account can use
agent models                      # same, as a subcommand
/model                            # picker; Tab edits parameters
/model auto                       # let Cursor route
agent --model gpt-5 "fix tests"   # pin one for a run

Fresh installs start on Auto. Team restrictions shrink the list; a blocked --model exits with a restriction message.

See: Configuration

Shortcuts

CommandEffect
/opusJump to the Claude family
/composerJump to Composer
/fastToggle Fast when supported
/max-modeToggle Max Mode

Each family shortcut remembers your last pick. Turn them off under Model slash commands in /config.

See: Changelog

Approvals and sandbox

Run modes

ModeRuns without asking
allowlistAllowlisted calls, sandboxed shell
auto-reviewAllowlisted calls, then a classifier
unrestrictedEvery tool call

Auto-review sandboxes shell commands and sends the rest to a classifier. Set the mode with approvalMode or /run-everything; --force (or --yolo) runs everything permissions.deny and team policy allow.

See: Run modes

Permission tokens

TokenControls
Shell(git)Any git subcommand
Shell(curl:*)curl with any arguments
Read(src/**/*.ts)Files matching a glob
Write(package.json)Writes to a path or glob
WebFetch(docs.github.com)Fetches from a domain
Mcp(datadog:*)Tools on an MCP server

Shell matches the first word of a command, Read and Write take globs, WebFetch takes a domain, and Mcp takes server:tool.

See: Permissions

Allow and deny

{
  "permissions": {
    "allow": ["Shell(git)", "Read(src/**/*.ts)"],
    "deny": ["Shell(rm)", "Read(.env*)"]
  }
}

Deny rules win over allow rules, and relative paths are scoped to the workspace. Approval prompts add entries with Tab.

See: Permissions

Sandbox

agent --sandbox disabled        # use allowlist mode instead
agent sandbox enable            # keep it on for every run
agent sandbox run ls --network  # one command, network allowed

/sandbox sets the mode and network access; settings persist. The sandbox allows workspace writes and limits network to sandbox.json plus Cursor defaults.

See: Sandboxing

Sandbox limits

.git/hooks and other protected paths stay off limits. On Linux, Landlock (kernel 6.2+) and unprivileged user namespaces are required; without them the CLI asks for approval.

See: Sandboxing

Configuration

Config files

Paths

~/.cursor/cli-config.json           # global, every project
.cursor/cli.json                    # project, permissions only
$CURSOR_CONFIG_DIR/cli-config.json  # custom directory

Example

{
  "version": 1,
  "editor": { "vimMode": false },
  "permissions": { "allow": ["Shell(git)"], "deny": ["Shell(rm)"] }
}

version, editor.vimMode, and permissions.allow/deny are required. The CLI repairs missing fields and backs up broken files as .bad. Project files set only permissions.

See: Configuration

Rules and AGENTS.md

Files

.cursor/rules/*.mdc   # project rules; .md is ignored
AGENTS.md             # root instructions, committed
CLAUDE.md             # also read at the root

Frontmatter

---
description: Component conventions for the web app
globs: src/components/**/*.tsx
alwaysApply: false
---

alwaysApply runs a rule every session, globs scopes it to matching files, and description lets the agent pull it in. Without either, only @-mention loads it.

See: Rules

MCP servers

agent mcp list
agent mcp list-tools datadog
agent mcp login datadog
agent mcp disable datadog

Servers live in .cursor/mcp.json or ~/.cursor/mcp.json. --approve-mcps skips the approval prompt, and ACP sessions ignore team-level servers.

See: MCP

Worktrees

agent -w "upgrade the test runner"
agent -w auth-fix "fix the flaky auth test"
agent --workspace ~/src/app -w "fix the tests"

Worktrees live under ~/.cursor/worktrees/<repo>/<name>. --worktree-base picks the base ref; .cursor/worktrees.json setup runs once the workspace is trusted.

See: Worktrees

Environment variables

VariablePurpose
CURSOR_API_KEYAPI key for scripts and CI
CURSOR_AUTH_TOKENToken for ACP clients
CURSOR_CONFIG_DIRMove cli-config.json
XDG_CONFIG_HOMELinux config root
NO_OPEN_BROWSERPrint the login URL instead
HTTP_PROXYProxy for agent traffic
HTTPS_PROXYProxy for TLS traffic
NODE_EXTRA_CA_CERTSTrust a TLS-inspecting proxy CA
COLORFGBGForce the dark or light theme

CURSOR_CONFIG_DIR wins over XDG_CONFIG_HOME. Set COLORFGBG="15;0" for a dark theme or "0;15" for a light one.

See: Configuration

Common workflows

Scripting and CI

agent -p "review this diff for bugs"
agent -p --force "fix the failing tests"
agent -p --output-format json "list the TODOs" | jq .result

A failed run exits non-zero and writes the error to stderr; json emits no object in that case, so check the exit code before parsing.

See: Headless CLI

GitHub Actions

- name: Install Cursor CLI
  run: |
    curl https://cursor.com/install -fsS | bash
    echo "$HOME/.local/bin" >> $GITHUB_PATH

- name: Run the agent
  env:
    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
  run: agent -p --force "fix the failing tests"

Store the key with gh secret set CURSOR_API_KEY. For CI, encode restrictions in permissions.allow/deny instead of relying on prompts.

See: GitHub Actions

Cloud handoff

& refactor the auth module and add tests

Prefix a message with & to hand it to a Cloud Agent; pick it up later at cursor.com/agents.

See: Cloud Agent

Also see

0 Comments for this cheatsheet. Write yours!