Headless mode

Headless mode 是 Gemini CLI 的程式化入口。它不會開啟互動式終端 UI，而是執行一次任務並把結果輸出到標準輸出。

觸發方式

兩種常見觸發方式：

gemini -p "Explain this error"
gemini --prompt "Write a commit message"

或在非 TTY 環境中執行，例如管道、重定向、CI。

如果沒有 -p 且沒有 pipe / redirect，Gemini CLI 會進入互動 UI。自動化指令碼應顯式使用 -p 或 --prompt，避免 CI 因為等待互動輸入卡住。

官方還支援 --prompt-interactive 這類混合入口，但生產指令碼不要依賴互動追問。能一次性給出輸入、上下文、輸出格式和失敗策略，指令碼才可復現。

輸出格式

預設輸出普通文本。需要給指令碼消費時，使用結構化輸出：

gemini --output-format json -p "Summarize @package.json"

JSON 模式通常包含：

• response：最終回答。
• stats：token 與延遲統計。
• error：失敗時的錯誤資訊。

Streaming JSON 輸出適合長期任務或即時消費事件，事件可能包括初始化、訊息片段、工具呼叫、工具結果、錯誤和最終結果。

指令碼消費 JSON 時，要用真正的 JSON parser，不要用 grep 或字串切分。模型輸出和錯誤欄位都可能包含換行、引號和程式碼塊。

退出碼

0   成功
1   通用错误或 API 失败
42  输入错误
53  turn limit exceeded

指令碼里不要只讀 stdout。必須同時處理退出碼和 stderr；response 為空但退出碼為 0、或者模型返回了不可解析結構，都要算失敗分支。

什麼時候用

• CI 裡自動總結 diff。
• 批次處理日誌。
• 為內部工具包一層 AI wrapper。
• 生成結構化 JSON 後交給 jq 或後續指令碼。

生產指令碼注意

• prompt 要固定，不要依賴互動追問。
• 輸入先限流和過濾，避免把大檔案、金鑰、二進位制檔案塞進上下文。
• 需要 JSON 時使用 --output-format json，再用 jq 或語言內 JSON parser 校驗。
• 對 429、網路錯誤、turn limit exceeded 做重試或失敗記錄。
• 批次任務寫入檔案時先寫臨時檔案，校驗後再替換正式檔案。

驗收方式

用成功樣例、無效輸入、超長輸入、API 失敗四種情況跑指令碼。確認退出碼、JSON 解析、空輸出處理和日誌記錄都符合預期，再接入 CI。

指令碼里建議把失敗分成三類記錄：輸入不合法、模型或網路失敗、輸出不符合 schema。三類失敗的重試策略不同，不要統一寫成“再跑一次”。

CI 中還要設定超時。

失敗日誌要可追溯。 方便複查。

還要記錄輸入摘要和模型資訊。否則同一個 headless 指令碼在配額、fallback 或模型選擇變化後，失敗很難復現。

上線前檢查

上線前至少跑三種輸入：正常輸入、空輸入、超長輸入。再模擬一次非零退出和一次 JSON 解析失敗。指令碼能穩定處理這五類情況，才適合放進 CI 或定時任務。

失敗分支要寫入日誌，且保留輸入摘要、任務編號和退出碼。

接下來去哪

官方來源

• Gemini CLI headless mode
• Gemini CLI automation tutorial