The Cursor CLI: agent mode outside the editor

Installing it

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

export PATH="$HOME/.local/bin:$PATH"   # add this to .zshrc or .bashrc

agent --version
agent login
agent status

irm 'https://cursor.com/install?win32=true' | iex

The flags that matter

Headless and scripted runs

This is the reason to have a CLI at all. Print mode turns the agent into something you can pipe, schedule, and put in a pipeline.

# plain text out
agent -p "summarise what changed in the last three commits"

# structured, for a script to parse
agent -p --output-format json "list every TODO in src/ with its file and line"

# actually apply changes, no confirmation prompts
agent -p --force "convert src/utils/*.js to TypeScript, keep behaviour identical"

For long or streaming runs, --output-format stream-json emits typed events as they happen: a system event with the model, assistant events carrying text, tool_call events with a started or completed subtype, and a final result with a duration. That is what you pipe into jq behind a progress indicator, rather than a job that appears frozen for four minutes.

- name: Install Cursor CLI
  run: |
    curl https://cursor.com/install -fsS | bash
    echo "$HOME/.cursor/bin" >> $GITHUB_PATH

- name: Review the diff
  env:
    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
  run: |
    agent -p --output-format json \
      "review the changes in this PR for missing error handling" \
      > review.json

The sandbox, and why it is the best reason to use the CLI

The CLI has a sandbox of its own, which matters more here than in the editor because nobody is watching a terminal run inside a pipeline. It is configured with a sandbox.json file, and the defaults are the interesting part.

{
  "networkPolicy": {
    "default": "deny",
    "allow": ["registry.npmjs.org", "*.github.com"]
  },
  "additionalReadonlyPaths": ["~/.config/myapp"],
  "disableTmpWrite": false
}

Network denied by default is the setting worth appreciating. Most of what people fear from an autonomous agent needs an outbound connection, and a run that can read your repository but cannot phone anywhere is a much smaller risk surface than one that can do both. Allowlisting your package registry and your git host covers the majority of real work.

Separately, the CLI reads a config file at ~/.cursor/cli-config.json, with a project-level .cursor/cli.json for permissions only. It carries permissions.allow and permissions.deny arrays and an approvalMode of allowlist, auto-review, or unrestricted. Set the approval mode there rather than reaching for --yolo on every invocation.

Running several at once

The strongest reason to use a terminal agent at all is that it parallelises. That requires one working tree per agent, or they overwrite each other. The Cursor CLI has this built in rather than leaving it to you, which none of the other mainstream terminal agents do.

# each run gets its own isolated checkout
agent -w auth   "add JWT middleware under src/middleware, do not touch login"
agent -w search "add full-text search to the notes list"

# base a worktree on something other than the current HEAD
agent -w hotfix --worktree-base release/2.4 "patch the null deref in parser.ts"

{
  "setup-worktree-unix": [
    "cp ../main-repo/.env .env",
    "pnpm install --frozen-lockfile"
  ],
  "setup-worktree-windows": "scripts/setup-worktree.ps1"
}

What you gain and lose against the editor

Against the other terminal agents

The -w row is the genuine differentiator and is not talked about enough. Every terminal agent benefits from one worktree per session, and Cursor is the one that ships the flag instead of leaving you to write the shell around it.

Questions people ask

Keep reading