CLI reference - 327 items
Cursor CLI reference
Cursor CLI documents 53 slash commands, 73 CLI flags, 42 subcommands, 54 keyboard shortcuts, 46 settings keys, 36 environment variables and 23 config files. This page lists all 327 with what each one does, the values it accepts and a working example where the docs give one.
Last verified 19 official pagesRun as cursor-agent
Slash commands53
Own page: Cursor CLI slash commands| Command | Description | Example |
|---|---|---|
/model [filter] | Selects a model; press Tab to edit. Typing a filter such as /model sonnet opens the picker pre-filtered. optional filter Docs: /model [filter] | /model auto
/model gpt-5
/model sonnet-4-thinking |
/run-everything [on|off|status] | Toggles Run Everything or shows its status. /auto-run is an alias. on | off | status Docs: /run-everything [on|off|status] | -no example |
/plan [prompt] | Switches to Plan mode, shows the current plan, or submits a prompt in Plan mode. optional prompt Docs: /plan [prompt] | -no example |
/ask | Toggles Ask mode for read-only questions. Docs: /ask | -no example |
/debug [prompt] | Toggles Debug mode or submits a prompt in Debug mode. optional prompt Docs: /debug [prompt] | -no example |
/goal [objective] | Gives the agent a long-lived objective to work towards until it is fully complete. Rolling out; tracks an active or paused status line and pauses on Ctrl+C. objective Docs: /goal [objective] | -no example |
/logs | Shows the debug log path and copies it to the clipboard. Docs: /logs | -no example |
/update | Updates Cursor Agent to the latest version from inside the session. Docs: /update | -no example |
/max-mode | Toggles Max Mode on legacy request-based plans. Docs: /max-mode | -no example |
/rename <name> | Renames the current chat session. name Docs: /rename <name> | -no example |
/clear | Starts a new chat session. /new, /new-chat, and /newchat are aliases. Docs: /clear | -no example |
/resume | Opens recent chats and resumes one. Also bound to Ctrl+Y per the changelog. Docs: /resume | -no example |
/fork | Forks the current chat into a new session. The changelog lists /branch and /duplicate as aliases. Docs: /fork | -no example |
/summarize | Summarizes the conversation to reduce context. /compress is an alias; the changelog also lists /compact. Docs: /summarize | -no example |
/rewind | Jumps back to a previous message, restoring files and conversation state from an interactive timeline. On by default since June 2026; /undo and /restore are aliases per the changelog. Docs: /rewind | -no example |
/vim | Toggles Vim keys for the current session and saves the preference. Docs: /vim | /vim |
/line-numbers | Toggles line numbers in code blocks. Docs: /line-numbers | -no example |
/show-thinking | Toggles thinking block display. Docs: /show-thinking | -no example |
/status-indicators | Toggles terminal title status indicators. Docs: /status-indicators | -no example |
/shell [command] | Enters Shell Mode, which runs quick non-interactive shell commands with a 30 second timeout. /sh and /run are aliases. optional command Docs: /shell [command] | -no example |
/about | Shows CLI version, system, and account info, and copies it to the clipboard. Docs: /about | -no example |
/setup-terminal | Configures terminal newline keybindings; detects your terminal and gives instructions for Option+Enter / Alt+Enter as a newline alternative. Docs: /setup-terminal | /setup-terminal |
/help [command] | Shows help. Use /help <command> for command details. optional command Docs: /help [command] | -no example |
/feedback <message> | Shares feedback with the team. message Docs: /feedback <message> | -no example |
/open | Opens the repository's Git root in Cursor. /cursor is an alias. Docs: /open | -no example |
/copy-request-id | Copies the last request ID to the clipboard. Docs: /copy-request-id | -no example |
/copy-conversation-id | Copies the current conversation ID to the clipboard. Docs: /copy-conversation-id | -no example |
/logout | Signs out from Cursor. Docs: /logout | -no example |
/quit | Exits the CLI. Docs: /quit | -no example |
/exit | Exits the CLI. Docs: /exit | -no example |
/mcp [list|list-tools] [identifier] | Manages MCP servers and lists tools for a server. Opens a per-server detail view with tool schemas, login, logout, enable, and disable; servers are grouped under User / Project / Team. list | list-tools; optional identifier Docs: /mcp [list|list-tools] [identifier] | -no example |
/plugin [subcommand] | Manages plugins and marketplaces, including install or uninstall at user or project scope and /plugin marketplace add to add a marketplace by git URL. optional subcommand Docs: /plugin [subcommand] | -no example |
/config | Configures CLI settings interactively, replacing hand-editing JSON, including a version and account page. Docs: /config | -no example |
/copy | Copies a previous user message to the clipboard; can also copy individual steps of agent replies. Docs: /copy | -no example |
/sandbox | Configures sandbox mode and network access settings through an interactive menu. Settings persist across sessions. Docs: /sandbox | -no example |
/bedrock [subcommand] | Configures Bedrock when the Bedrock feature is enabled. optional subcommand Docs: /bedrock [subcommand] | -no example |
/auto-review | Turns on the Auto-review run mode, which checks shell, MCP, and Fetch calls via allowlist, sandbox, then classifier. Docs: /auto-review | -no example |
/add-dir | Adds a directory to the workspace mid-session and refreshes slash skills and custom commands immediately. path Docs: /add-dir | -no example |
/save-workspace | Saves the current set of workspace directories as a named multi-directory workspace. Docs: /save-workspace | -no example |
/load-workspace | Reloads a saved named multi-directory workspace. Docs: /load-workspace | -no example |
/usage | Shows included-usage meters with Auto and API breakdowns, on-demand spend against your limit, plan name, and billing-cycle reset date. Docs: /usage | -no example |
/fast | Toggles Fast when the current model supports it. Docs: /fast | -no example |
/opus | Model family shortcut that jumps straight to a model without the picker; each family shortcut remembers your last choice. Shortcuts can be disabled under Model slash commands in /config. Docs: /opus | -no example |
/composer | Model family shortcut that jumps straight to a Composer model without the picker, remembering your last choice in that family. Docs: /composer | -no example |
/btw | Asks a quick read-only side question mid-turn; the answer streams into a dismissible overlay and never touches conversation history. Docs: /btw | -no example |
/context | Visualizes what is consuming the context window, broken down by category. Docs: /context | -no example |
/changes | Unified review UI (also Ctrl+R) with a Session tab showing only this session's edits. Docs: /changes | -no example |
/skills | Browses skills; flags skills that exceed Agent Skills limits with a yellow warning count. Docs: /skills | -no example |
/skill-name | Inline invocation of a skill by name; works in interactive and -p print mode. Pressing Enter attaches the skill to one message, Option+Enter invokes it as a sticky Custom Mode. Docs: /skill-name | -no example |
/rules | Interactive rules browser with inline editing. Docs: /rules | -no example |
/commands | Interactive custom commands browser with inline editing. Docs: /commands | -no example |
/detach | Detaches from a persistent session started with agent persist. Docs: /detach | -no example |
/full-conversation | Opts out of rendering only recent turns on full repaints. Docs: /full-conversation | -no example |
CLI flags73
Own page: Cursor CLI CLI flags| Flag | Description | Example |
|---|---|---|
-v, --version | Global option that outputs the version number. The install docs use it to verify that Cursor CLI is working. Docs: -v, --version | agent --version |
--api-key <key> | API key for authentication. The CURSOR_API_KEY environment variable can be used instead. string Docs: --api-key <key> | agent --api-key your_api_key_here "implement user authentication" |
-H, --header <header> | Adds a custom header to agent requests. Can be used multiple times (repeatable curl-style since February 2026). format | -no example |
-p, --print | Prints responses to the console for scripts or non-interactive use. Has access to all tools, including write and shell. boolean flag Docs: -p, --print | agent -p "find and fix performance issues" --model "gpt-5" |
--output-format <format> | Output format, only valid with --print or when print mode is inferred (non-TTY stdout or piped stdin). json emits a single result object; stream-json emits NDJSON events; text emits only the final assistant message. text | json | stream-json (default: text) Docs: --output-format <format> | agent -p "review these changes for security issues" --output-format text |
--stream-partial-output | Streams partial output as individual text deltas. Only works with --print and the stream-json output format. boolean flag Docs: --stream-partial-output | agent -p --force --output-format stream-json --stream-partial-output \
"Analyze this project structure and create a summary report in analysis.txt" |
--resume [chatId] | Resumes a chat session, loading prior context. Since July 2026 it opens All chats across workspaces by default. optional chat ID Docs: --resume [chatId] | agent --resume="chat-id-here" |
--continue | Continues the previous session. Alias for --resume=-1. boolean flag Docs: --continue | agent --continue |
--model <model> | Model to use. Passing a model blocked by a team admin restriction exits with the restriction message. model ID string Docs: --model <model> | agent -p "Your prompt here" --model gpt-5 |
--mode <mode> | Sets the agent mode. Agent is the default when no mode is specified. plan | ask Docs: --mode <mode> | --mode=ask |
--plan | Starts in Plan mode. Shorthand for --mode=plan. boolean flag Docs: --plan | -no example |
--list-models | Lists all available models. boolean flag Docs: --list-models | -no example |
-f, --force | Force allows commands unless explicitly denied. Combined with --print it lets the agent make direct file changes without confirmation. boolean flag Docs: -f, --force | agent -p --force "Refactor this code to use modern ES6+ syntax" |
--yolo | Alias for --force. Described in the changelog as fully autonomous runs that auto-approve consistently across trust, MCP, and command approvals. boolean flag Docs: --yolo | -no example |
--sandbox <mode> | Sets sandbox mode for command execution. Settings persist across sessions. enabled | disabled Docs: --sandbox <mode> | -no example |
--approve-mcps | Automatically approves all MCP servers, skipping approval prompts. boolean flag Docs: --approve-mcps | agent --approve-mcps "query my database for recent errors" |
--trust | Trusts the workspace without prompting. The parameters page lists it as headless mode only; the v2026.07.20 changelog says it now also works in interactive sessions, skipping the trust dialog. boolean flag Docs: --trust | -no example |
--workspace <path> | Workspace directory to use. Without it the CLI uses the current working directory. path Docs: --workspace <path> | agent --workspace ~/src/my-app --worktree auth-fix "fix the flaky auth test and open a PR" |
--plugin-dir <path> | Loads a local plugin directory. Can be specified multiple times. path; repeatable Docs: --plugin-dir <path> | -no example |
-w, --worktree [name] | Runs in a new Git worktree under ~/.cursor/worktrees/<reponame>/<name> instead of editing the current checkout. If the name is omitted, one is generated. optional name Docs: -w, --worktree [name] | agent --worktree "upgrade the test runner and fix any broken snapshots" |
--worktree-base <branch> | Branch or ref to base the new worktree on. branch or ref (default: current HEAD) Docs: --worktree-base <branch> | -no example |
--skip-worktree-setup | Skips running worktree setup scripts from .cursor/worktrees.json. boolean flag Docs: --skip-worktree-setup | -no example |
-h, --help | Displays help for a command. All commands support it for command-specific help. Docs: -h, --help | -no example |
--auth-token | Existing CLI auth path that can pre-authenticate before startup, alternatively via CURSOR_AUTH_TOKEN. On workers it is a pre-minted access token used by the Kubernetes operator and other automation. token string Docs: --auth-token | -no example |
-e, --endpoint <url> | API endpoint option that can be passed from the root CLI command, including before acp. The worker CLI reference lists the default endpoint. URL (default: https://api2.cursor.sh) Docs: -e, --endpoint <url> | agent -e https://api2.cursor.sh acp |
-k | Shown in the ACP docs as a TLS option that can be passed from the root CLI command. Docs: -k | agent -k acp |
--add-dir <path> | Adds directories at launch to start a multi-root session. Repeatable, and usable together with --workspace. path; repeatable Docs: --add-dir <path> | -no example |
--auto-review | Turns on the Auto-review run mode, which runs allowlisted calls, sandboxes what it can, and sends the rest to a classifier. Also available via /config or /auto-review. boolean flag Docs: --auto-review | -no example |
--image | Attaches images. Since March 2026 it works in any session, not just print mode. Docs: --image | -no example |
--disable-auto-update | Turns background auto-updates off. boolean flag Docs: --disable-auto-update | -no example |
--format <format> | Command-specific output format option for status, whoami, and about. text | json (default: text) Docs: --format <format> | -no example |
--allow-paths <paths> | sandbox run option: comma-separated list of extra read/write paths. comma-separated paths Docs: --allow-paths <paths> | -no example |
--readonly-paths <paths> | sandbox run option: comma-separated list of extra read-only paths. comma-separated paths Docs: --readonly-paths <paths> | -no example |
--blocked-patterns <patterns> | sandbox run option: comma-separated list of gitignore-style patterns to block. comma-separated patterns Docs: --blocked-patterns <patterns> | -no example |
--sandbox (sandbox run) | sandbox run option: runs with the workspace read/write sandbox policy. boolean (default: true) Docs: --sandbox (sandbox run) | -no example |
--network | sandbox run option: enables network access in the sandbox. boolean (default: false) Docs: --network | -no example |
--sb-debug | sandbox run option: writes sandbox debug logs to a temp folder and prints the path. boolean flag Docs: --sb-debug | -no example |
--auth-token-file <path> | worker option: path to a file containing the worker auth token, such as a session token. The CLI re-reads the file when reconnecting after an auth failure or disconnect. path Docs: --auth-token-file <path> | -no example |
--worker-dir <path> | worker option: workspace root to expose to agents. Repeatable (up to 20 paths per the pool docs); the first value is the assignment identity. path; repeatable (default: current directory) Docs: --worker-dir <path> | -no example |
--management-addr <address> | worker option: listen address for the /healthz, /readyz, and /metrics endpoints. address, for example :8080 Docs: --management-addr <address> | -no example |
--label <key=value> | worker option: adds a worker label. Can be used multiple times; cannot be combined with --labels-file. key=value; repeatable Docs: --label <key=value> | -no example |
--labels-file <path> | worker option: path to a JSON or TOML labels file. Can also be set with CURSOR_WORKER_LABELS_FILE. path Docs: --labels-file <path> | -no example |
--idle-release-timeout <seconds> | worker option: seconds the worker may stay connected after becoming idle; 0 disables idle-based release. The parameters page lists default 0, while the Team Pools CLI reference lists default 3600 (env CURSOR_WORKER_IDLE_RELEASE_TIMEOUT). seconds; default documented as 0 (parameters page) and 3600 (pool page) Docs: --idle-release-timeout <seconds> | agent worker --pool my-pool --idle-release-timeout 600 start |
--pool [name] | worker option: registers for pool assignment; one cloud agent claims the worker at a time. Optional pool name, defaulting to default (env CURSOR_WORKER_POOL_NAME). optional name (default: default) Docs: --pool [name] | agent worker --pool start |
--single-use | worker option: legacy alias for --pool. Docs: --single-use | -no example |
--pool-name <name> | worker option: pool label for pool workers; requires --pool or --single-use. The pool docs mark it as a deprecated alias for --pool <name>. string (default: default) Docs: --pool-name <name> | -no example |
--name <name> | worker option: custom display name for the worker. string (default: machine hostname) Docs: --name <name> | -no example |
--data-dir <path> | worker option: base directory for logs, artifacts, and recording data. path Docs: --data-dir <path> | -no example |
--debug | worker option: prints worker debug diagnostics before starting bridge mode. boolean flag Docs: --debug | -no example |
--computer-use | worker option: lets agents drive this machine's desktop. On macOS it installs the Cursor Computer Use helper app if needed. boolean flag Docs: --computer-use | agent worker --computer-use start |
--display <display> | worker option, Linux only: existing X11 display to require for --computer-use. When omitted, a reachable DISPLAY is reused or a managed desktop is started. X11 display, for example :0 Docs: --display <display> | -no example |
--share-desktop [mode] | worker option, Linux only: lets authorized viewers watch or control the agent desktop. Separate from computer use. view | view_and_control (default view_and_control per pool docs) Docs: --share-desktop [mode] | -no example |
--verbose | worker start option: enables verbose startup logs. boolean flag Docs: --verbose | -no example |
--json | worker debug option: outputs the debug report as JSON. boolean flag Docs: --json | -no example |
--api-key <key> (worker) | Service account API key for pool workers. Env var CURSOR_API_KEY. string Docs: --api-key <key> (worker) | agent worker --api-key "your-service-account-api-key" start |
--clone-git-repos | On claim, checks out the agent's GitHub repos in the workspace, reusing clean checkouts and cloning the rest. Any-repo named pools only; implies --mint-github-token and requires git on PATH. boolean (default: off) Docs: --clone-git-repos | -no example |
--mint-github-token | Receives short-lived GitHub tokens during claimed runs. Pool workers only; requires team-admin enablement. boolean flag Docs: --mint-github-token | -no example |
--sync-dashboard-secrets | Receives team and user Cloud Agent secrets for the run's repositories, plus API envVars, as environment variables during claimed runs. Pool workers only; requires team-admin enablement (Secret sync). boolean flag Docs: --sync-dashboard-secrets | -no example |
--on-session-start <command> | Runs a sessionStart command after each claim, in addition to hooks from .cursor/hooks.json. Pool workers only. command Docs: --on-session-start <command> | -no example |
--on-session-end <command> | Runs a sessionEnd command before each claim is torn down. Pool workers only. command Docs: --on-session-end <command> | -no example |
--identity-socket | Serves a per-claim OIDC token socket to claimed agents and sets CURSOR_AGENT_SOCKET to its path in their shells. boolean (default: off) Docs: --identity-socket | -no example |
--worker-id <id> | Stable worker id used with claim. The docs prefer the CURSOR_AGENT_WORKER_ID env var so older CLI builds ignore an unknown flag. string Docs: --worker-id <id> | agent worker --pool "$CURSOR_POOL" --worker-id "$CURSOR_AGENT_WORKER_ID" start |
--spawn <path> | worker controller option: script to run once after a successful claim, or once per missing warm worker. Required. path Docs: --spawn <path> | agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool my-pool --pool default |
--api-key <key> (worker controller) | worker controller option: service account API key, also readable from CURSOR_API_KEY. Session login is not used. string Docs: --api-key <key> (worker controller) | -no example |
--pool <name> (worker controller) | worker controller option: pool to watch. Repeatable and mutually exclusive with --all-pools; warm mode requires --pool. name; repeatable Docs: --pool <name> (worker controller) | -no example |
--all-pools | worker controller option: uses the team-wide pending-requests list and stream. Does not register pools; not allowed in warm mode. boolean flag Docs: --all-pools | -no example |
--warm-idle <count> | worker controller option: keeps count idle workers per --pool and skips claiming. Reconciles against the pools endpoint every 60 seconds. integer count Docs: --warm-idle <count> | agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool my-pool --warm-idle 5 |
--session-token | worker controller option, claim mode only: gives the spawn hook a session token for its claim instead of the API key. Cannot be combined with --warm-idle. boolean flag Docs: --session-token | agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool my-pool --session-token |
--identity-audience <aud> | worker controller option, claim mode only: requests a signed identity token with this audience on every claim and gives it to the spawn hook. Cannot be combined with --warm-idle. audience string Docs: --identity-audience <aud> | -no example |
--repository <url> | worker controller option: filters pending requests by repository. Required for repo-scoped keys; in warm mode it also pins the pool idle-count to that repo's row. URL Docs: --repository <url> | -no example |
--endpoint <url> (worker controller) | worker controller option: public API base, also readable from CURSOR_API_ENDPOINT. URL (default: https://api.cursor.com) Docs: --endpoint <url> (worker controller) | -no example |
--git-ref | Option for agent plugin marketplace add that pins a branch, tag, or commit of the marketplace repository. branch, tag, or commit Docs: --git-ref | -no example |
--resume (agent persist) | Used with agent persist to continue an existing chat in a persistent session. Docs: --resume (agent persist) | -no example |
Subcommands42
Own page: Cursor CLI subcommands| Command | Description | Example |
|---|---|---|
agent [prompt...] | Starts in agent mode, the default. When no command is specified, Cursor Agent starts in interactive agent mode; an initial prompt can be passed as an argument. prompt: initial prompt for the agent Docs: agent [prompt...] | agent "refactor the auth module to use JWT tokens" |
login | Authenticates with Cursor using a browser flow and stores credentials locally. During login, pressing q reveals a QR code for the same login URL. Docs: login | agent login |
logout | Signs out and clears stored authentication. Docs: logout | agent logout |
status | whoami | Views authentication status: whether you are authenticated, account information, and current endpoint configuration. --format text|json Docs: status | whoami | agent status |
about | Displays version, system, and account info. --format text|json Docs: about | agent about |
models | Lists available models for this account, including team Bedrock models and respecting team model restrictions. Docs: models | agent models |
mcp | Manages MCP servers configured for Cursor Agent. MCP in the CLI uses the same configuration as the editor. login | list | list-tools | enable | disable Docs: mcp | agent mcp |
mcp login <identifier> | Authenticates with an MCP server configured in .cursor/mcp.json or ~/.cursor/mcp.json, with automatic callback handling. identifier Docs: mcp login <identifier> | agent mcp login <identifier> |
mcp list | Lists configured MCP servers and their status in an interactive menu showing names, connection status, configuration source, and transport. Docs: mcp list | agent mcp list |
mcp list-tools <identifier> | Lists available tools and their argument names for a specific MCP server. identifier Docs: mcp list-tools <identifier> | agent mcp list-tools playwright |
mcp enable <identifier> | Adds an MCP server to the local approved list. identifier Docs: mcp enable <identifier> | agent mcp enable <identifier> |
mcp disable <identifier> | Disables an MCP server so it will not load or prompt for approval. identifier Docs: mcp disable <identifier> | agent mcp disable <identifier> |
sandbox | Configures sandbox mode or runs one command in a sandbox. Hidden command. enable | disable | reset | run | help Docs: sandbox | agent sandbox enable |
sandbox enable | Enables sandbox mode for command execution. Docs: sandbox enable | agent sandbox enable |
sandbox disable | Disables sandbox mode and uses allowlist mode. Docs: sandbox disable | agent sandbox disable |
sandbox reset | Resets sandbox configuration to defaults. Docs: sandbox reset | agent sandbox reset |
sandbox run <cmd> [args...] | Runs a command in a sandbox with workspace read/write. --allow-paths, --readonly-paths, --blocked-patterns, --sandbox, --network, --sb-debug Docs: sandbox run <cmd> [args...] | agent sandbox run ls |
sandbox help [command] | Displays help for a sandbox command. Docs: sandbox help [command] | agent sandbox help |
worker | Starts a private cloud worker that connects to Cursor and runs agents in your environment. start | debug | controller | help Docs: worker | agent worker start |
worker start | Starts the worker and connects to Cursor. Waits for the bridge to connect before reporting ready. --verbose Docs: worker start | agent worker [options] start |
worker debug | Runs private worker preflight diagnostics for auth, privacy, and routing. --json Docs: worker debug | agent worker debug |
worker help [command] | Displays help for a worker command. Docs: worker help [command] | agent worker help |
worker controller | Starts workers from a --spawn hook, either claim-then-spawn (default) or as a warm pool with --warm-idle. Authenticates with a service account key. --spawn, --api-key, --pool, --all-pools, --warm-idle, --session-token, --identity-audience, --repository, --endpoint Docs: worker controller | agent worker controller --spawn ./spawn.sh --api-key "$CURSOR_API_KEY" --pool my-pool --pool default |
acp | Starts ACP (Agent Client Protocol) server mode over stdio with JSON-RPC 2.0, newline-delimited. Intended for custom clients and advanced integrations; hidden from default help output. Docs: acp | agent acp |
update | Updates Cursor Agent to the latest version. The CLI also tries to auto-update by default. Docs: update | agent update |
ls | Opens previous chats so you can resume one. Docs: ls | agent ls |
resume | Resumes the latest chat session. Docs: resume | agent resume |
create-chat | Creates a new empty chat and returns its ID. Docs: create-chat | agent create-chat |
generate-rule | rule | Generates a new Cursor rule with interactive prompts. Docs: generate-rule | rule | agent generate-rule |
install-shell-integration | Installs shell integration to ~/.zshrc. Docs: install-shell-integration | agent install-shell-integration |
uninstall-shell-integration | Removes shell integration from ~/.zshrc. Docs: uninstall-shell-integration | agent uninstall-shell-integration |
help [command] | Displays help for a command. Docs: help [command] | agent help [command] |
bedrock | Configures AWS Bedrock access with your own access keys or a team IAM role; works across interactive, headless, and editor sessions. Docs: bedrock | -no example |
persist | Starts a persistent session that keeps the agent running after you disconnect. Detach with /detach. attach | list | stop; --resume Docs: persist | -no example |
persist attach | Reconnects to a persistent session later. Docs: persist attach | -no example |
persist list | Lists persistent sessions (documented as agent persist list|stop for managing sessions). Docs: persist list | -no example |
persist stop | Stops a persistent session (documented as agent persist list|stop for managing sessions). Docs: persist stop | -no example |
env deploy | Deploys a Cloud Agent environment from an environment file. Files can include comments and trailing commas; invalid files fail with a syntax error pointing to where parsing stopped. environment file Docs: env deploy | -no example |
plugin marketplace add <git-url> | Registers a plugin marketplace from the shell without an interactive session. Pin a branch, tag, or commit with --git-ref. git URL; --git-ref Docs: plugin marketplace add <git-url> | -no example |
plugin marketplace list | Prints each marketplace's name, scope, and git URL. --format json for scripts Docs: plugin marketplace list | -no example |
plugin marketplace update | Re-indexes a marketplace from its repository. Docs: plugin marketplace update | -no example |
plugin marketplace remove | Deletes a user-scoped marketplace. Docs: plugin marketplace remove | -no example |
Keyboard shortcuts54
Own page: Cursor CLI keyboard shortcuts| Shortcut | Description | Example |
|---|---|---|
Shift+Tab | Rotates between modes (Agent, Plan, Ask). Docs: Shift+Tab | -no example |
Shift+Enter | Inserts a newline instead of submitting. Works natively in iTerm2, Ghostty, Kitty, Warp, and Zed; intercepted by tmux and screen. Docs: Shift+Enter | -no example |
Ctrl+D | Exits the CLI, following standard shell behavior and requiring a double-press. Docs: Ctrl+D | -no example |
Ctrl+J | Inserts a newline (ASCII line feed). Works in all terminals including tmux, screen, and SSH; the most reliable option. Docs: Ctrl+J | -no example |
\+Enter | Type a backslash, then press Enter to insert a newline. Works in all terminals. Docs: \+Enter | -no example |
Option+Enter / Alt+Enter | Newline alternative after /setup-terminal (Apple Terminal, Alacritty, VS Code); sends \x1b\r. In the / menu it also invokes a skill as a sticky Custom Mode. Docs: Option+Enter / Alt+Enter | map alt+enter send_text all \x1b\r |
ArrowUp | Cycles through previous messages; prompt history is per conversation. Docs: ArrowUp | -no example |
Ctrl+R | Reviews changes (the /changes review UI). Docs: Ctrl+R | -no example |
i (review) | In review, adds follow-up instructions. Docs: i (review) | -no example |
ArrowUp / ArrowDown (review) | Scrolls in the review view. Docs: ArrowUp / ArrowDown (review) | -no example |
ArrowLeft / ArrowRight (review) | Switches files in the review view. In the resume picker, Left/Right switch between All chats and This workspace. Docs: ArrowLeft / ArrowRight (review) | -no example |
o / O (review) | Opens diffs in your editor from the review UI. Docs: o / O (review) | -no example |
@ | Selects files and folders to include in context. Docs: @ | -no example |
& | Prepend to any message to push the conversation to a Cloud Agent. Docs: & | & refactor the auth module and add comprehensive tests |
y / n | Approves (y) or rejects (n) execution of a terminal command. Docs: y / n | -no example |
Tab (/model) | In the /model picker, press Tab to edit. Docs: Tab (/model) | -no example |
Tab (Shell Mode approval) | When prompted for permissions in Shell Mode, adds the command to the allowlist. Docs: Tab (Shell Mode approval) | -no example |
Ctrl+C | Cancels a hanging Shell Mode command and clears/exits Shell Mode; also pauses a /goal and cancels sudo prompts or cloud transfers. Docs: Ctrl+C | -no example |
Ctrl+O | Expands truncated output. Docs: Ctrl+O | -no example |
Esc / Backspace / Delete (empty input) | Exits Shell Mode when the input is empty. Docs: Esc / Backspace / Delete (empty input) | -no example |
Ctrl+L | Clears the screen and scrollback like a shell while keeping the session running. Docs: Ctrl+L | -no example |
Ctrl+V | Pastes a clipboard image. Docs: Ctrl+V | -no example |
Ctrl+G | Opens your prompt in $EDITOR and drops the result back into the prompt bar. Docs: Ctrl+G | -no example |
? | Opens the shortcut cheat sheet to discover input shortcuts. Docs: ? | -no example |
Ctrl+B (double press) | Sends a running shell to the background. Docs: Ctrl+B (double press) | -no example |
Ctrl+Y | Opens the /resume picker. Docs: Ctrl+Y | -no example |
q (login) | During agent login or first-run onboarding, reveals a QR code for the login URL to scan from a phone. Docs: q (login) | -no example |
Enter (while agent works) | Sends the queued message into the active run at a safe boundary to steer it; pressing Enter again interrupts the turn and sends the queued message immediately. Docs: Enter (while agent works) | -no example |
Enter (/ menu skill) | Picking a skill from the / menu and pressing Enter attaches it to one message. Docs: Enter (/ menu skill) | -no example |
Esc (Vim mode) | Returns to normal mode from insert mode when Vim mode is enabled. Docs: Esc (Vim mode) | -no example |
h, l | Vim mode: move left / right. Docs: h, l | -no example |
j, k | Vim mode: move down / up. Docs: j, k | -no example |
w, b | Vim mode: next / previous word. Docs: w, b | -no example |
e | Vim mode: end of word. Docs: e | -no example |
W, B, E | Vim mode: same as w, b, e but for WORD (non-whitespace sequence). Docs: W, B, E | -no example |
0, $ | Vim mode: start / end of line. Docs: 0, $ | -no example |
x | Vim mode: delete character under cursor. Docs: x | -no example |
X | Vim mode: delete character before cursor. Docs: X | -no example |
d + motion | Vim mode: delete range (e.g., dw deletes word). Docs: d + motion | dw |
dd | Vim mode: delete entire line. Docs: dd | -no example |
D | Vim mode: delete to end of line. Docs: D | -no example |
s | Vim mode: substitute character (delete + insert mode). Docs: s | -no example |
S, cc | Vim mode: change entire line. Docs: S, cc | -no example |
C | Vim mode: change to end of line. Docs: C | -no example |
i | Vim mode: insert at cursor. Docs: i | -no example |
a | Vim mode: insert after cursor. Docs: a | -no example |
I | Vim mode: insert at start of line. Docs: I | -no example |
A | Vim mode: insert at end of line. Docs: A | -no example |
o | Vim mode: open new line below. Docs: o | -no example |
O | Vim mode: open new line above. Docs: O | -no example |
<count> prefix | Vim mode: prefix commands with a number to repeat them; for example 3w moves forward 3 words and 2dd deletes 2 lines. Docs: <count> prefix | 3w |
f / F / t / T / ; / , | Vim find motions with operator composition (for example df, and ct.). Docs: f / F / t / T / ; / , | df, |
r | Vim mode: replace character. Docs: r | -no example |
Alt+Delete | Deletes a word in the input. Docs: Alt+Delete | -no example |
Settings46
Own page: Cursor CLI settings keys| Key | Description | Example |
|---|---|---|
version | Required cli-config.json field: config schema version. number (current: 1) Docs: version | {
"version": 1,
"editor": { "vimMode": false },
"permissions": { "allow": ["Shell(ls)"], "deny": [] }
} |
editor.vimMode | Required cli-config.json field that enables Vim keybindings. boolean (default: false) Docs: editor.vimMode | {
"version": 1,
"editor": { "vimMode": true },
"permissions": { "allow": ["Shell(ls)"], "deny": [] }
} |
permissions.deny | Required field listing forbidden operations. Deny rules take precedence over allow rules. string[] Docs: permissions.deny | -no example |
channel | Release channel used for CLI updates. string Docs: channel | -no example |
model | Selected model configuration. object Docs: model | -no example |
maxMode | Persisted preference for max mode in the model picker. boolean Docs: maxMode | -no example |
hasChangedDefaultModel | CLI-managed model override flag. boolean Docs: hasChangedDefaultModel | -no example |
notifications | Sends a terminal notification when the agent finishes or needs input. boolean Docs: notifications | -no example |
hints | Shows CLI hints while the agent is working. boolean Docs: hints | -no example |
rewind | Enables /rewind to restore an earlier message in the session. boolean Docs: rewind | -no example |
suggestNextPrompt | Suggests a follow-up prompt at the end of each turn. boolean Docs: suggestNextPrompt | -no example |
display.showLineNumbers | Shows line numbers in rendered code blocks. boolean Docs: display.showLineNumbers | -no example |
display.showThinkingBlocks | Renders model thinking blocks when available. boolean Docs: display.showThinkingBlocks | -no example |
display.showStatusIndicators | Enables terminal title status indicators. boolean Docs: display.showStatusIndicators | -no example |
display.showStatusLineRunningTime | Shows elapsed running time in the status line. boolean Docs: display.showStatusLineRunningTime | -no example |
approvalMode | Approval mode for tool calls. allowlist | auto-review | unrestricted Docs: approvalMode | -no example |
sandbox.mode | Sandbox mode override. string Docs: sandbox.mode | -no example |
sandbox.networkAccess | Network access setting for sandbox mode. string Docs: sandbox.networkAccess | -no example |
sandbox.readBoundary | Read access mode controlling whether the agent can read files outside the workspace without asking. sandbox.json overrides it. system (default) | workspace Docs: sandbox.readBoundary | -no example |
network.useHttp1ForAgent | Uses HTTP/1.1 with Server-Sent Events instead of HTTP/2 for agent connections, for proxies that do not support HTTP/2 bidirectional streaming. boolean (default: false) Docs: network.useHttp1ForAgent | {
"version": 1,
"editor": { "vimMode": false },
"permissions": { "allow": [], "deny": [] },
"network": {
"useHttp1ForAgent": true
}
} |
attribution.attributeCommitsToAgent | Adds a "Made with Cursor" trailer to Agent commits. Admin-disabled attribution is enforced regardless of local settings. boolean (default: true) Docs: attribution.attributeCommitsToAgent | -no example |
attribution.attributePRsToAgent | Adds a "Made with Cursor" footer to Agent PRs. boolean (default: true) Docs: attribution.attributePRsToAgent | -no example |
autoAcceptWebSearch | cli-config.json setting for the Auto-Accept Web Search permission, letting the agent run web searches without pausing for approval. Also toggled under Permissions in /config. boolean (off by default) Docs: autoAcceptWebSearch | -no example |
statusLine | Points to your own command whose output (with live token usage data) renders in the prompt footer as a custom status line. command Docs: statusLine | -no example |
Shell(commandBase) | Permission token controlling shell commands; commandBase is the first token of the command line. Supports globs and command:args syntax. e.g. Shell(ls), Shell(git), Shell(curl:*) Docs: Shell(commandBase) | Shell(curl:*) |
Read(pathOrGlob) | Permission token controlling read access to files and directories. Supports glob patterns. path or glob Docs: Read(pathOrGlob) | Read(src/**/*.ts) |
Write(pathOrGlob) | Permission token controlling write access to files and directories. Supports glob patterns. path or glob Docs: Write(pathOrGlob) | Write(src/**) |
WebFetch(domainOrPattern) | Permission token controlling which domains the web fetch tool can fetch without prompting. * matches all domains, *.example.com matches subdomains, example.com matches that domain only. domain or pattern Docs: WebFetch(domainOrPattern) | WebFetch(docs.github.com) |
Mcp(server:tool) | Permission token controlling which MCP tools the agent can run, using the server name from mcp.json and the tool name, with * wildcards. server:tool Docs: Mcp(server:tool) | Mcp(datadog:*) |
autoRun.allow_instructions | permissions.json key: plain-English instructions describing actions Auto-review should lean toward allowing. The CLI reads the same permissions.json as the IDE. string[] Docs: autoRun.allow_instructions | -no example |
autoRun.block_instructions | permissions.json key: plain-English instructions describing actions Auto-review should lean toward blocking. string[] Docs: autoRun.block_instructions | {
"autoRun": {
"allow_instructions": [],
"block_instructions": [
"Every AWS CLI command should go through approval first.",
"Every command that modifies Kubernetes resources should go through approval first."
]
}
} |
type (sandbox.json) | sandbox.json sandbox mode, honored by the CLI. workspace_readwrite gives read/write in the workspace, workspace_readonly restricts to read-only, insecure_none disables the sandbox. "workspace_readwrite" (default) | "workspace_readonly" | "insecure_none" Docs: type (sandbox.json) | -no example |
additionalReadwritePaths | sandbox.json: extra paths the agent can read and write. Only applies when type is workspace_readwrite. string[] (default: []) Docs: additionalReadwritePaths | -no example |
additionalReadonlyPaths | sandbox.json: extra paths the agent can read. string[] (default: []) Docs: additionalReadonlyPaths | -no example |
readBoundary | sandbox.json read access mode; workspace asks before reading outside the workspace. Overrides sandbox.readBoundary in cli-config.json. "system" (default) | "workspace" Docs: readBoundary | {
"readBoundary": "workspace",
"additionalReadPaths": ["/opt/shared/design-tokens", "~/notes/*.md"]
} |
additionalReadPaths | sandbox.json Read Allowlist paths and globs the agent can read outside the workspace. Only applies when readBoundary is workspace. string[] (default: []) Docs: additionalReadPaths | -no example |
disableTmpWrite | sandbox.json: when true, removes default write access to /tmp and system temp directories. boolean (default: false) Docs: disableTmpWrite | -no example |
enableSharedBuildCache | sandbox.json: redirects build-tool caches (npm, cargo, pip, etc.) to a shared tmpdir so sandboxed and unsandboxed commands share caches. boolean (default: false) Docs: enableSharedBuildCache | -no example |
networkPolicy.default | sandbox.json: action when no allow/deny rule matches. "allow" | "deny" (default: "deny") Docs: networkPolicy.default | {
"networkPolicy": {
"default": "allow"
}
} |
networkPolicy.allow | sandbox.json: patterns to allow; supports exact domains, wildcards, and CIDR notation. string[] (default: []) Docs: networkPolicy.allow | -no example |
networkPolicy.deny | sandbox.json: patterns to deny. Highest priority; always blocks even if also in allow. string[] (default: []) Docs: networkPolicy.deny | -no example |
setup-worktree | .cursor/worktrees.json generic fallback setup for all operating systems, checked when the CLI creates a worktree. Accepts an array of shell commands or a script path. string[] | string Docs: setup-worktree | {
"setup-worktree": [
"npm ci",
"cp $ROOT_WORKTREE_PATH/.env .env"
]
} |
setup-worktree-unix | .cursor/worktrees.json commands or script path for macOS and Linux; takes precedence over setup-worktree on Unix. string[] | string Docs: setup-worktree-unix | -no example |
setup-worktree-windows | .cursor/worktrees.json commands or script path for Windows; takes precedence over setup-worktree on Windows. string[] | string Docs: setup-worktree-windows | -no example |
enabled_plugins | Key in ~/.cursor/settings.json that points at local plugin folders, so local plugins load without a marketplace. Docs: enabled_plugins | -no example |
user-invocable | SKILL.md frontmatter key; setting it to false hides the skill from / autocomplete and typed /skill-name resolution while keeping it available to the model. boolean Docs: user-invocable | user-invocable: false |
Environment variables36
Own page: Cursor CLI environment variables| Variable | Description | Example |
|---|---|---|
CURSOR_API_KEY | API key for authentication, recommended for automation, scripts, and CI. Equivalent to --api-key. string Docs: CURSOR_API_KEY | export CURSOR_API_KEY=your_api_key_here
agent "implement user authentication" |
CURSOR_AUTH_TOKEN | Auth token alternative to --auth-token for pre-authenticating. Also passed to controller spawn hooks in place of CURSOR_API_KEY when --session-token is used. string Docs: CURSOR_AUTH_TOKEN | -no example |
CURSOR_CONFIG_DIR | Overrides the CLI config location with a custom directory path. path Docs: CURSOR_CONFIG_DIR | -no example |
XDG_CONFIG_HOME | On Linux/BSD, the CLI uses $XDG_CONFIG_HOME/cursor/cli-config.json when set. path Docs: XDG_CONFIG_HOME | -no example |
NO_OPEN_BROWSER | Set to 1 to print the login URL without opening a browser. 1 Docs: NO_OPEN_BROWSER | NO_OPEN_BROWSER=1 agent login |
HTTP_PROXY | Proxy server for CLI traffic when your network routes through a proxy. URL Docs: HTTP_PROXY | export HTTP_PROXY=http://your-proxy:port |
HTTPS_PROXY | HTTPS proxy server; honored for login, API-key validation, and the agent streaming connection. URL Docs: HTTPS_PROXY | export HTTPS_PROXY=http://your-proxy:port |
NODE_USE_ENV_PROXY | Set alongside HTTP_PROXY/HTTPS_PROXY when configuring the CLI behind a proxy. 1 Docs: NODE_USE_ENV_PROXY | export NODE_USE_ENV_PROXY=1 |
NODE_EXTRA_CA_CERTS | Path to your organization's CA certificate when the proxy performs SSL inspection. path Docs: NODE_EXTRA_CA_CERTS | export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca-cert.pem |
COLORFGBG | Forces the CLI theme when automatic terminal color detection does not work. "15;0" (dark) | "0;15" (light) Docs: COLORFGBG | # Force dark theme
export COLORFGBG="15;0"
# Force light theme
export COLORFGBG="0;15" |
TERM | Terminal type; the troubleshooting guide says to check it is set correctly when colors look wrong. e.g. xterm-256color Docs: TERM | -no example |
AGENT_CLI_CREDENTIAL_STORE | Set to file to store credentials unencrypted in an owner-only file, for sandboxes without macOS Keychain. Packaged Unix builds also skip system CA loading in this mode. file Docs: AGENT_CLI_CREDENTIAL_STORE | AGENT_CLI_CREDENTIAL_STORE=file |
SHELL | Shell Mode runs commands in your login shell from $SHELL; zsh and bash are supported. path to zsh or bash Docs: SHELL | -no example |
EDITOR | Ctrl+G opens your prompt in $EDITOR and drops the result back into the prompt bar. editor command Docs: EDITOR | -no example |
CURSOR_WORKER_LABELS_FILE | Path to a JSON or TOML labels file for agent worker, equivalent to --labels-file. path Docs: CURSOR_WORKER_LABELS_FILE | -no example |
CURSOR_WORKER_IDLE_RELEASE_TIMEOUT | Env var for --idle-release-timeout: seconds to stay connected after a session ends. seconds (default 3600 per pool docs; 0 disables) Docs: CURSOR_WORKER_IDLE_RELEASE_TIMEOUT | -no example |
CURSOR_WORKER_POOL_NAME | Env var for the worker pool name (--pool / --pool-name). string (default: default) Docs: CURSOR_WORKER_POOL_NAME | -e CURSOR_WORKER_POOL_NAME="$CURSOR_POOL" |
CURSOR_AGENT_WORKER_ID | Worker id the machine must start with; the worker CLI reads it automatically. Set by worker controller for spawn hooks. string Docs: CURSOR_AGENT_WORKER_ID | -no example |
CURSOR_API_ENDPOINT | Public API base for worker controller (--endpoint); also passed to spawn hooks with CURSOR_API_URL. URL (default https://api.cursor.com) Docs: CURSOR_API_ENDPOINT | -no example |
CURSOR_API_URL | API base the controller is using, set in spawn hook environments. URL Docs: CURSOR_API_URL | -no example |
CURSOR_REQUEST_ID | Claim mode spawn hook variable: agent id of the claimed request. string Docs: CURSOR_REQUEST_ID | -no example |
CURSOR_USER_ID | Claim mode spawn hook variable: Cursor user id that created the request. string Docs: CURSOR_USER_ID | -no example |
CURSOR_REPO_URL, CURSOR_REPO_OWNER, CURSOR_REPO_NAME | Claim mode spawn hook variables with repository metadata when the request targets a repo. Unset for any-repo requests. string Docs: CURSOR_REPO_URL, CURSOR_REPO_OWNER, CURSOR_REPO_NAME | -no example |
CURSOR_REPO_URLS | Claim mode spawn hook variable: JSON array of repository URLs for multi-repo requests. JSON array Docs: CURSOR_REPO_URLS | -no example |
CURSOR_POOL | Spawn hook variable (both modes): pool the worker should join. string Docs: CURSOR_POOL | agent worker --pool "$CURSOR_POOL" --worker-id "$CURSOR_AGENT_WORKER_ID" start |
CURSOR_WORKER_NAME | Spawn hook variable (both modes): display name for the worker. string Docs: CURSOR_WORKER_NAME | -no example |
CURSOR_AUTH_TOKEN_EXPIRES_AT | Claim mode with --session-token: expiry of the session token as an ISO 8601 timestamp. ISO 8601 timestamp Docs: CURSOR_AUTH_TOKEN_EXPIRES_AT | -no example |
CURSOR_IDENTITY_TOKEN, CURSOR_IDENTITY_TOKEN_EXPIRES_AT | Claim mode with --identity-audience: identity token for this claim and its expiry. string; timestamp Docs: CURSOR_IDENTITY_TOKEN, CURSOR_IDENTITY_TOKEN_EXPIRES_AT | -no example |
CURSOR_IDENTITY_NONCE | Claim mode with --identity-audience: nonce the controller sent with this claim, to compare with the token's nonce. string Docs: CURSOR_IDENTITY_NONCE | -no example |
CURSOR_WAKE | Set to 1 when agent worker controller --warm-idle runs the --spawn hook to wake a hibernated worker for a follow-up. 1 Docs: CURSOR_WAKE | -no example |
CURSOR_AGENT_SOCKET | Set in claimed agents' shells to the path of the per-claim OIDC token socket when the worker uses --identity-socket. path Docs: CURSOR_AGENT_SOCKET | -no example |
CURSOR_SANDBOX | Injected into sandboxed child processes when running inside the sandbox. "seatbelt" (macOS) | "native" (Linux) Docs: CURSOR_SANDBOX | -no example |
CURSOR_ORIG_UID | UID of the user who launched Cursor, captured before sandbox namespace or identity changes (macOS, Linux). integer Docs: CURSOR_ORIG_UID | docker run --rm \
--user "${CURSOR_ORIG_UID:-$(id -u)}:${CURSOR_ORIG_GID:-$(id -g)}" \
-v "$PWD:/work" -w /work \
my-image build |
CURSOR_ORIG_GID | GID of the user who launched Cursor, captured before sandbox identity changes (macOS, Linux). integer Docs: CURSOR_ORIG_GID | -no example |
CURSOR_SANDBOX_LANDLOCK_STATUS | Linux only: reports the active sandbox backend, useful for diagnostics. fully_enforced (Landlock) | bubblewrap (Bubblewrap fallback) Docs: CURSOR_SANDBOX_LANDLOCK_STATUS | -no example |
ROOT_WORKTREE_PATH | Available to worktree setup commands in .cursor/worktrees.json to reference the root worktree. path Docs: ROOT_WORKTREE_PATH | cp $ROOT_WORKTREE_PATH/.env .env |
Config files23
Own page: Cursor CLI config files| Path | Description | Example |
|---|---|---|
~/.cursor/cli-config.json | Global CLI config file on macOS/Linux. Pure JSON (no comments); the CLI self-repairs missing fields and backs up corrupted files as .bad. JSON Docs: ~/.cursor/cli-config.json | mv ~/.cursor/cli-config.json ~/.cursor/cli-config.json.bad |
$env:USERPROFILE\.cursor\cli-config.json | Global CLI config file on Windows. JSON Docs: $env:USERPROFILE\.cursor\cli-config.json | -no example |
<project>/.cursor/cli.json | Project-level CLI config. Only permissions can be configured at the project level. JSON Docs: <project>/.cursor/cli.json | -no example |
$XDG_CONFIG_HOME/cursor/cli-config.json | Config location used on Linux/BSD when XDG_CONFIG_HOME is set. JSON Docs: $XDG_CONFIG_HOME/cursor/cli-config.json | -no example |
.cursor/mcp.json | Project-level MCP configuration shared with the editor; the CLI follows project, global, nested precedence and discovers configs from parent directories. Project-level servers require approval. JSON Docs: .cursor/mcp.json | -no example |
~/.cursor/mcp.json | User-level MCP configuration; servers from it load without per-workspace prompts. JSON Docs: ~/.cursor/mcp.json | -no example |
~/.cursor/permissions.json | User-level permissions.json that the CLI reads (same terminal/MCP allowlist file as the IDE) and Auto-review uses for allow/block instructions. JSON Docs: ~/.cursor/permissions.json | -no example |
<project-dir>/.cursor/permissions.json | Project-level permissions.json, merged with the user file; a team dashboard configuration takes priority over both. JSON Docs: <project-dir>/.cursor/permissions.json | -no example |
~/.cursor/sandbox.json | Per-user sandbox policy file honored by the CLI (including over SSH); lower priority than the workspace file. JSON Docs: ~/.cursor/sandbox.json | -no example |
<workspace>/.cursor/sandbox.json | Per-repo sandbox policy file; merged with the user file with per-repo settings taking priority. JSON Docs: <workspace>/.cursor/sandbox.json | -no example |
.cursor/worktrees.json | Worktree setup scripts run when the CLI creates a worktree; looked up in the worktree path, then the project root. Runs only after the workspace is trusted; skipped with --skip-worktree-setup. JSON Docs: .cursor/worktrees.json | -no example |
~/.cursor/worktrees/<reponame>/<name> | Directory where CLI worktrees are created, alongside editor worktrees; cleaned up with the same retention rules. directory Docs: ~/.cursor/worktrees/<reponame>/<name> | -no example |
.cursor/rules | Rules directory loaded automatically by the CLI agent, using the same rules system as the editor; nested subdirectories are discovered. directory Docs: .cursor/rules | -no example |
AGENTS.md | Read at the project root (if present) and applied as rules alongside .cursor/rules. Markdown Docs: AGENTS.md | -no example |
CLAUDE.md | Read at the project root (if present) and applied as rules alongside .cursor/rules. Markdown Docs: CLAUDE.md | -no example |
.cursor/skills, .claude/skills, .agents/skills, .codex/skills | Skill directories discovered by the CLI; .cursor/skills in subdirectories are discovered too. directories Docs: .cursor/skills, .claude/skills, .agents/skills, .codex/skills | -no example |
~/.cursor/skills-cursor | Location where managed-skill sync materializes a skill's nested Markdown files. directory Docs: ~/.cursor/skills-cursor | -no example |
~/.cursor/settings.json | Settings file where an enabled_plugins key can point at local plugin folders. JSON Docs: ~/.cursor/settings.json | -no example |
~/.zshrc | Target file for install-shell-integration and uninstall-shell-integration. Docs: ~/.zshrc | -no example |
~/.local/bin | Install location to add to PATH after installation; the default binary path is ~/.local/bin/agent. directory Docs: ~/.local/bin | echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc |
$HOME/.cursor/bin | Path added to GITHUB_PATH in the documented GitHub Actions setup after installing the CLI. directory Docs: $HOME/.cursor/bin | echo "$HOME/.cursor/bin" >> $GITHUB_PATH |
.cursor/hooks.json | Hooks file that pool workers run in addition to --on-session-start commands. JSON Docs: .cursor/hooks.json | -no example |
.envrc | direnv file loaded automatically by the agent's shell in interactive and agent-dispatched shells. Docs: .envrc | -no example |
More on Cursor CLI
- Cursor CLI in the tools directoryWhat it is, who makes it and how it fits next to other coding agents.
- Cursor CLI errors and fixes18 error messages, quoted verbatim, with the documented fix for each.
- Cursor usage limitsPlan and tier limits for this tool, copied from the official docs.
Use other models in Cursor CLI
Setup guides from the model-in-tool directory, each with the env vars and base URL from official docs.
Related reading
FAQ
How many commands and options does Cursor CLI have?
The official Cursor CLI docs list 327 items: 53 slash commands, 73 CLI flags, 42 subcommands, 54 keyboard shortcuts, 46 settings keys, 36 environment variables and 23 config files. The largest group is CLI flags, with 73.
Where does Cursor CLI keep its configuration?
Cursor CLI documents 23 config files and locations, including ~/.cursor/cli-config.json, $env:USERPROFILE\.cursor\cli-config.json and <project>/.cursor/cli.json. The docs describe ~/.cursor/cli-config.json as: Global CLI config file on macOS/Linux. Pure JSON (no comments); the CLI self-repairs missing fields and backs up corrupted files as .bad.
Which environment variables does Cursor CLI read?
The docs list 36 environment variables, such as CURSOR_API_KEY, CURSOR_AUTH_TOKEN, CURSOR_CONFIG_DIR and XDG_CONFIG_HOME. Each one is in the environment variables table above with what it controls.
Sources
Last verified . Names and examples are copied verbatim from the 19 official pages below, and every row above links the exact section it came from.
- cursor.com/docs/cli/reference/parameters70 items
- cursor.com/docs/cli/reference/output-format1 item
- cursor.com/docs/cli/acp5 items
- cursor.com/docs/cli/changelog56 items
- cursor.com/docs/cloud-agent/self-hosted/pool35 items
- cursor.com/docs/cli/reference/authentication4 items
- cursor.com/docs/cli/mcp6 items
- cursor.com/docs/cli/installation2 items
- cursor.com/docs/cli/reference/slash-commands36 items
- cursor.com/docs/cli/reference/terminal-setup28 items
- cursor.com/docs/cli/reference/configuration32 items
- cursor.com/docs/cli/reference/permissions5 items
- cursor.com/docs/agent/security/run-modes8 items
- cursor.com/docs/reference/sandbox12 items
- cursor.com/docs/configuration/worktrees5 items
- cursor.com/docs/cli/shell-mode5 items
- cursor.com/docs/cli/using15 items
- cursor.com/docs/cli/github-actions1 item
- cursor.com/docs/cli/overview1 item
Newsletter
Know when your tools change
One email per week. New coding agent releases, the flags and commands they add, and what they mean for how you work.