What is the Cursor CLI?
The Cursor CLI is Cursor's coding agent in your terminal, run with the agent command. The Cursor CLI docs say it "lets you interact with AI agents directly from your terminal to write, review, and modify code." You can chat with it interactively, or run it non-interactively in scripts and CI pipelines with print mode.
It is the same agent as the one in the editor, with the same Agent, Plan and Ask modes, the same rules and the same MCP servers. If you are new to how that agent works, start with our Cursor Agent guide.
How do you install and sign in?
Install with one command, per the installation page:
# macOS, Linux and Windows (WSL)
curl https://cursor.com/install -fsS | bash
# Windows (native), in PowerShell
irm 'https://cursor.com/install?win32=true' | iex
# check it worked
agent --version
If your shell cannot find agent, add ~/.local/bin to your PATH in ~/.bashrc or ~/.zshrc, as the installation page shows. The CLI auto-updates by default; run agent update to update by hand.
Then sign in. The browser flow is the recommended method:
agent login # opens your browser
agent status # shows whether you are signed in
agent logout # clears stored credentials
For scripts and CI, use an API key instead. Generate one in the Cursor Dashboard under API Keys, then set CURSOR_API_KEY or pass --api-key. See the authentication reference for details, including NO_OPEN_BROWSER=1 for machines without a browser.
How do you use the CLI interactively?
Run agent to start a session, or pass a first prompt:
agent
agent "refactor the auth module to use JWT tokens"
The CLI asks you to approve (y) or reject (n) each terminal command before it runs. When the agent finishes editing, press Ctrl+R to review changes; press i to add follow-up instructions and the arrow keys to move through files.
Modes. The CLI supports the same modes as the editor:
| Mode | What it does | How to switch |
|---|---|---|
| Agent | Full access to all tools | Default |
| Plan | Designs the approach first, with clarifying questions | Shift+Tab, /plan, --plan, --mode=plan |
| Ask | Read-only exploration, no edits | /ask, --mode=ask |
There is also /debug for Debug mode, and any skill can run as a Custom Mode: pick it from the / menu and press Option+Enter.
Useful habits:
- Type
@to add files and folders to context. - Run
/summarizeto free up context in a long session. - Press Shift+Enter for a newline (Ctrl+J in tmux).
- Use
/shellto run quick commands without leaving the chat. Shell Mode commands time out after 30 seconds, so it is for short, non-interactive commands. - Prepend
&to a message to hand the conversation to a Cloud Agent that keeps running while you are away.
Sessions. Pick up where you left off:
agent ls # list previous chats and pick one
agent resume # resume the latest chat
agent --continue # continue the previous session
agent --resume="chat-id" # resume a specific chat
Worktrees. Pass -w or --worktree [name] to run the agent in a new Git worktree under ~/.cursor/worktrees/<reponame>/<name>, so it does not touch your current checkout.
Which commands and flags matter most?
The parameters reference lists everything. These are the ones you will use most:
| Flag or command | What it does |
|---|---|
-p, --print |
Non-interactive print mode for scripts and CI |
--output-format |
text (default), json or stream-json; only with --print |
--stream-partial-output |
Streams text deltas; with --print and stream-json |
-f, --force / --yolo |
Force allow commands unless explicitly denied |
--model <model> |
Choose a model; agent models lists yours |
--mode <mode> |
plan or ask |
--sandbox <mode> |
enabled or disabled |
--trust |
Trust the workspace without prompting (headless only) |
--approve-mcps |
Approve all MCP servers automatically |
--workspace <path> |
Set the workspace directory |
agent mcp list |
List configured MCP servers and their status |
agent generate-rule |
Create a Cursor rule with interactive prompts |
The CLI reads the same mcp.json as the editor, so servers you set up in Cursor work here too. Our Cursor MCP guide covers that file. It also applies rules from .cursor/rules and reads AGENTS.md and CLAUDE.md at the project root, so the rules you already wrote carry over.
How do you run the Cursor CLI headless?
Headless use means print mode: agent -p "prompt". It prints the response and exits, which makes it scriptable.
# a question, plain text answer
agent -p "What does this codebase do?"
# let it change files
agent -p --force "Refactor this code to use modern ES6+ syntax"
# structured output for scripts
agent -p --output-format json "Summarize the open TODOs in src/" | jq -r '.result'
The headless guide is clear on one point: combine --print with --force to modify files, because "Without --force, changes are only proposed, not applied." Print mode has access to write and shell tools, and --force together with your allow and deny rules decides what runs without a prompt.
Output formats. text returns only the final answer. json emits one object when the run succeeds, with the answer in result plus session_id and timing fields. On failure the process exits non-zero and writes to stderr instead. stream-json emits one JSON line per event, ending with a result event, which suits progress bars and logs. Details are in the output format reference.
Images and files. To give the agent an image in a script, put the file path in the prompt, such as agent -p "Describe this screenshot: ./screenshot.png". The agent reads it with its file tools.
How do you control what the CLI is allowed to do?
Permissions live in ~/.cursor/cli-config.json for every project, or <project>/.cursor/cli.json for one project. Only permissions can be set per project; other settings are global. Each rule is a typed token:
{
"permissions": {
"allow": ["Shell(git)", "Read(src/**/*.ts)", "Write(docs/**)", "WebFetch(docs.github.com)"],
"deny": ["Shell(rm)", "Read(.env*)", "Write(**/*.key)"]
}
}
The token types are Shell(command), Read(path), Write(path), WebFetch(domain) and Mcp(server:tool). Globs are supported, and deny rules win over allow rules. The permissions reference has the full syntax. For extra isolation, --sandbox enabled or /sandbox runs commands in a sandbox with optional network access.
How do you use the Cursor CLI in GitHub Actions?
The GitHub Actions page shows the basic setup:
- 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
This official snippet adds $HOME/.cursor/bin to the runner's PATH, while the installation page tells local users to add ~/.local/bin. If a later step cannot find agent, check where the installer put it on your runner.
Store the key with gh secret set CURSOR_API_KEY --repo OWNER/REPO --body "$CURSOR_API_KEY" or in the repository's Actions secrets settings.
Cursor describes two autonomy levels. Full autonomy lets the agent create branches, commit, push and comment on PRs itself: simpler, but it needs more trust. For production CI, Cursor recommends the restricted approach: tell the agent to only modify files, deny Shell(git) and Shell(gh) in permissions, and run commits, pushes and PR comments as separate, deterministic workflow steps. That keeps the risky actions auditable.
How does the Cursor CLI compare with other terminal agents?
If you use more than one tool, the shape is familiar. Codex CLI has codex exec for non-interactive runs, covered in our Codex CLI guide, and Claude Code has claude -p, covered in the Claude Code headless guide. The Cursor CLI's main draw is sharing configuration with the Cursor editor: the same rules, MCP servers, skills and modes in both places.
Where should your CLI prompts live?
Headless runs make prompts into code: the same review or refactor instruction runs again and again. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, with {{name}} blanks for the parts that change between runs. To turn a prompt you keep reusing into a skill, the free SKILL.md generator builds the SKILL.md in your browser.