Configuration
Configure the Agent CLI using the cli-config.json file.
File location
| Type | Platform | Path |
|---|---|---|
| Global | macOS/Linux | ~/.cursor/cli-config.json |
| Global | Windows | $env:USERPROFILE\.cursor\cli-config.json |
| Project | All | <project>/.cursor/cli.json |
Only permissions can be configured at the project level. All other CLI settings must be set globally.
Override with environment variables:
CURSOR_CONFIG_DIR: custom directory pathXDG_CONFIG_HOME(Linux/BSD): uses$XDG_CONFIG_HOME/cursor/cli-config.json
Schema
Required fields
| Field | Type | Description |
|---|---|---|
version | number | Config schema version (current: 1) |
editor.vimMode | boolean | Enable Vim keybindings (default: false) |
permissions.allow | string[] | Permitted operations (see Permissions) |
permissions.deny | string[] | Forbidden operations (see Permissions) |
Optional fields
| Field | Type | Description |
|---|---|---|
channel | string | Release channel used for CLI updates |
model | object | Selected model configuration |
maxMode | boolean | Persisted preference for max mode in the model picker |
hasChangedDefaultModel | boolean | CLI-managed model override flag |
notifications | boolean | Send a terminal notification when the agent finishes or needs input |
hints | boolean | Show CLI hints while the agent is working |
rewind | boolean | Enable /rewind to restore an earlier message in the session |
suggestNextPrompt | boolean | Suggest a follow-up prompt at the end of each turn |
display.showLineNumbers | boolean | Show line numbers in rendered code blocks |
display.showThinkingBlocks | boolean | Render model thinking blocks when available |
display.showStatusIndicators | boolean | Enable terminal title status indicators |
display.showStatusLineRunningTime | boolean | Show elapsed running time in the status line |
approvalMode | string | Approval mode: allowlist, auto-review, or unrestricted |
sandbox.mode | string | Sandbox mode override |
sandbox.networkAccess | string | Network access setting for sandbox mode |
network.useHttp1ForAgent | boolean | Use HTTP/1.1 instead of HTTP/2 for agent connections (default: false) |
attribution.attributeCommitsToAgent | boolean | Add "Made with Cursor" trailer to Agent commits (default: true) |
attribution.attributePRsToAgent | boolean | Add "Made with Cursor" footer to Agent PRs (default: true) |
Examples
Minimal config
{ "version": 1, "editor": { "vimMode": false }, "permissions": { "allow": ["Shell(ls)"], "deny": [] }}Enable Vim mode
{ "version": 1, "editor": { "vimMode": true }, "permissions": { "allow": ["Shell(ls)"], "deny": [] }}Configure permissions
{ "version": 1, "editor": { "vimMode": false }, "permissions": { "allow": ["Shell(ls)", "Shell(echo)"], "deny": ["Shell(rm)"] }}See Permissions for available permission types and examples.
Troubleshooting
Config errors: Move the file aside and restart:
mv ~/.cursor/cli-config.json ~/.cursor/cli-config.json.badChanges don't persist: Ensure valid JSON and write permissions. Some fields are CLI-managed and may be overwritten.
Notes
- Pure JSON format (no comments)
- CLI performs self-repair for missing fields
- Corrupted files are backed up as
.badand recreated - Permission entries are exact strings (see Permissions for details)
Models
You can select a model for the CLI using the /model slash command.
/model auto/model gpt-5/model sonnet-4-thinkingSee the Slash commands docs for other commands.
Proxy configuration
If your network routes traffic through a proxy server, configure the CLI using environment variables and the config file.
Environment variables
Set these environment variables before running the CLI:
export HTTP_PROXY=http://your-proxy:portexport HTTPS_PROXY=http://your-proxy:portexport NODE_USE_ENV_PROXY=1If your proxy performs SSL inspection (man-in-the-middle), also trust your organization's CA certificate:
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca-cert.pemHTTP/1.1 fallback
Some enterprise proxies (like Zscaler) don't support HTTP/2 bidirectional streaming. Enable HTTP/1.1 mode in your config:
{ "version": 1, "editor": { "vimMode": false }, "permissions": { "allow": [], "deny": [] }, "network": { "useHttp1ForAgent": true }}This switches agent connections to HTTP/1.1 with Server-Sent Events (SSE), which works with most corporate proxies.
See Network Configuration for proxy testing commands and troubleshooting.