Installing Cursor CLI: a basic guide

Goal

By the end you'll have Cursor CLI installed, authenticated with your Cursor account, and a first agent session running against a real project, both interactively and in headless mode.

Cursor CLI brings Cursor's agent to the terminal. It's the same model access and agent behavior as the editor, callable from a shell: interactive sessions, headless runs for scripts and CI, plan/ask/agent modes, and a configurable sandbox. The installed binary is cursor-agent (the docs also refer to it as agent).

Prerequisites

• macOS, Linux, WSL, or Windows (PowerShell).
• A terminal with permission to install binaries onto your PATH.
• A Cursor account (the CLI shares your Cursor plan and pricing).
• A local project to work on.

This guide covers Cursor CLI as of September 2026.

Steps

1. Install the binary

macOS / Linux / WSL:

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

Windows (PowerShell):

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

The installer places cursor-agent on your PATH. If it isn't found afterward, open a new terminal.

2. Verify the install

cursor-agent --version

Expected check: it prints the installed version. If the shell says "command not found", open a new session so it picks up the updated PATH.

3. Sign in

cursor-agent login

This opens your browser to authenticate with your Cursor account. If the browser won't launch (for example over SSH), set NO_OPEN_BROWSER=1 and open the printed URL manually.

Check the result:

cursor-agent status

Expected check: it shows your account and endpoint. Use cursor-agent logout to sign out.

For CI or automation, skip the browser and use an API key from the Cursor dashboard:

export CURSOR_API_KEY=your_api_key_here
cursor-agent "run the test suite and fix failures"

4. Start an interactive session

cd path/to/your/project
cursor-agent

Or start with a prompt directly:

cursor-agent "explain the auth flow in this project"

Switch modes inside the session: Agent (full access), Plan (design first, no edits), Ask (read-only). Control file-system and command access with /sandbox or the --sandbox <mode> flag. Pick a model with --model (for example --model "gpt-5").

The CLI reads .cursor/rules, plus AGENTS.md and CLAUDE.md at the repo root, and auto-detects mcp.json.

5. Run it headless

For scripts and pipelines:

cursor-agent -p "summarize the changes in the last commit" --output-format text

Use --output-format json for structured output you can parse.

6. Resume and update

cursor-agent ls          # list previous chats
cursor-agent resume      # resume the most recent
cursor-agent update      # update to the latest version

Expected result

• cursor-agent --version prints a version.
• cursor-agent status shows you're signed in.
• cursor-agent opens an interactive session on your project.
• cursor-agent -p "..." --output-format text returns an answer without an interactive prompt.

Troubleshooting

Next step

Add project rules under .cursor/rules so every session starts with the right context, and wire Cursor CLI into GitHub Actions for automated review and fix workflows.