CLI reference
Gemini CLI 常用啟動方式、引數、非互動式呼叫、session resume、model、sandbox、approval mode 和輸出格式。
Gemini CLI 的命令列入口分兩類：互動式會話用於持續協作，非互動式 prompt 用於指令碼和自動化。不要把 CLI reference 當成引數長表背誦；先掌握執行位置、上下文輸入、許可權模式和輸出格式。
先記 4 個入口：gemini 進入互動；gemini -p 一次性執行；gemini -r latest 恢復最近會話；cat file | gemini 處理管道輸入。真實專案先用預設批准模式，不要第一天就開 yolo。
1. 常用啟動方式
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 | 團隊環境要先確認版本策略 |
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:#3b82f62. 常用引數
| 引數 | 用途 |
|---|---|
--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 |
引數優先順序很高：命令列引數用於當前 session，會覆蓋部分配置檔案設定。臨時試驗可以用引數；團隊預設行為應該沉澱到配置和文件裡。
3. approval mode
當前官方配置文件把 --approval-mode 解釋為工具呼叫批准模式，常見值是 default、auto_edit、yolo。Plan mode 另有專門頁面，不要把它當成長期自動批准策略。
| 模式 | 使用建議 |
|---|---|
default | 日常預設，先確認再執行 |
auto_edit | 小範圍編輯可考慮，但要看 diff |
yolo | 只適合低風險臨時目錄，不適合真實專案 |
不要在真實專案預設使用 yolo：生產儲存庫、含金鑰目錄、部署指令碼目錄、資料庫遷移和客戶資料目錄都不適合跳過確認。需要自動化時，也應該先限制目錄、工具和命令。
4. 輸出格式和指令碼化
非互動式任務優先使用結構化輸出：
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. 接下來去哪
命令系統
繼續看 slash commands、@ 檔案引用和 ! shell 的使用邊界。
Headless mode
準備把 Gemini CLI 放進指令碼或 CI 時，繼續看非互動式模式。
配置檔案
需要把預設模型、sandbox、工具限制和隱私設定長期化時，繼續看 settings。