Cursor CLI reference - Environment variables
Cursor CLI environment variables
Cursor CLI documents 36 environment variables, including CURSOR_API_KEY, CURSOR_AUTH_TOKEN and CURSOR_CONFIG_DIR. Cursor CLI reads these from your shell environment. Each row gives the docs' description, accepted values and an example where one is documented.
Last verified 10 official pagesFull Cursor CLI reference
| 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 |
The rest of the Cursor CLI reference
FAQ
How many environment variables does Cursor CLI have?
The official Cursor CLI docs list 36 environment variables, including CURSOR_API_KEY, CURSOR_AUTH_TOKEN and CURSOR_CONFIG_DIR. All of them are in the table above, in the docs' order.
What does CURSOR_API_KEY do in Cursor CLI?
API key for authentication, recommended for automation, scripts, and CI. Equivalent to --api-key. Values: string. Example: export CURSOR_API_KEY=your_api_key_here
Where are Cursor CLI environment variables documented?
On 10 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 10 official pages below, and every row above links the exact section it came from.
- cursor.com/docs/cli/reference/authentication2 items
- cursor.com/docs/cli/acp1 item
- cursor.com/docs/cli/reference/configuration6 items
- cursor.com/docs/cli/reference/terminal-setup2 items
- cursor.com/docs/cli/changelog3 items
- cursor.com/docs/cli/shell-mode1 item
- cursor.com/docs/cli/reference/parameters1 item
- cursor.com/docs/cloud-agent/self-hosted/pool15 items
- cursor.com/docs/agent/security/run-modes4 items
- cursor.com/docs/configuration/worktrees1 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.