Cursor Agent CLI: The Complete Guide

Cursor is best known as an editor, but the same agent that powers its sidebar also ships as a standalone command-line tool. The Cursor Agent CLI runs in any terminal — over SSH, in tmux, on a headless box — and that changes what it's useful for: scripted runs, CI experiments, and long agent sessions on machines you aren't sitting in front of.

This guide covers installation, the interaction modes, session management, and permissions, plus how to keep an eye on runs when you leave the terminal behind.

Installation

Cursor distributes the CLI through an install script:

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

The script places a cursor-agent binary on your PATH. Verify with:

cursor-agent --version

On first run you'll authenticate against your Cursor account — the CLI shares your subscription and model access with the editor. You can also log in explicitly:

cursor-agent login
cursor-agent status   # check auth + version

The two ways to run it

Interactive mode

Run cursor-agentinside a repository and you get a terminal UI much like the editor's agent panel: you type a task, the agent plans, edits files, proposes shell commands, and asks before doing anything destructive.

cd ~/code/my-app
cursor-agent "add input validation to the signup endpoint"

You stay in the loop the whole time: every command the agent wants to run is shown first, and file edits are visible as diffs.

Print (non-interactive) mode

With -p / --print the agent runs without a UI and writes its result to stdout — the mode you want for scripts and automation. Combine it with an output format for machine-readable results:

cursor-agent -p "summarize the failing tests and suggest fixes" \
  --output-format text

Because nobody is present to click "approve", print mode is where permission flags matter most — more on that below.

Sessions: resume where you left off

Every run is a session with an ID. You can list previous sessions and pick one up with its context intact:

cursor-agent ls          # list sessions
cursor-agent resume      # continue the most recent one

This matters for long tasks: you can start a refactor at the office, kill the terminal, and resume the same conversation from a laptop at home — the agent keeps its plan and history.

Choosing a model

The CLI exposes the same model list as the editor. Pick one per run with --model:

cursor-agent --model <model-name> "migrate the config loader to zod"

Model names change often enough that hardcoding them in scripts is a maintenance hazard; run cursor-agent --help or check your Cursor settings for what's currently available.

Permissions and safety

By default the agent asks before running shell commands or making risky changes. For unattended runs there are flags that widen the sandbox — most notably --force, which auto-approves command execution. Treat that the way you'd treat sudo in a cron job:

• Use it only in disposable environments (containers, CI runners, scratch clones).
• Keep the working tree committed first, so git diff shows you everything the agent did.
• Prefer approval-by-human for anything touching credentials, deploys, or migrations.

The gap: who watches a long run?

The CLI's biggest strength — running for a long time without you — is also its awkward spot. An agent mid-refactor will periodically stop and wait for an approval. If you've left the desk, the run just sits there.

There are classic answers (tmux + SSH from a phone terminal works, badly) and there's the approach we build: Remoot bridges your IDE and its agent workflows to a mobile app, so approval prompts arrive as push notifications and you answer them with a tap instead of thumb-typing into an SSH session. The step-by-step setup is in How to Run Cursor Agent From Your Phone.

Cheat sheet

cursor-agent                      # interactive session in cwd
cursor-agent "task..."            # start with a prompt
cursor-agent -p "task..."         # non-interactive, print result
cursor-agent --model <name> ...   # pick a model
cursor-agent ls                   # list sessions
cursor-agent resume               # resume latest session
cursor-agent login / logout       # auth
cursor-agent status               # auth + version info
cursor-agent update               # self-update

If you use the CLI seriously, the pattern that sticks is: interactive mode at the desk, print mode in scripts, and something watching the long runs when you're neither place.