Skip to content
Cursor Handbook

Install the Cursor CLI

One command on macOS, Linux and WSL, one on native Windows. The binary is called agent and lands in ~/.local/bin, which is where most first-run problems come from.

  • No editor required
  • Auto-updates by default
  • ~/.local/bin

Checked against cursor.com on 25 September 2026

The install commands

macOS, Linux, Windows (WSL)
$ curl https://cursor.com/install -fsS | bash
Windows (native PowerShell)
> irm 'https://cursor.com/install?win32=true' | iex
Check it worked
$ agent --version

What the three steps actually do

  1. 01

    Run the installer

    One command on every Unix-like platform, including Windows under WSL. Native Windows uses the PowerShell variant below.

  2. 02

    Put the binary on your PATH

    The installer writes to ~/.local/bin. If your shell does not already search there, the next step fixes it permanently.

  3. 03

    Authenticate

    `agent login` opens a browser to link the CLI to your existing Cursor account. On a headless machine, set CURSOR_API_KEY instead.

Fixing the PATH

The installer puts agent in ~/.local/bin. Several Linux distributions already search that directory; macOS generally does not. If the version check above printed command not found, add it yourself and reload the shell.

# zsh, the default shell on macOS
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Two failure modes are worth naming, because they look identical from the outside. If ls ~/.local/bin/agent shows nothing, the install failed and re-running it is the fix. If the file is there but the command is not found, the export went into a file your shell does not read. On macOS, login shells read ~/.zprofile while interactive shells read ~/.zshrc, and a line in the wrong one does nothing.

Signing in

agent login opens a browser and links the CLI to the account you already use in the editor. It does not consume an extra seat, and it does not come with a separate usage allowance. Confirm which account you landed on with agent status, which is worth doing if you have both a personal and a work account.

On a machine with no browser, a build runner or a container, use an API key instead. Both of these work:

export CURSOR_API_KEY=...
agent -p "run the test suite and summarise failures"

# or per-invocation
agent --api-key "$CURSOR_API_KEY" -p "..."

Keep the key in your CI provider's secret store. It authenticates an agent that can write files and execute shell commands, so it deserves the same care as a deploy token.

Updating

The CLI tries to auto-update so you stay on the current build. When you want to force it, either of these works:

agent update     # from the shell
/update          # from inside a session

In containers, pin behaviour by reinstalling at image build time rather than relying on the updater at runtime, otherwise the version changes underneath a pipeline that was green yesterday.

Making the terminal behave

Multi-line prompts are the first friction most people hit. Pressing Enter sends the message, and the key combination for a newline varies by terminal. Running /setup-terminal once configures the keybinding for the terminal you are in. It is a thirty-second fix that saves a lot of accidentally-sent half-written prompts.

agent install-shell-integration adds integration to ~/.zshrc, and agent uninstall-shell-integration removes it again cleanly, which is the right way to back out rather than editing the file by hand.

Commands transcribed from the official installation page on 25 September 2026.

Frequently asked questions

What is the Cursor CLI install command?
On macOS, Linux and Windows under WSL: curl https://cursor.com/install -fsS | bash. On native Windows in PowerShell: irm 'https://cursor.com/install?win32=true' | iex.
Where does the Cursor CLI install to?
Into ~/.local/bin. That directory is on the PATH by default on many Linux distributions but often is not on macOS, which is why a fresh install can leave `agent` reporting command not found.
Why does my shell say `agent: command not found`?
Almost always a PATH problem rather than a failed install. Check that ~/.local/bin/agent exists. If it does, append ~/.local/bin to your PATH in ~/.zshrc or ~/.bashrc and reload the shell. Opening a new terminal tab is not always enough, because the export has to be in the file the shell actually reads.
Do I need the Cursor editor installed to use the CLI?
No. The CLI is a standalone binary and works on a machine with no desktop environment at all, which is the point of it. The one command that depends on the editor is /open, which opens the repository's Git root in Cursor.
How do I update the Cursor CLI?
It tries to auto-update by default. To update on demand, run `agent update` from the shell, or `/update` from inside an interactive session.
How do I install the Cursor CLI without piping curl to bash?
Fetch the script first and read it before running it: curl -fsSL https://cursor.com/install -o install.sh, inspect the file, then bash install.sh. The end state is identical, and on shared or production machines it is the more defensible choice.
Can I install the Cursor CLI in a Docker image or CI runner?
Yes. Run the install command in the image build, add ~/.local/bin to PATH, and authenticate with the CURSOR_API_KEY environment variable rather than `agent login`, since there is no browser to complete an interactive sign-in.

Keep reading