Skip to main content
Watch: I Built an AI App Without Leaving Databricks

Cursor CLI reference - Config files

Cursor CLI config files and locations

Cursor CLI documents 23 config files, including ~/.cursor/cli-config.json, $env:USERPROFILE\.cursor\cli-config.json and <project>/.cursor/cli.json. These are the files and directories Cursor CLI reads its configuration from. Each row gives the docs' description, accepted values and an example where one is documented.

Last verified 11 official pagesFull Cursor CLI reference

Cursor CLI config files
PathDescriptionExample
~/.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

The rest of the Cursor CLI reference

FAQ

How many config files does Cursor CLI have?

The official Cursor CLI docs list 23 config files, including ~/.cursor/cli-config.json, $env:USERPROFILE\.cursor\cli-config.json and <project>/.cursor/cli.json. All of them are in the table above, in the docs' order.

What does ~/.cursor/cli-config.json do in Cursor CLI?

Global CLI config file on macOS/Linux. Pure JSON (no comments); the CLI self-repairs missing fields and backs up corrupted files as .bad. Values: JSON. Example: mv ~/.cursor/cli-config.json ~/.cursor/cli-config.json.bad

Where are Cursor CLI config files documented?

On 11 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

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 11 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.