Cursor CLI: Using Cursor’s Agent From the Terminal

Cursor CLI is Cursor’s agent without the editor. You install it with one line, run it as agent, and it works on the folder you are in: reading code, editing files, running commands after you approve them. It uses the same rules, AGENTS.md and mcp.json as the editor, so a project set up for Cursor needs nothing new. Run agent for an interactive session, or agent -p "..." to print a single answer for a script, with --output-format json or stream-json when a program reads the result. What it may do without asking is set in a small JSON file of allow and deny rules.

Install and sign in

Cursor’s installation page↗ (opens in a new tab) gives one command for macOS, Linux and WSL and one for native Windows. Afterwards, make sure ~/.local/bin is on your PATH and check the version.

# macOS, Linux, WSL
curl https://cursor.com/install -fsS | bash

# Windows (PowerShell)
irm 'https://cursor.com/install?win32=true' | iex

agent --version
agent login          # opens the browser to sign in to your Cursor account
agent status         # who you are signed in as
agent update         # it also tries to update itself by default

On a machine with no browser, NO_OPEN_BROWSER=1 agent login prints the sign-in address instead. Scripts and CI use an API key from the Cursor dashboard, passed in the CURSOR_API_KEY environment variable or with --api-key. The environment variable is the better habit; a flag ends up in shell history and process lists.

Interactive sessions

Run agent on its own, or agent "explain the auth flow" to start with a prompt. The CLI has the editor’s modes: Agent does the work, Plan asks clarifying questions and designs an approach first, and Ask explores without changing anything. Shift+Tab rotates between them; /plan and /ask switch directly; --plan or --mode=ask starts a session in that mode. When to use which is covered in Cursor Agent vs Ask vs Plan.

• Before running a terminal command the CLI asks you to approve (y) or reject (n) it.
• Ctrl+R reviews the changes so far; press i to add a follow-up instruction.
• @ adds files or folders to the context; /summarize frees space when a long session fills up.
• agent ls lists earlier chats, agent resume or --continue reopens the latest, and --resume <chat id> a specific one.
• -w or --worktree [name] runs the agent in a new Git worktree under ~/.cursor/worktrees/, so it never edits your current checkout.
• Starting a message with & hands the conversation to a cloud agent that keeps running while you are away, covered in Cursor cloud agents.

Choosing a model

/model inside a session opens a picker, and /model followed by a name switches directly. From the shell, agent models or --list-models prints what your account can use, and --model <name> sets it for one run. The list depends on your plan and changes often, so read it from your own install rather than from an article; a script that pins a model name will need updating when that model is retired.

Rules and AGENTS.md

The CLI loads the same project rules as the editor from .cursor/rules, applied according to each rule’s settings. Cursor’s page on using the agent in the CLI↗ (opens in a new tab) adds that it also reads AGENTS.md and CLAUDE.md at the project root and applies them as rules alongside .cursor/rules. So a repository that already keeps shared instructions in AGENTS.md for other agents works in Cursor CLI unchanged. agent generate-rule writes a new rule through a few prompts. Worked rule files for common stacks are in Cursor rules examples.

MCP servers

The CLI reads the editor’s mcp.json: .cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project. A remote server needs only its URL; if it uses OAuth, agent mcp login <name> signs in. For a CI job, which cannot open a browser, the same file can send a token from an environment variable, because Cursor resolves ${env:NAME} in url and headers.

{
  "mcpServers": {
    "fenbs": {
      "url": "https://fenbs.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FENBS_TOKEN}"
      }
    }
  }
}

• agent mcp list shows each configured server and its status; agent mcp list-tools <name> lists its tools.
• agent mcp enable <name> approves a server locally and agent mcp disable <name> stops it loading.
• --approve-mcps approves every configured server for one run. Useful in CI, where nobody is there to click, and a reason to keep the project’s mcp.json short.

Permissions

What the agent may do without asking is a list of allow and deny rules. Cursor’s permissions reference↗ (opens in a new tab) puts them in ~/.cursor/cli-config.json for your user or .cursor/cli.json in a project; only permissions can be set at project level. There are five kinds: Shell(command), Read(path or glob), Write(path or glob), WebFetch(domain) and Mcp(server:tool). Deny rules win over allow rules.

{
  "permissions": {
    "allow": [
      "Shell(git)",
      "Shell(npm)",
      "Read(src/**)",
      "Write(src/**)",
      "Mcp(fenbs:*)"
    ],
    "deny": [
      "Shell(rm)",
      "Read(.env*)",
      "Write(**/.env*)",
      "Mcp(fenbs:fenbs_delete_item)"
    ]
  }
}

Two broader switches sit above the list. -f, --force and its alias --yolo allow commands unless a rule denies them; --sandbox enabled or agent sandbox enable runs commands in a sandbox with read and write access to the workspace. Keep --force for disposable environments, and let the deny list carry the lines that must never be crossed. Deny rules are the ones that still apply when --force is on.

Print mode and output formats

-p or --print runs one prompt, prints the result and exits. According to Cursor’s headless guide↗ (opens in a new tab), changes in print mode are only proposed unless you add --force, so a script that should edit files says so explicitly. --trust trusts the workspace without a prompt, and only works in headless mode.

• text (the default) prints the final answer only.
• json prints one object when the run succeeds, with result holding the full answer, plus session_id, is_error and duration_ms.
• stream-json prints newline-delimited events as the run goes, one line per assistant message and tool call, ending with a result event. Add --stream-partial-output for the text as it is written.
• On failure the process exits non-zero and writes the error to stderr; json then prints no object, so check the exit code first.

agent -p --output-format json "List the TODO comments in src/ as a bullet list" \
  | jq -r '.result'

Two more routes exist for tools rather than scripts. agent create-chat returns the ID of a new empty chat, so a wrapper can start a conversation and then send each prompt to it with --resume <chat id>, keeping one thread across several print-mode calls. And agent acp runs the CLI as an Agent Client Protocol server over stdio, speaking JSON-RPC, for editors and custom clients that want Cursor’s agent behind their own interface. Cursor describes ACP as an advanced option; for everyday terminal work, plain agent is the one to use.

Cursor CLI in CI

Cursor’s GitHub Actions page↗ (opens in a new tab) installs the CLI in a step, adds it to the path, and passes the API key from a repository secret:

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

- name: Update the docs
  env:
    CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
  run: |
    agent -p --force "Update docs/ for the changes in this pull request.
    Do not create branches, commit, push or comment. Only edit files."

Cursor describes two approaches: full autonomy, where the agent also commits, pushes and comments, and restricted autonomy, which it recommends for production workflows. In the restricted version the agent only edits files, and later workflow steps do the Git and pull request work deterministically. Back the prompt with a .cursor/cli.json that denies Shell(git) and Shell(gh), so the rule holds even if the prompt is ignored.

The work list outside the terminal

A terminal session ends, and a CI run leaves only a log. The task the agent was working on, and what it found, is better kept where the next session and the next person will look. With fenbs in mcp.json, the agent can read the task in Next Up, move it to In Progress, comment what it changed and move it to Completed, under your role and with its name on every change in History. Interactively it signs in through the browser; a CI job uses a token issued by hand under Settings, with a name, the scopes you tick and an optional expiry, sent as the Bearer header above. The Mcp(...) rules then narrow what it may call. Setup is on Cursor on fenbs.