---
title: "Cursor CLI 與 Headless 自動化"
description: "把 Cursor Agent 從編輯器帶到終端、指令碼、CI 和受控自動化。"
verifiedAt: "2026-05-09"
---

Cursor CLI 的價值不是"換個地方聊天"，而是把 Agent 放進 terminal、git、scripts、CI、PR review 和自動化流水線。Headless（無介面 / 非互動）模式更進一步，讓任務可以非互動執行。邊界也更嚴格：非互動越多，許可權、輸出和回退越要明確。

> [!NOTE]
> **本章目標**：你會判斷什麼時候用編輯器 Agent，什麼時候用 CLI，什麼時候進入 headless，並能寫出可審計的只讀指令碼和小範圍寫入指令碼。

## 1. 安裝與第一次啟動

官方安裝命令：

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

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

# 安装完成后直接启动交互
agent
```

`agent` 是 Cursor CLI 的可執行命令。第一次啟動會要求登入，認證完畢後即可在終端直接對話。

> [!WARNING]
> **企業 / 安全敏感環境**：`curl ... \| bash` 模式直接執行遠端指令碼，部分公司安全策略禁止。建議先 `curl https://cursor.com/install -fsS -o /tmp/cursor-install.sh` 下載指令碼審查，再 `bash /tmp/cursor-install.sh`，或透過內部軟體分發系統下發。Cursor 也有 macOS / Windows 桌面版安裝包可選，CLI 是可選項。

## 2. CLI 適合什麼

編輯器適合邊看程式碼邊協作；CLI 適合貼近工程命令和自動化系統。

CLI 適合：

- 終端裡快速問專案結構。
- 對當前 git diff 做只讀 review。
- 批次生成報告。
- 在 CI 中輸出檢查結果。
- 透過 script 固定 prompt 和 output format。
- 把任務 handoff 到 Cloud Agent。

不適合：

- 需要大量視覺互動的 UI 調整。
- 需要人工逐步審查的複雜改動卻沒有 review gate。
- 生產部署、刪除、資料庫遷移這類高風險自動寫入。

## 3. 三種模式仍然重要

Cursor CLI 支援 Agent、Plan、Ask。和編輯器一樣，模式決定風險。

```bash
agent --mode=ask "explain how billing is initialized"
agent --plan "plan a safe migration from REST to GraphQL"
agent "fix the failing checkout parser test and show the diff"
```

判斷：

- 只讀理解：`--mode=ask`。
- 複雜任務先方案：`--plan` 或 `--mode=plan`。
- 明確小任務：預設 Agent。

很多 CLI 事故來自把 Ask 任務用 Agent 執行，或者把 Plan 任務直接寫入。

### 把任務推到 Cloud Agent（mid-conversation handoff）

在互動會話中，把訊息開頭加 `&` 可以把任務推到 Cloud Agent 繼續跑——本地終端關掉它也不會停。適合長任務邊喝咖啡邊跑：

```text
& 把整个 auth module 重构为 JWT，并补完整测试
```

