From d73fec1be67a6f60c75219e0c8841b02567daab7 Mon Sep 17 00:00:00 2001 From: Fechin Date: Fri, 3 Apr 2026 18:28:46 +0800 Subject: [PATCH] feat: add Cursor CLI icon and move to AI category --- source/_posts/cursor-cli.md | 520 ++++++++++++++++++++++++++++++ source/assets/icon/cursor-cli.svg | 10 + 2 files changed, 530 insertions(+) create mode 100644 source/_posts/cursor-cli.md create mode 100644 source/assets/icon/cursor-cli.svg diff --git a/source/_posts/cursor-cli.md b/source/_posts/cursor-cli.md new file mode 100644 index 0000000..4f58cdc --- /dev/null +++ b/source/_posts/cursor-cli.md @@ -0,0 +1,520 @@ +--- +title: Cursor CLI +date: 2026-04-03 12:00:00 +background: bg-[#1a1a1a] +tags: + - AI + - CLI + - agent + - cursor + - coding +categories: + - AI +intro: | + [Cursor CLI](https://cursor.com/docs/cli/overview) (`agent`) is the terminal interface for Cursor's AI coding agent — run agentic tasks, scripts, and CI pipelines from the command line. +plugins: + - copyCode +--- + +## Getting Started + +### Hello World {.row-span-2} + +```bash +# Interactive agent session +$ agent + +# One-shot prompt (print mode) +$ agent -p "List all TODO comments in this repo" + +# Ask a question (read-only) +$ agent --mode=ask "How does auth work here?" + +# Plan only (no edits) +$ agent --plan "Refactor the payment module" +``` + +### Install + +#### macOS / Linux / WSL + +```bash {.wrap} +$ curl https://cursor.com/install -fsS | bash +``` + +#### Windows (PowerShell) + +```powershell {.wrap} +irm 'https://cursor.com/install?win32=true' | iex +``` + +#### Post-install + +```bash +# Add to PATH if needed +export PATH="$HOME/.local/bin:$PATH" + +# Verify +$ agent --version + +# Update +$ agent update +``` + +### Key Concepts + +| Concept | Description | +| ----------- | ----------------------------------- | +| Agent mode | Full access: read, write, run shell | +| Plan mode | Read-only analysis, no edits | +| Ask mode | Q&A / explanations, read-only | +| Cloud agent | Delegates to remote Cursor cloud | +| Session | Saved conversation with history | +| Worktree | Isolated git branch environment | +| ACP | Agent Client Protocol (JSON-RPC) | +| MCP | External tool/data integrations | + +## CLI Flags {.cols-2} + +### Session & Mode {.row-span-2} + +| Flag | Description | +| -------------------- | ------------------------------------- | +| `--mode=plan` | Plan mode (read-only, no edits) | +| `--mode=ask` | Ask mode (Q&A, read-only) | +| `--plan` | Shorthand for `--mode=plan` | +| `-p, --print` | Headless/print mode (non-interactive) | +| `-c, --cloud` | Start in cloud agent mode | +| `--continue` | Continue previous session | +| `--resume [chatId]` | Resume a specific session | +| `-n, --name` | Name for the session | +| `--workspace ` | Set workspace directory | +| `--model ` | Model to use (e.g., `sonnet-4`) | +| `--list-models` | List available models and exit | + +{.bold-first} + +### Worktree & Sandbox + +| Flag | Description | +| ----------------------- | ------------------------------------- | +| `-w, --worktree [name]` | Start in isolated git worktree | +| `--worktree-base ` | Branch/ref to base the worktree on | +| `--skip-worktree-setup` | Skip `.cursor/worktrees.json` scripts | +| `--sandbox ` | `enabled` or `disabled` | +| `--trust` | Trust workspace without prompting | +| `--approve-mcps` | Auto-approve all MCP servers | + +{.bold-first} + +### Output & Permissions + +| Flag | Description | +| ------------------------- | --------------------------------------- | +| `--output-format ` | `text` \| `json` \| `stream-json` | +| `--stream-partial-output` | Stream text deltas (stream-json only) | +| `-f, --force` | Allow commands unless explicitly denied | +| `--yolo` | Alias for `--force` | +| `--api-key ` | Auth key (or `CURSOR_API_KEY`) | +| `-H, --header ` | Custom request header (`Name: Value`) | + +{.bold-first} + +## Commands {.cols-2} + +### All Subcommands {.row-span-2} + +| Command | Description | +| ----------------------------------- | --------------------------------------- | +| `agent [prompt]` | Start interactive or print session | +| `agent ls` | List sessions to resume | +| `agent resume` | Resume latest chat session | +| `agent login` | Authenticate with Cursor | +| `agent logout` | Sign out and clear auth | +| `agent status` | View auth status / whoami | +| `agent update` | Update to latest version | +| `agent about` | Show version, system, account info | +| `agent models` | List available models | +| `agent create-chat` | Create new empty chat, return ID | +| `agent rule` | Generate new Cursor rule interactively | +| `agent mcp` | Manage MCP servers | +| `agent mcp list` | List configured MCP servers | +| `agent mcp list-tools ` | List tools for a specific MCP server | +| `agent mcp enable ` | Add MCP server to approved list | +| `agent mcp disable ` | Disable an MCP server | +| `agent mcp login ` | Authenticate with an MCP server | +| `agent install-shell-integration` | Install shell integration to `~/.zshrc` | +| `agent uninstall-shell-integration` | Remove shell integration | +| `agent acp` | Start ACP server (JSON-RPC over stdio) | + +{.bold-first} + +### Session Management + +```bash +# List sessions to resume +$ agent ls + +# Continue previous session +$ agent --continue + +# Resume specific session by ID +$ agent --resume abc123 + +# Resume latest session +$ agent resume +``` + +### Auth & Account + +```bash +$ agent login +$ agent logout +$ agent status # or: agent whoami +$ agent about # version + account info +$ agent models # list available models +``` + +## Execution Modes {.cols-3} + +### Agent Mode {.secondary} + +Full agentic access — reads files, writes code, runs shell commands, and uses all tools. + +```bash +$ agent +$ agent "Fix the bug in auth.ts" +``` + +Default mode when no `--mode` flag is given. + +### Plan Mode + +Read-only analysis. Proposes a plan without making any edits to the codebase. + +```bash +$ agent --plan +$ agent --mode=plan "Refactor auth" +``` + +Cannot modify files or run commands. + +### Ask Mode + +Question & answer style. Explains code, answers questions — no edits, no shell. + +```bash +$ agent --mode=ask +$ agent --mode=ask "How does caching work?" +``` + +Best for understanding code without risk. + +## Headless & Scripting {.cols-2} + +### Pipe & Script Usage {.row-span-2} + +```bash +# Summarize a diff +$ git diff | agent -p "Summarize these changes" + +# Review a file +$ cat src/auth.ts | agent -p "Find security issues" + +# Process logs +$ tail -200 app.log | agent -p "Identify errors" + +# Reference images in prompt +$ agent -p "Describe this diagram: /path/to/image.png" +``` + +Output formats: + +```bash +# Plain text (default) +$ agent -p "task" --output-format text + +# Full JSON response +$ agent -p "task" --output-format json + +# Streaming JSON deltas +$ agent -p "task" --output-format stream-json + +# Stream text chunks as they arrive +$ agent -p "task" --output-format stream-json \ + --stream-partial-output +``` + +### CI / CD Usage + +```bash +# Allow all file modifications +$ agent -p "Update changelog" --force + +# Run with API key from env +$ CURSOR_API_KEY=xxx agent -p "Run tests" + +# Trusted workspace (skip prompts) +$ agent -p "Deploy" --trust + +# Specific workspace directory +$ agent -p "Analyze" --workspace /repo +``` + +Batch processing: + +```bash {.wrap} +for f in src/**/*.ts; do + agent -p "Add JSDoc to $f" --force +done +``` + +## Worktrees {.cols-2} + +### Isolated Environments {.row-span-2} + +Worktrees create an isolated git branch at `~/.cursor/worktrees//` — keeping the main working tree clean. + +```bash +# Auto-named worktree +$ agent -w + +# Named worktree +$ agent -w feature-auth + +# Worktree from specific branch +$ agent -w fix --worktree-base main + +# Skip setup scripts +$ agent -w feature --skip-worktree-setup +``` + +Worktree config in `.cursor/worktrees.json`: + +```json +{ + "setup": ["npm install", "cp .env.example .env"] +} +``` + +### Worktree Files + +Control what's copied to a new worktree: + +``` +# .worktreeinclude (glob patterns) +.env +.env.local +secrets/ +node_modules/ +``` + +Files matching these patterns are copied from the main tree to the new worktree on creation. + +## Shell Mode {.cols-2} + +### Shell Execution + +Shell mode runs in `$SHELL`. Navigate with `cd` chained to commands: + +```bash +# Change directory then run +cd /my/project && agent "optimize this" + +# Shell commands inside session +$ ls -la # runs in $SHELL +$ npm test # runs tests +$ git status # git operations +``` + +Shell controls: + +| Key | Action | +| -------- | ---------------------------- | +| `Ctrl+C` | Cancel current shell command | +| `Ctrl+O` | Expand / view full output | +| `Tab` | Add command to allowlist | + +{.shortcuts} + +### Shell Notes + +- Each command runs in `$SHELL` (zsh/bash/fish) +- 30-second timeout per command +- `cd dir && cmd` for directory-specific commands +- Shell integration improves context awareness: + +```bash +$ agent install-shell-integration +# adds hooks to ~/.zshrc +``` + +## MCP Servers {.cols-2} + +### Configure MCP {.row-span-2} + +User-level config at `~/.cursor/mcp.json`, project-level at `.cursor/mcp.json`: + +#### stdio server (Node.js) + +```json +{ + "mcpServers": { + "my-tool": { + "command": "npx", + "args": ["-y", "my-mcp-server"], + "env": { "API_KEY": "value" } + } + } +} +``` + +#### stdio server (Python) + +```json +{ + "mcpServers": { + "my-tool": { + "command": "python", + "args": ["-m", "my_mcp_server"] + } + } +} +``` + +#### HTTP / SSE server + +```json +{ + "mcpServers": { + "remote-tool": { + "url": "https://my-server.com/mcp" + } + } +} +``` + +### MCP Commands + +```bash +# List all configured servers +$ agent mcp list + +# List tools for a server +$ agent mcp list-tools my-tool + +# Approve a server +$ agent mcp enable my-tool + +# Disable a server +$ agent mcp disable my-tool + +# Authenticate with a server +$ agent mcp login my-tool + +# Auto-approve all in session +$ agent --approve-mcps +``` + +## ACP Protocol {.cols-2} + +### ACP Overview {.row-span-2} + +ACP (Agent Client Protocol) exposes the Cursor agent as a JSON-RPC 2.0 server over **stdio**. Build custom IDE integrations or headless clients. + +```bash +# Start ACP server +$ agent acp + +# With API key +$ agent --api-key "$CURSOR_API_KEY" acp +``` + +**Request flow:** + +``` +initialize +authenticate (cursor_login) +session/new or session/load +session/prompt + → session/update (streaming chunks) + → session/request_permission (tool approval) +session/cancel (optional) +``` + +Permission outcomes: + +| Response | Effect | +| -------------- | ------------------------ | +| `allow-once` | Approve this time only | +| `allow-always` | Always approve this tool | +| `reject-once` | Deny this time only | + +### ACP Extension Methods + +Cursor extension methods sent over ACP: + +| Method | Type | Purpose | +| ----------------------- | -------- | ---------------------- | +| `cursor/ask_question` | Blocking | Multiple-choice prompt | +| `cursor/create_plan` | Blocking | Request plan approval | +| `cursor/update_todos` | Notify | Update todo list state | +| `cursor/task` | Notify | Subagent task status | +| `cursor/generate_image` | Notify | Image generation event | + +{.show-header} + +Minimal Node.js client: + +```js {.wrap} +const agent = spawn('agent', ['acp'], { stdio: ['pipe', 'pipe', 'inherit'] }); +// send initialize → authenticate → session/new → session/prompt +``` + +**IDE integrations via ACP:** + +- JetBrains (IntelliJ, WebStorm, PyCharm) +- Neovim via `avante.nvim` plugin +- Zed editor extensions +- Any editor with extension support + +## Cloud Agents {.cols-2} + +### Cloud Mode + +Cloud agents run tasks remotely in Cursor's infrastructure. Use for long-running or parallel workloads. + +```bash +# Launch cloud agent picker +$ agent -c +$ agent --cloud + +# Cloud agent with a prompt +$ agent -c "Migrate all tests to Vitest" +``` + +Cloud agents support: + +- Remote execution (no local resources) +- Parallel task delegation +- Longer-running workflows + +### Subagent Types + +When using ACP or cloud, subagents can be typed: + +| Type | Description | +| -------------------- | ----------------------- | +| `explore` | Codebase exploration | +| `browser_use` | Web browser automation | +| `computer_use` | Desktop GUI actions | +| `shell` | Shell command execution | +| `video_review` | Video content analysis | +| `{ custom: "type" }` | Custom subagent type | + +## Also see {.cols-1} + +- [Cursor CLI Docs](https://cursor.com/docs/cli/overview) _(cursor.com)_ +- [ACP Protocol Docs](https://cursor.com/docs/cli/acp) _(cursor.com)_ +- [Cursor Marketplace](https://cursor.com/marketplace) _(cursor.com)_ +- [MCP Overview](https://cursor.com/docs/mcp) _(cursor.com)_ diff --git a/source/assets/icon/cursor-cli.svg b/source/assets/icon/cursor-cli.svg new file mode 100644 index 0000000..e86744f --- /dev/null +++ b/source/assets/icon/cursor-cli.svg @@ -0,0 +1,10 @@ + + + + + + \ No newline at end of file