Guide

How to install and use cursor-agent (macOS & Windows)

Most people meet Cursor as an editor — a VS Code fork with an AI agent baked into the sidebar. But Cursor also ships a separate command-line agent that runs entirely in your terminal, no editor window required. It's the same kind of tool as Claude Code or Codex: you point it at a repo, describe a task, and it reads files, writes edits, and runs commands. People call it cursor-agent, and it's handy when you live in the terminal, want to drive an agent over SSH, or wire one into a script.

Getting it running takes a couple of minutes. The friction is usually one thing: Cursor installs the CLI through its own script rather than npm, and that exact command shifts between releases, so it's worth pulling from the source. Here's the whole path on macOS and Windows, plus how it differs from running Claude Code once it's up.

What cursor-agent actually is

cursor-agent is Cursor's coding agent unbundled from the editor and shipped as a standalone binary. It runs the same agent loop you get inside the Cursor app — model access, file edits, command execution, your project rules — but in a plain terminal session. A few things to know up front:

• It's a separate install. Having the Cursor editor on your machine doesn't give you the CLI, and vice versa. They're distinct downloads.
• It uses your Cursor account. Auth and model usage run through the same Cursor login you'd use in the editor, so your plan and limits carry over.
• The command is agent. Cursor installs the binary under the name agent (people still call the tool "cursor-agent"), so that's what you type to run it.
• It's scriptable. Beyond the interactive REPL, there's a non-interactive print mode for piping it into shell scripts and CI.

Install on macOS

Cursor distributes the CLI with an install script rather than a package manager. The current flow is a one-line curl piped into your shell:

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

That drops the binary into ~/.local/bin. If your shell can't find agent afterward, that directory isn't on your PATH — add ~/.local/bin to your PATH in ~/.zshrc and reopen the terminal. Then confirm it landed:

agent --version

Piping a script straight into bash is convenient but worth a glance first — if you'd rather inspect it, fetch the URL in a browser before running it. Because Cursor changes this command between releases, grab the current one from the official CLI install docs rather than trusting a tutorial that might be stale.

Install on Windows

On Windows the same idea runs through PowerShell instead of curl. The current command fetches the installer and pipes it into iex:

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

Run that in PowerShell or Windows Terminal, then check it with agent --version. If you work primarily inside WSL, treat that distro like macOS and use the curl ... | bash command from inside the Linux shell instead — pick whichever environment your repos actually live in so paths line up. As with macOS, confirm the exact command against Cursor's docs before pasting, since the query string and host can change.

Sign in to your Cursor account

The CLI doesn't work anonymously — it needs a Cursor account. After installing, log in:

agent login

That opens your browser, you authenticate with Cursor, and the credentials get stored locally so you only do it once. You can check the result anytime with agent status, which shows whether you're authenticated and which account you're on. If you're automating in CI where no browser exists, Cursor also supports an API key via the CURSOR_API_KEY environment variable instead of the interactive login — the authentication docs cover that path.

Your first run in a repo

Change into a project you don't mind it editing, then start the interactive session:

cd my-project
agent

Describe a task in plain English — "add input validation to the signup form and a test for it." The agent reads the relevant files, proposes changes, and before it runs any terminal command it stops to ask you to approve (y) or reject (n). You can also pass a prompt straight in as an argument, or run a one-shot non-interactive job with the print flag, which is what makes it easy to script:

agent -p "summarize what this service does" --output-format text

Like any agent, start in a git repo with a clean working tree so you can git diff exactly what it changed and roll back if you don't like it. In print mode the agent only proposes edits by default — it needs an explicit flag (--force) before it will actually write files, which is a sensible guardrail for the first few runs. If you've thought about vibe coding, this is the loop you'll be working in.

How it differs from Claude Code

If you've already installed Claude Code, cursor-agent will feel familiar — same describe-edit-run rhythm — but a few things diverge:

• Install path. Claude Code installs via npm i -g; cursor-agent uses Cursor's own shell script. No Node dependency for the Cursor CLI.
• Account and models. Claude Code signs into Anthropic (a Claude plan or Console API billing) and runs Anthropic's models. cursor-agent signs into Cursor and can route across the models Cursor offers, on your Cursor plan.
• Ecosystem ties. cursor-agent shares rules and config with the Cursor editor, so a setup you've tuned in the app carries to the terminal. Claude Code leans on its own config and hooks for events.

Neither is strictly better — it usually comes down to which account you already pay for and which models you prefer. The deeper trade-offs are their own topic in Claude Code vs Cursor. The good news: both speak the same terminal, so nothing stops you from running them side by side and even running multiple agents at once on different tasks.

Where Backgrind fits

Once cursor-agent is doing real work, a single task can run for minutes and then stop to ask for approval or finish while you've tabbed away — and the terminal ends up buried. Backgrind wraps the same agent CLI you just installed, with your login and config, in an always-on-top overlay that floats over whatever you're doing and flashes only when it needs a decision or completes — so you can stop babysitting the terminal. There's a live demo if you want to see it in motion.