跑起來之後可以在 [cursor.com/agents](https://cursor.com/agents) 網頁端或移動端繼續跟進。

### 恢復歷史會話（Sessions）

```bash
agent ls                  # 列所有历史对话
agent resume              # 恢复最近一个
agent --continue          # 继续上一个会话
agent --resume="chat-id"  # 指定 chat id 恢复
```

會話恢復保留了完整上下文，適合長任務跨天繼續，或者本地切到不同終端視窗接著幹。

## 4. Headless 是自動化入口，不是無監管入口

Headless 的核心是 print mode（列印模式，非互動輸出到 stdout 而非進入 REPL）：`agent -p` 或 `agent --print`。它適合 scripts、CI、批處理和自動報告。

只讀示例：

```bash
agent -p --output-format text \
  "Review the current git diff for correctness and security risks. Do not edit files."
```

可寫示例需要顯式邊界：

```bash
agent -p --force --output-format text \
  "Only edit src/public-api.ts. Add missing JSDoc for exported functions. Do not edit any other file."
```

關鍵點：

- `agent -p` 適合輸出建議或報告。
- 寫入指令碼必須顯式使用 `--force` 或 `--yolo`（you-only-live-once，跳過所有確認的極簡寫入開關，比 `--force` 更激進），並限制檔案範圍。
- 只讀指令碼要明確寫 `Do not edit files`。
- 寫入指令碼前檢查 git 工作區。

## 5. 輸出格式決定能否自動化

官方 Headless 文件支援 text、json、stream-json：

| 格式 | 何時用 |
|---|---|
| `text` | 人讀摘要 / PR 評論 / 日誌摘要 |
| `json` | 機器解析最終結果，schema 由 prompt 鎖死 |
| `stream-json` | 長任務即時進度 / 工具呼叫流，適合需要邊跑邊渲染的 UI |

機器消費不要靠字串擷取。要麼要求 JSON schema，要麼用 `jq` 或正式 parser 處理。

```bash
agent -p --output-format json \
  "Return exactly JSON with keys: findings, riskLevel, recommendedCommands."
```

## 6. 只讀審查指令碼

第一階段建議只做 review，不寫檔案。

```bash
#!/usr/bin/env bash
set -euo pipefail

agent -p --output-format text \
  "Review the current git diff for:
  - correctness risks
  - security risks
  - missing tests

  Do not edit files.
  Return concise findings with file paths when possible."
```

這個指令碼適合放在本地 pre-review、人工觸發的 CI job 或 PR 輔助評論。它的價值是穩定產出風險清單，而不是替代測試。

## 7. 小範圍寫入指令碼

寫入必須更嚴格。

```bash
#!/usr/bin/env bash
set -euo pipefail

test -z "$(git status --short)"

agent -p --force --output-format text \
  "Only edit src/public-api.ts.
  Add JSDoc comments to exported functions.
  Do not change runtime behavior.
  After editing, summarize exact changes."

git diff -- src/public-api.ts
```

上線標準：

- 工作區乾淨。
- 檔案範圍固定。
- 禁止觸碰 secrets、lockfile、配置和無關模組。
- 執行後展示 diff。
- 跑 focused test、lint 或 build。
- 失敗時能丟棄分支或 revert commit。

## 8. GitHub Actions：先 restricted autonomy

官方 GitHub Actions 文件有 full autonomy 和 restricted autonomy 兩種思路。

生產 CI 預設用 restricted autonomy：

- Agent 負責分析和有限檔案修改。
- deterministic workflow step（確定性工作流步驟，命令列為可預測、不依賴 AI 推理的固定 step）負責 branch、commit、push、PR comment。
- `CURSOR_API_KEY` 只走 GitHub Secrets。
- permissions 明確 allow / deny。
- 預設 deny `Shell(git)`、`Shell(gh)` 和 `.env*` 寫入。

不要一開始就讓 Agent 在 CI 裡同時負責理解問題、修改檔案、提交、推送和評論 PR。職責拆開，日誌和回退才清楚。

## 9. 商業級上線清單

把 CLI / headless 放進團隊流程前，確認：

- 安裝來源、PATH、版本驗證可復現。
- 本地、CI、團隊成員的認證邊界分開。
- Ask、Plan、Agent 使用場景寫清楚。
- `agent -p` 預設只讀。
- 寫入指令碼要求乾淨 Git 工作區。
- 輸出格式固定，機器消費用 JSON。
- CI secrets 不進日誌和 prompt。
- Git / gh / deploy 由 deterministic step 執行。
- 每個自動化都有日誌、退出碼和人工 gate。

## 官方來源

- [Cursor CLI Overview](https://cursor.com/docs/cli/overview.md)：官方 CLI 總覽、interactive / print mode、Cloud Agent handoff、sessions、sandbox 和 sudo prompt。
- [Using Headless CLI](https://cursor.com/docs/cli/headless.md)：官方 print mode、`--force` / `--yolo`、輸出格式、API key 和指令碼示例。
- [Cursor GitHub Actions](https://cursor.com/docs/cli/github-actions.md)：官方 CI 安裝、`CURSOR_API_KEY`、full autonomy、restricted autonomy 和 permissions。
- [Cursor CLI Output Format](https://cursor.com/docs/cli/reference/output-format.md)：官方 text、json、stream-json 輸出格式。

## 接下來去哪

<Cards>
  <Card title="上一篇" description="先把 Skills、Subagents 和 Hooks 的邊界分清。" href="/zh-Hant/docs/cursor/understanding/07-skills-subagents-hooks" />
  <Card title="下一篇" description="繼續理解 Cloud Agent、Bugbot 和 Review 的團隊流程。" href="/zh-Hant/docs/cursor/understanding/09-cloud-agent-bugbot-review" />
  <Card title="官方 Headless" description="檢視官方重組頁裡的 headless 指令碼與輸出格式。" href="/zh-Hant/docs/cursor/official/03-cli-automation/35-headless" />
</Cards>
