Cursor CLI Guide: Install, Agent Mode and ACP

By CodeAgentSwarm Team · Updated August 16, 2026

Cursor Agent CLI can run as a first-class agent inside CodeAgentSwarm through the official Agent Client Protocol (ACP). You keep your Cursor account, models, rules, skills and MCP configuration. CodeAgentSwarm adds a supervised Chat interface for streaming responses, tool activity, permission requests and cancellation. The important command is cursor-agent. CodeAgentSwarm does not use the generic agent alias because another installed CLI can own that name. Cursor IDE and Cursor Agent CLI belong to the same product, but they are different interfaces: the IDE is the editor, while cursor-agent works from a terminal or an ACP client.

What the Cursor ACP integration does

CodeAgentSwarm starts cursor-agent acp over stdio and speaks JSON-RPC. Cursor remains the model and tool provider. The app is the client that presents each turn, tool call and decision in the same workspace as Claude Code, Codex CLI, OpenCode, Kimi Code, Antigravity CLI and Grok Build.

Stream text and tool activity as Cursor produces it
Approve or reject command permissions without blocking the session
Cancel an active answer
Choose Cursor Agent, Plan or Ask mode
Choose models exposed by the active Cursor session
Attach images when the installed Cursor version advertises image support

Install and authenticate Cursor Agent CLI

CodeAgentSwarm detects cursor-agent explicitly and can run Cursor's official installer for macOS, Linux or native Windows when the CLI is missing.

bash

# macOS or Linux
curl https://cursor.com/install -fsS | bash

# Native Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex

cursor-agent --version
cursor-agent login
cursor-agent status

For CI or another non-interactive environment, Cursor also accepts CURSOR_API_KEY. In normal desktop use, the browser login uses your existing Cursor account and its subscription or usage.

On Windows, CodeAgentSwarm downloads Cursor's official PowerShell installer and verifies the native cursor-agent.cmd before starting Chat. It never falls back to a generic agent command.

Use Agent, Plan and Ask mode

Choose the interaction before sending a prompt. Agent can inspect and change the project, Plan prepares an implementation approach before editing, and Ask is the read-only choice for explanations and investigation. CodeAgentSwarm preserves that selection when you reopen the Chat or move a session from the terminal view into Chat.

The same Chat can display Cursor model choices and image attachments when the connected version advertises those ACP capabilities. Responses, tool calls and permission requests appear as they happen, and Stop cancels the active turn.

MCP, rules, skills and Cursor extensions

CodeAgentSwarm reads user and project MCP servers from .cursor/mcp.json without modifying either file. Project entries override same-named user entries, and the merged servers are sent through ACP's native mcpServers field. Cursor rules and skills remain owned by Cursor.

The ACP adapter also understands Cursor-specific requests for questions, plans, todos, delegated tasks and generated images. They become native CodeAgentSwarm timeline items instead of raw JSON.

Keep installation, mode selection, MCP and Skills on this page. For focused workflows, continue with the guides to Cursor CLI conversation history, running a Cursor Agent swarm or using Cursor CLI on Windows.

Conversation history and version compatibility

Cursor versions differ in ACP resume support. CodeAgentSwarm enables ACP session/load only when the handshake reports agentCapabilities.loadSession: true. That avoids a resume button that could never work.

bash

cursor-agent update
# cursor-agent upgrade works too

An older Cursor CLI can still start a new Chat. CodeAgentSwarm shows an update instruction and does not save that Chat as resumable until the capability is available.

The dedicated history and resume guide explains what changes when an older ACP version reports loadSession: false.

Run Cursor Agent beside other coding agents

Create a Cursor Chat for one task and start Codex, Claude Code or another supported CLI for the next. Each agent gets its own session and project context while CodeAgentSwarm keeps status, permissions, task progress and history visible in one place.

This is useful when you want Cursor models and project rules without moving every task into the Cursor editor, or when a mixed-agent workflow needs one shared supervision surface.

See the Cursor Agent swarm guide for isolation and task-splitting patterns, or compare the workflow in Cursor CLI vs Claude Code.

FAQ

Yes. It launches the official cursor-agent binary in ACP mode over stdio and JSON-RPC.

Yes. Sign in with cursor-agent login or provide CURSOR_API_KEY. Authentication and usage remain with Cursor.

Yes. CodeAgentSwarm reads user and project .cursor/mcp.json files without modifying them and sends the merged servers through ACP.

Only when the installed Cursor CLI advertises ACP loadSession support. Older versions can start new chats but show an update instruction instead of a broken resume action.

Yes. CodeAgentSwarm can install and run Cursor Agent natively on Windows with Cursor's official PowerShell installer.

Run Cursor Agent beside your other coding agents with streaming Chat, visible permissions, project history and one place to supervise the work.

Download it freemacOS & Windows

Cursor CLI vs Claude Code: Which Fits Your Workflow?

Cursor CLI and Claude Code are terminal coding agents from different providers. Both can inspect a project, use tools and help complete coding tasks, but they belong to different account, model and configuration ecosystems.

Read guide

View all guides