Cursor CLI reference - CLI flags
Cursor CLI command-line flags
Cursor CLI documents 73 CLI flags, including --api-key <key>, --output-format <format> and --stream-partial-output. You pass these to cursor-agent on the command line. Each row gives the docs' description, accepted values and an example where one is documented.
Last verified 5 official pagesFull Cursor CLI reference
| 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 |
The rest of the Cursor CLI reference
FAQ
How many CLI flags does Cursor CLI have?
The official Cursor CLI docs list 73 CLI flags, including --api-key <key>, --output-format <format> and --stream-partial-output. All of them are in the table above, in the docs' order.
What does -v, --version do in Cursor CLI?
Global option that outputs the version number. The install docs use it to verify that Cursor CLI is working. Example: agent --version
Where are Cursor CLI command-line flags documented?
On 5 official docs pages at cursor.com, last read on October 17, 2026. Every row in the table links the exact section it came from.
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.
Sources
Last verified . Names and examples are copied verbatim from the 5 official pages below, and every row above links the exact section it came from.
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.