Cursor CLI: install, headless mode, permissions and CI

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.

curl https://cursor.com/install -fsS | bash
agent --version

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.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

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

{
  "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.

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.

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.

- 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_MODEL

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