cursor-cli

name	cursor-cli
description	The `agent` CLI — install, interactive modes (Agent / Plan / Ask), headless `-p` mode for CI, GitHub Actions integration, and how it relates to the TypeScript SDK. Use when scripting Cursor in shell pipelines or workflows instead of (or alongside) the SDK.
metadata	{"internal":false,"source":"https://cursor.com/docs/cli/overview"}

cursor-cli

The CLI ships the same agent runtime as the SDK and the editor — pick it when shell-script ergonomics beat a TypeScript program. The SDK is the right choice when you need streaming events, durable cloud reattachment, or programmatic subagents; the CLI is the right choice for one-off prompts and CI gates.

When to use

• One-off prompts in a terminal
• CI / GitHub Actions jobs that operate on a repo
• Headless scripted runs with structured output
• Quick local experiments before promoting to SDK code

Install & auth

• [[references/install]] — curl / PowerShell installers, $HOME/.cursor/bin
• [[references/auth]] — CURSOR_API_KEY, login flow

Interactive

• [[references/interactive]] — agent REPL
• [[references/modes]] — Agent / Plan / Ask, --mode, Shift+Tab
• [[references/sessions]] — agent resume, agent --continue
• [[references/cloud-handoff]] — &-prefix for background

Headless

• [[references/headless]] — -p / --print, --force / --yolo
• [[references/output-formats]] — text / json / stream-json, --stream-partial-output
• [[references/exit-codes]] — $? in shell scripts

CI / automation

• [[references/github-actions]] — workflow snippet, CURSOR_API_KEY secret
• [[references/permissions]] — restricting agent autonomy in CI

Compared to the SDK

• [[references/cli-vs-sdk]] — when to pick which

Cross-links

• SDK entry point → [[../cursor-sdk/SKILL]]
• Models flag → [[../cursor-models/SKILL]]
• Rules / skills the CLI loads → [[../cursor-rules/SKILL]] · [[../cursor-skills-system/SKILL]]