SOP-013: CLI Installation

Document Control

Field	Value
SOP ID	SOP-013
Version	1.0
Status	Active
Last Updated	2024-12

Purpose

This SOP provides detailed instructions for installing and using Cursor CLI (cursor-agent) for terminal-based AI coding assistance.

Scope

CLI installation
Interactive mode
Non-interactive/headless mode
Session management

Prerequisites

macOS, Linux, or Windows (WSL)
Internet connection
Cursor account

Procedure

CLI Overview

Mode	Command	Features
Interactive	`cursor-agent`	Conversational interface, review/approve changes, persistent context
Non-Interactive	`cursor-agent -p "prompt"`	Single-shot execution, CI/CD friendly, structured output

Step 1: Install CLI

One-liner Installation:

bash

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

This downloads the cursor-agent binary to ~/.local/bin/.

Step 2: Configure PATH

If cursor-agent isn't found after install:

For Bash:

bash

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

For Zsh:

bash

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

Step 3: Verify Installation

bash

cursor-agent --version

Should output version number like cursor-agent 1.x.x

Step 4: Start Interactive Session

bash

# Start in current directory
cursor-agent

# Start with initial prompt
cursor-agent "explain the main.go file"

# Start in specific directory
cd /path/to/project && cursor-agent

Interactive Session Commands:

Action	How To
Send message	Type and press Enter
New line	Shift+Enter
Cancel	Ctrl+C
Exit	Type `exit` or Ctrl+D

Step 5: Non-Interactive Mode

For scripts, CI/CD, and automation:

bash

# Basic usage
cursor-agent -p "find and fix security issues"

# Specify model
cursor-agent -p "review code for performance" --model "gpt-5"

# Include git changes for review
cursor-agent -p "review these changes" --output-format text

# JSON output for parsing
cursor-agent -p "list all functions" --output-format json

Step 6: Session Management

List Previous Sessions:

bash

cursor-agent ls

Resume Latest Session:

bash

cursor-agent resume

Resume Specific Session:

bash

cursor-agent --resume="session-id-here"

Shell Mode

For continuous terminal interaction:

bash

cursor-agent shell

Shell Mode Features:

Persistent context across commands
Command history
Rule integration
MCP support

MCP in CLI

Use MCP servers from the command line:

bash

# List available MCP tools
cursor-agent --list-mcp-tools

# Configure MCP in project
# Create .cursor/mcp.json as described in SOP-012

GitHub Actions Integration

Example Workflow:

yaml

name: Code Review
on: pull_request

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Cursor CLI
        run: curl https://cursor.com/install -fsS | bash

      - name: Review Changes
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
        run: |
          ~/.local/bin/cursor-agent -p "Review this PR for security issues" \
            --output-format text > review.txt

      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.txt', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: review
            });

CLI Reference

Command	Description
`cursor-agent`	Start interactive session
`cursor-agent "prompt"`	Start with initial prompt
`cursor-agent -p "prompt"`	Non-interactive single prompt
`cursor-agent ls`	List sessions
`cursor-agent resume`	Resume latest session
`cursor-agent shell`	Start shell mode
`cursor-agent update`	Update to latest version
`cursor-agent --version`	Show version
`cursor-agent --help`	Show help

Common Flags:

Flag	Description
`-p, --prompt`	Prompt to execute
`--model`	AI model to use
`--output-format`	Output format (text, json)
`--resume`	Resume session by ID

Updating CLI

bash

# Auto-update (happens automatically)
# Or manually:
cursor-agent update
# or
cursor-agent upgrade

Verification Checklist

[ ] CLI installed successfully
[ ] cursor-agent --version works
[ ] Interactive session starts
[ ] Can send prompts and receive responses
[ ] Session resume works
[ ] Non-interactive mode executes

Troubleshooting

Issue	Solution
Command not found	Add ~/.local/bin to PATH
Permission denied	Check file permissions
Network error	Check internet, firewall
Session not found	Use `cursor-agent ls` to find ID
Authentication failed	Re-run install script

SOP-013: CLI Installation ​

Document Control ​

Purpose ​

Scope ​

Prerequisites ​

Procedure ​

CLI Overview ​

Step 1: Install CLI ​

Step 2: Configure PATH ​

Step 3: Verify Installation ​

Step 4: Start Interactive Session ​

Step 5: Non-Interactive Mode ​

Step 6: Session Management ​

Shell Mode ​

MCP in CLI ​

GitHub Actions Integration ​

CLI Reference ​

Updating CLI ​

Verification Checklist ​

Troubleshooting ​

See Also ​

SOP-013: CLI Installation

Document Control

Purpose

Scope

Prerequisites

Procedure

CLI Overview

Step 1: Install CLI

Step 2: Configure PATH

Step 3: Verify Installation

Step 4: Start Interactive Session

Step 5: Non-Interactive Mode

Step 6: Session Management

Shell Mode

MCP in CLI

GitHub Actions Integration

CLI Reference

Updating CLI

Verification Checklist

Troubleshooting

See Also