Running Cursor CLI: Install, Modes, and CI Automation

What Cursor CLI Actually Is

Cursor's own CLI documentation defines it in one sentence: it "lets you interact with AI agents directly from your terminal to write, review, and modify code."

The relationship to the editor matters more than the definition. Cursor built its identity as an editor-first tool, and the CLI is not a separate product bolted on afterward; it shares the same account, the same model access, and the same underlying agent as the IDE. What it does not share is the diff view, the inline suggestions, or any of the visual surface that makes the editor an editor.

• Same account, same models - sign in once and both surfaces draw on the same plan and model access.
• Runs anywhere a terminal does - SSH sessions, containers, CI runners, anywhere the editor cannot follow.
• No GUI dependency - every interaction is text in, text out, which is exactly what makes it scriptable.

Installing and Signing In

One command per platform, both downloading and adding the binary to your PATH.

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

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

Interactive use signs in through the CLI's own login flow against your existing Cursor account. Headless and CI use skip that flow entirely and authenticate with an API key instead:

The Three Modes

Every session runs in one of three modes, and the mode decides how much the agent is allowed to touch.

Plan mode is the one worth defaulting to on anything you have not scoped tightly. It costs one extra round trip to review the proposal, and that round trip is cheaper than an Agent-mode run that touched the wrong files.

The Full Command Reference

The flags that actually get used, gathered from Cursor's separate overview and headless documentation pages into one table.

A complete headless invocation combines several of these in one line:

agent -p --force --output-format json \
  "Add input validation to the login form in auth.ts" \
  --model gpt-5

Running It in CI

Cursor's GitHub Actions documentation gives the working shape: install the CLI, export the API key from a repository secret, then call the agent in a run step.

- 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 gpt-5

That example stops at running the agent. It does not gate the pipeline on whether the change actually worked, because the CLI has no way to check that from inside a terminal. The verification section below covers the step this workflow is missing.

The same pattern generalizes past GitHub Actions: any CI system that can export an environment variable and run a shell command can call agent -p the same way.

Cursor CLI vs Other Terminal Agents

Several coding agents now ship a terminal mode. What differs is which product came first.

Neither difference makes one strictly better; they reflect different starting points. A team already living in the Cursor editor gets a terminal mode with zero account switching. A team that wants fine-grained control over delegated work gets more surface in Claude Code's subagent system. Our breakdown of OpenCode vs Claude Code covers a third point on the same map for teams weighing an open-source terminal agent instead, and our Windsurf vs Cursor comparison covers the editor-level choice one level up from the terminal.

Can You Trust What It Says

For code-level claims, usually yes. A -p run that says it added a function, or that a test command exited 0, is reporting something it can actually check: the file on disk, the process exit code.

Delegating a bounded research task and trusting a compressed answer back is a real pattern, and it is worth showing rather than describing. Writing this article required confirming that today's sibling piece on testing AI coding tools did not already cover Cursor CLI specifically, so we spawned a subagent to read it and report back. It returned exactly this:

2) "Cursor CLI" mentioned? No. The term "Cursor CLI" never appears. All
references are to the Cursor editor/IDE and its rules system (.mdc files,
.cursor/rules, chat sessions) - not the terminal/headless cursor.com/cli
product.

3) Covers Cursor CLI installation/flags/modes/CI? No. Zero mention of
Cursor CLI installation, CLI flags, Agent/Plan/Ask modes, or CI/CD usage
of the terminal product. This is entirely open territory for your new
article.

That subagent read a 650-line file and returned seven lines. The compression is trustworthy precisely because the claim it is making, whether a specific string appears in a specific file, is a claim its own tools (Read, Grep) can actually verify.

A UI claim is a different kind of claim. When agent -p "fix the login bug" --force reports success, it is reporting that the diff compiles and, at best, that a test command exited 0. Nothing in that toolchain opened a browser, so nothing confirms the login form actually renders or the fixed field actually accepts input. Kane CLI from TestMu AI is built for that specific gap: a plain-English objective, a real Chrome browser, and a standard exit code (0 passed, 1 failed, 2 environment error, 3 timeout) that a CI step can check the same way it checks any other command's exit status.

npm install -g @testmuai/kane-cli
kane-cli login --username "$LT_USERNAME" --access-key "$LT_ACCESS_KEY"

kane-cli run --agent --headless \
  "sign in with the test account, open the dashboard, assert the page
   shows the account name" \
  --url https://www.testmuai.com/selenium-playground/

Dropped into the same CI job right after the Cursor CLI step, that command is the piece the official GitHub Actions example above stops short of. The Kane CLI introduction documentation covers authentication and the full command reference.

Where the Terminal Half Falls Short

Three limits worth planning around before wiring it into a workflow.

• No visual review surface - the editor's diff view, inline suggestions, and hover previews have no terminal equivalent; --force means the agent edits without you seeing anything but the eventual text summary.
• UI correctness is structurally invisible - covered above, and it is the single most consequential gap for anyone shipping rendered features from a headless run.
• No documented hook or subagent system - Cursor's own CLI documentation does not describe lifecycle hooks or named delegated agents the way Claude Code's does, so fine-grained control over a multi-step run is more limited today.

None of these rule out headless use. They rule out treating a text summary as proof of anything the summary cannot actually see.

Getting Started Checklist

Four steps cover a working setup end to end.

• Install with the platform-specific command above, then sign in interactively once to confirm the account and model access are what you expect.
• Default to Plan mode on anything you have not scoped tightly; drop to Agent mode once the proposal looks right.
• Wire agent -p into one CI job using the GitHub Actions pattern above, with CURSOR_API_KEY as a repository secret.
• Add a browser-verification step immediately after it for any change that touches rendered UI, so the pipeline checks the one thing the agent cannot.

The terminal half of Cursor is genuinely useful for exactly what it is built for: running the same agent somewhere the editor cannot go. Start with the Kane CLI documentation to close the one gap it was never built to cover.