Cursor CLI: the Cursor agent in the terminal, install and setup

Cursor CLI is the same Cursor agent, only in the terminal: you run the agent command, describe a task, and it reads the project, proposes edits and executes commands. It suits work on a server over SSH, scripts and CI. Below are installation, sign-in, modes, running without a dialogue, and an honest comparison with Claude Code and Codex CLI, including what matters about using your own key. We rely on Cursor's official documentation; check flags and names against agent --help, because the CLI updates often.

Installing Cursor CLI

According to the documentation, installation is a single command.

macOS, Linux and Windows through WSL:

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

Windows (PowerShell, native):

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

Running an install script from the network without reading it is a trade-off. If you prefer to be careful, download the file first, read it and only then run it. After installation, check the version:

agent --version

If the command is not found, add ~/.local/bin to PATH as shown in the documentation:

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

(for bash replace ~/.zshrc with ~/.bashrc). Updates: the CLI tries to update itself, and manually it is agent update.

Signing in and the first run

Cursor CLI works through your Cursor account. You sign in with:

agent login

To check the state use agent status (or agent whoami). For scripts and CI where there is no browser, there is the CURSOR_API_KEY environment variable or the --api-key flag: this is a key from your Cursor account, not a key from a third-party gateway.

The first interactive run:

cd ~/projects/my-app
agent

Or straight with a task:

agent "explain the project structure and find the entry points"

The agent models command (or the --list-models flag) shows the models available to your account; you can choose one with the --model flag or the /model command inside a session.

Working modes

The CLI supports the same modes as the editor:

A practical order: start a new task in Plan, approve the plan, then move to Agent. Before running terminal commands, the CLI asks for confirmation (y or n). You can review changes with Ctrl+R, add files and folders to the context with @, and free up context space with /summarize.

Running without a dialogue: scripts and CI

The -p (--print) flag prints the answer to the console and is meant for automation. Important: according to the documentation, in this mode the agent has access to all tools including write and shell, but without --force (or --yolo) edits are only proposed and not applied:

agent -p "find potential performance problems" --output-format text   # analysis only
agent -p --force "add JSDoc comments to src/utils.js"   # applies edits, use deliberately

The output format is set with --output-format: text, json or stream-json (for streaming parsing). In CI set CURSOR_API_KEY as a secret, and enable --force only on an isolated branch or in a sandbox. For safety there is a sandbox mode (--sandbox enabled), and the -w / --worktree flag runs the agent in a separate git worktree so the current directory stays untouched.

If you need a console agent specifically for CI, compare this mode with running Claude Code without a dialogue: there the agent also runs from a script, but reaches the model with your own key.

Configuration and permissions

Settings live in the JSON file ~/.cursor/cli-config.json (on Windows under %USERPROFILE%\.cursor\). At the project level there is .cursor/cli.json, but only for the permissions section. An example that allows ls and echo and forbids rm:

{
  "version": 1,
  "editor": { "vimMode": false },
  "permissions": {
    "allow": ["Shell(ls)", "Shell(echo)"],
    "deny": ["Shell(rm)"]
  }
}

The file must be pure JSON with no comments; on an error the documentation advises renaming it and restarting the CLI. For the remaining parameters (for example the approval mode, sandbox, proxy) see the Cursor CLI configuration reference.

Rules, MCP and instructions

The CLI uses the same rules system as the editor: it reads .cursor/rules and also the AGENTS.md and CLAUDE.md files in the project root. That is handy if the repository already has instructions for other agents (AGENTS.md for Codex, CLAUDE.md for Claude Code). MCP servers are picked up from the same mcp.json as in the editor; you can manage them with agent mcp list, agent mcp list-tools <name> and agent mcp enable <name>.

Cursor CLI, Claude Code and Codex CLI: what differs

All three are console agents, but they are built differently.

The main difference for anyone who wants to pay per token from their own balance: Claude Code and Codex connect to a gateway directly. For Claude Code that is ANTHROPIC_BASE_URL=https://api.zukko.pro and ANTHROPIC_AUTH_TOKEN=fetch_... without /v1 (details in the Claude Code documentation↗); for Codex the provider is given with the address https://api.zukko.pro/v1 (Codex documentation↗). In the Cursor CLI documentation we found no setting for your own API address: the CLI goes through the Cursor account. If per-token payment on a Zukko key matters to you, lean on Claude Code or Codex, or on a key in the Cursor editor (Cursor instructions↗). If you check the current documentation and find that the CLI has gained such a setting, follow it.

In Zukko, the cache-read discount applies to Claude in the Anthropic format, that is, in Claude Code. How Claude Code and Codex differ from each other is covered in the article Codex or Claude Code↗.

FAQ

Can I connect a Zukko key to Cursor CLI?

We found no parameter for your own base URL in the Cursor CLI documentation, so we cannot name a direct method. In the Cursor editor the key is connected in the model settings, and in Claude Code and Codex through their own settings. Check Cursor's current documentation.

How does agent differ from cursor-agent?

The command name in the documentation today is agent. Older materials use another name; rely on agent --help on your machine.

Is it safe to run with --force?

Only in an isolated environment: the flag allows direct file changes without confirmation. Use a separate branch or worktree, sandbox mode and a deny list in the permissions.

Do I need a Cursor subscription for the CLI?

The CLI authorizes through your Cursor account, and the terms of use are defined by your plan. Check the current terms at cursor.com/pricing↗.

If you need a terminal agent on your own key, create a key on the Zukko API keys↗ page and connect it to Claude Code or Codex.