Part of the Cursor AI Complete Guide (2026) series. Bring Cursor Agent capabilities into your terminal, SSH sessions, and automation pipelines.

Why the Cursor CLI Matters

Many developers think Cursor is only a graphical IDE. The Cursor CLI brings the same Agent capabilities into scripts, SSH sessions, and automation workflows.

Install:

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

Start the Agent:

agent

CLI Modes

ModePurpose
PlanDesign an approach before coding
AskExplore code without making changes
AgentExecute coding tasks
HeadlessAutomation and CI
graph LR
    subgraph CLI Modes
        PL[Plan] --> AG[Agent]
        AS[Ask] --> AG
        AG --> HL[Headless]
    end
    PL -->|Clarifies requirements| AG
    AS -->|Read-only exploration| AG
    HL -->|Scripts & CI| OUT[Automated Output]

Plan Mode encourages the Agent to clarify requirements before editing code.

Ask Mode is useful for repository exploration and explanations without file changes.

Agent Mode executes multi-step coding tasks with tool access.

Headless Mode runs without the full editor UI — ideal for pipelines.

Useful CLI Commands

agent

Start the Cursor Agent interactively.

/model

Switch AI model.

/plan

Create an implementation plan before coding.

/ask

Inspect code without modifying it.

/resume

Resume previous conversations.

/mcp list

Browse configured MCP servers.

/usage

Display Cursor usage statistics.

Headless Automation

One of the most powerful CLI features is headless execution:

agent -p "Generate API documentation for this project."
flowchart LR
    T[Trigger: Cron / GitHub Action] --> H[Headless Agent]
    H --> R[Read Repository]
    H --> G[Generate Output]
    G --> F[Write Files / PR Comment]

This enables integration with:

  • CI/CD pipelines
  • GitHub Actions
  • Scheduled documentation updates
  • Security review workflows
  • Automated refactoring tasks

Example: GitHub Actions

- name: Cursor doc update
  run: |
    agent -p "Update CHANGELOG.md with commits since last tag."

Adjust to your environment and approval requirements — many teams run headless agents on dedicated runners with scoped credentials.

Productivity Workflow with CLI

flowchart TD
    A[SSH into Server] --> B[agent]
    B --> C[/plan Feature X]
    C --> D[Review Plan]
    D --> E[Agent Implements]
    E --> F[Run Tests]
    F --> G[Commit]

Developers on remote machines, containers, or minimal environments can use the CLI without the full desktop editor.

CLI vs IDE Agent

AspectIDE AgentCLI Agent
Visual diff reviewExcellentLimited
Interactive editingIncludedIncluded
SSH / remote serversNot includedIncluded
CI/CD automationNot includedIncluded
MCP accessIncludedIncluded
Background cloud handoffIncludedIncluded (with &)

Use the IDE for day-to-day feature work. Use the CLI for automation, remote servers, and scripted tasks.

Best Practices

  1. Start with Plan mode for non-trivial tasks — cheaper and clearer than fixing bad edits.
  2. Use Ask mode to onboard to unfamiliar repos before changing code.
  3. Scope headless prompts narrowly — one task per invocation.
  4. Combine with Rules — CLI Agent reads the same .cursor/rules/ as the IDE.
  5. Monitor usage with /usage on heavy automation jobs.

Common Mistakes

  • Running headless agents with overly broad prompts in CI
  • Skipping test runs after CLI-generated changes
  • Forgetting MCP auth on headless runners
  • Using Agent mode when Ask mode would suffice (wastes usage)

Frequently Asked Questions

How do I install Cursor CLI?

Run curl https://cursor.com/install -fsS | bash and follow platform-specific instructions from Cursor docs.

Can the CLI edit files?

Yes, in Agent mode. Ask mode is read-only.

Does CLI work with MCP?

Yes. Configure MCP servers once; both IDE and CLI can use them.

Is headless mode available on all plans?

Check current Cursor pricing — Agent usage limits apply to CLI the same as the IDE.

Last reviewed: July 2026