Cursor CLI: install, headless mode, permissions and CI
How do I set up and run the Cursor CLI, including in scripts and CI?
Install the Cursor CLI with the official install script, then run the agent command for an interactive session or agent -p for non-interactive print mode. Control what the agent may do with permissions.allow and permissions.deny in ~/.cursor/cli-config.json or a project .cursor/cli.json file. For CI, set the CURSOR_API_KEY environment variable and run agent in print mode.
Compare: headless mode for scripts and CI in every AI coding agent →
Install and run
On macOS, Linux and Windows (WSL) the CLI installs with a single command. Native Windows uses a PowerShell command instead. The installed command is called agent, and it tries to auto-update by default.
Install (macOS, Linux, WSL)
curl https://cursor.com/install -fsS | bash agent --version
Install (Windows PowerShell)
irm 'https://cursor.com/install?win32=true' | iex
If the agent command is not found after install, add ~/.local/bin to your PATH as the installation docs describe. You can update manually with agent update.
Add to PATH (bash)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc
Interactive vs print mode
Running agent with no command starts an interactive session where you describe goals, review proposed changes and approve commands. Print mode (-p or --print) runs non-interactively for scripts and CI and prints the response to the console.
- --model YOUR_MODEL picks the model; agent --list-models or agent models lists the models available to your account.
- --output-format text, json or stream-json controls print mode output (default text). It only works with --print.
- --stream-partial-output streams text deltas, and only works with --print and stream-json.
- --mode plan or --mode ask switches modes; agent mode is the default. --plan is shorthand for plan mode.
- -f or --force allows commands unless they are explicitly denied. Without --force, print mode only proposes file changes.
- --resume, --continue, agent resume and agent ls let you pick up earlier chats.
Interactive and print mode
# Interactive session with an initial prompt agent "refactor the auth module to use JWT tokens" # Non-interactive, structured output agent -p "review these changes for security issues" --model YOUR_MODEL --output-format json # Allow file edits in a script agent -p --force "Add JSDoc comments to src/app.js"
Permissions, MCP and rules
Permissions live in the permissions object of ~/.cursor/cli-config.json (global) or .cursor/cli.json inside your project. Only permissions can be set at the project level. Tokens include Shell(command), Read(glob), Write(glob), WebFetch(domain) and Mcp(server:tool), and deny rules take precedence over allow rules.
.cursor/cli.json
{
"permissions": {
"allow": ["Shell(ls)", "Shell(git)", "Read(src/**/*.ts)", "Write(src/**)", "Mcp(datadog:*)"],
"deny": ["Shell(rm)", "Read(.env*)", "Write(**/*.key)"]
}
}The CLI reads the same mcp.json configuration as the editor, so MCP servers you set up there also work in the terminal. Manage them with the agent mcp subcommands, or pass --approve-mcps to approve all MCP servers automatically.
MCP commands
agent mcp list agent mcp list-tools YOUR_SERVER agent mcp login YOUR_SERVER agent mcp enable YOUR_SERVER
The CLI uses the same rules system as the editor and loads rules from the .cursor/rules directory. It also reads AGENTS.md and CLAUDE.md at the project root, if present, and applies them as rules.
Using it in CI
For automation, generate a user API key in the Cursor Dashboard and expose it as the CURSOR_API_KEY environment variable. The --api-key flag also works, but the docs recommend the environment variable. In headless runs, --trust trusts the workspace without prompting.
GitHub Actions steps
- name: Install Cursor CLI
run: |
curl https://cursor.com/install -fsS | bash
echo "$HOME/.cursor/bin" >> $GITHUB_PATH
- name: Run Cursor Agent
env:
CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
run: |
agent -p "Your prompt here" --model YOUR_MODELFor production CI, Cursor recommends restricting the agent with permissions, for example denying Shell(git) and Shell(gh), and handling commits, pushes and PR comments in separate deterministic workflow steps.
Sources
More Cursor guides
- How to allow Cursor to run all commands: Run Everything, allowlist and sandbox
- Cursor Privacy Mode: telemetry, training and data retention
- Add MCP servers to Cursor with mcp.json
- Keep files out of Cursor with .cursorignore
- Cursor hooks: hooks.json, beforeShellExecution, afterFileEdit and exit codes
- Cursor sandbox: sandbox.json, network allowlist and run modes
- Cursor settings: settings.json, Cursor Settings and the ~/.cursor config files
- Cursor browser agent: @browser, browser automation and approval modes
- Cursor subagents: .cursor/agents, frontmatter, built-in Explore and Browser
- Cursor telemetry and OpenTelemetry export (Privacy Mode, OTLP, Analytics API)
- Cursor rules setup: project, user and Team Rules, .mdc frontmatter, globs and AGENTS.md
- Cursor skills and custom slash commands: .cursor/skills SKILL.md, .cursor/commands and /migrate-to-skills
Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.
Built an MCP server? Get it listed everywhere →
Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →