---
title: "CLI reference"
description: "Gemini CLI 常用啟動方式、引數、非互動式呼叫、session resume、model、sandbox、approval mode 和輸出格式。"
verifiedAt: "2026-05-09"
---

Gemini CLI 的命令列入口分兩類：互動式會話用於持續協作，非互動式 prompt 用於指令碼和自動化。不要把 CLI reference 當成引數長表背誦；先掌握執行位置、上下文輸入、許可權模式和輸出格式。

> [!NOTE]
> **先記 4 個入口**：`gemini` 進入互動；`gemini -p` 一次性執行；`gemini -r latest` 恢復最近會話；`cat file | gemini` 處理管道輸入。真實專案先用預設批准模式，不要第一天就開 `yolo`。

## 1. 常用啟動方式

```bash
gemini
gemini -p "summarize README.md"
gemini "explain this project"
cat logs.txt | gemini
gemini -i "What is the purpose of this project?"
gemini -r "latest"
gemini -r "latest" "Check for type errors"
gemini -r "<session-id>" "Finish this PR"
gemini update
```

這些入口的區別：

| 入口 | 適合場景 | 注意 |
| --- | --- | --- |
| `gemini` | 持續互動、真實專案理解和修改 | 會保留會話上下文 |
| `gemini -p "..."` | 一次性回答、指令碼、CI | 要明確輸出格式和退出碼處理 |
| `cat file | gemini` | 管道輸入、日誌解釋、批處理 | 輸入過大時要收窄範圍 |
| `gemini -r latest` | 恢復最近 session | 先確認是不是當前專案的 session |
| `gemini update` | 更新 CLI | 團隊環境要先確認版本策略 |

```mermaid
flowchart TD
    Need["我要用 Gemini CLI"] --> Interactive{"需要持續對話?"}
    Interactive -->|是| Repl["gemini"]
    Interactive -->|否| Script{"指令碼或 CI?"}
    Script -->|是| Prompt["gemini -p + output format"]
    Script -->|否| Pipe{"已有 stdin 輸入?"}
    Pipe -->|是| Stdin["cat file | gemini"]
    Pipe -->|否| Resume{"繼續舊會話?"}
    Resume -->|是| Session["gemini -r latest"]
    Resume -->|否| Repl

    style Prompt fill:#fef3c7,stroke:#f59e0b
    style Session fill:#dbeafe,stroke:#3b82f6
```

## 2. 常用引數

| 引數 | 用途 |
| --- | --- |
| `--model` / `-m` | 指定模型或模型 alias |
| `--prompt` / `-p` | 非互動式執行 prompt |
| `--prompt-interactive` / `-i` | 先執行 prompt，再繼續互動 |
| `--resume` / `-r` | 恢復歷史 session |
| `--sandbox` / `-s` | 啟用 sandbox |
| `--approval-mode` | 設定工具執行批准模式 |
| `--include-directories` | 把額外目錄加入 workspace |
| `--output-format` / `-o` | 輸出 text / json / stream-json |
| `--extensions` / `-e` | 指定啟用 extension |
| `--allowed-mcp-server-names` | 限制可用 MCP server |

> [!IMPORTANT]
> **引數優先順序很高**：命令列引數用於當前 session，會覆蓋部分配置檔案設定。臨時試驗可以用引數；團隊預設行為應該沉澱到配置和文件裡。

## 3. approval mode

當前官方配置文件把 `--approval-mode` 解釋為工具呼叫批准模式，常見值是 `default`、`auto_edit`、`yolo`。Plan mode 另有專門頁面，不要把它當成長期自動批准策略。

| 模式 | 使用建議 |
| --- | --- |
| `default` | 日常預設，先確認再執行 |
| `auto_edit` | 小範圍編輯可考慮，但要看 diff |
| `yolo` | 只適合低風險臨時目錄，不適合真實專案 |

> [!WARNING]
> **不要在真實專案預設使用 `yolo`**：生產儲存庫、含金鑰目錄、部署指令碼目錄、資料庫遷移和客戶資料目錄都不適合跳過確認。需要自動化時，也應該先限制目錄、工具和命令。

## 4. 輸出格式和指令碼化

非互動式任務優先使用結構化輸出：

```bash
gemini -p "Explain this repository" --output-format json
```

長任務監控可以按官方 README 的 `stream-json` 方式處理事件流；但指令碼里要寫清失敗處理、超時、重試和日誌脫敏，不要只管拿到一段文本。

## 5. model alias

官方 cheatsheet 中列出 `auto`、`pro`、`flash`、`flash-lite` 等 alias。具體解析到哪個模型會隨官方實現變化，以當前官方文件和 CLI 輸出為準。

模型 alias 是便利入口，不是長期契約。教程和團隊規則裡不要硬寫“某個 alias 一定等於某個模型版本”；需要固定模型時，回模型選擇章節和官方 CLI 輸出核驗。

## 6. 接下來去哪

<Cards>
  <Card title="命令系統" description="繼續看 slash commands、@ 檔案引用和 ! shell 的使用邊界。" href="/zh-Hant/docs/gemini-cli/official/01-cli-workflow/11-commands" />
  <Card title="Headless mode" description="準備把 Gemini CLI 放進指令碼或 CI 時，繼續看非互動式模式。" href="/zh-Hant/docs/gemini-cli/official/07-integrations-automation/72-headless-mode" />
  <Card title="配置檔案" description="需要把預設模型、sandbox、工具限制和隱私設定長期化時，繼續看 settings。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/20-settings" />
</Cards>

## 官方來源

- [Gemini CLI Cheatsheet](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/cli-reference.md)
- [Gemini CLI Configuration](https://google-gemini.github.io/gemini-cli/docs/get-started/configuration.html)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
