Headless mode

概要

対話 TUI 無しで、構造化されたテキストまたは JSON を返すプログラム向けインターフェース。CI/CD、バッチ処理、自前の AI ラッパースクリプト向け。

仕様

起動条件

非 TTY 環境で実行されたとき、または -p（--prompt）でクエリを渡したときに headless モードになる
フラグ無しの位置引数は既定で対話モードになる。ただし入力または出力がパイプ／リダイレクトされている場合は除く
応答は標準出力（stdout）に出る
標準入力（stdin）をコンテキストとして読める

出力形式（`--output-format`）

JSON 出力

応答と使用統計を含む単一の JSON オブジェクトを返す。

フィールド	型	内容
`response`	string	モデルの最終回答
`stats`	object	トークン使用量と API レイテンシの指標
`error`	object（任意）	失敗したときのエラー詳細

ストリーミング JSON 出力

改行区切り JSON（JSONL）のイベント列を返す。

イベント種別	内容
`init`	セッションのメタデータ（session ID、model）
`message`	ユーザーとアシスタントのメッセージチャンク
`tool_use`	引数付きのツール呼び出し要求
`tool_result`	実行されたツールの出力
`error`	致命的でない警告とシステムエラー
`result`	最終結果。集計統計とモデル別のトークン使用量の内訳を含む

終了コード

コード	意味
`0`	成功
`1`	一般的なエラーまたは API 失敗
`42`	入力エラー（不正なプロンプトや引数）
`53`	ターン数の上限超過

使い方の例

単発実行: gemini -p "..."
パイプ入力: cat error.log | gemini -p "Explain why this failed"、git diff | gemini -p "Write a commit message for these changes"
構造化データの抽出: --output-format json と jq -r '.response' を組み合わせる

設定

gemini -p "Write a poem about TypeScript"
cat error.log | gemini -p "Explain why this failed"
gemini --output-format json "Return a raw JSON object with keys 'version' and 'deps' from @package.json" | jq -r '.response' > data.json

function gcommit() {
  diff=$(git diff --staged)
  if [ -z "$diff" ]; then
    echo "No staged changes to commit."
    return 1
  fi
  msg=$(echo "$diff" | gemini -p "Write a concise Conventional Commit message for this diff. Output ONLY the message.")
  git commit -m "$msg"
}

制約・注意点

Folder Trust が有効で、フォルダが untrusted の場合、ヘッドレス環境では trust ダイアログを出せず FatalUntrustedWorkspaceError で終了する。--skip-trust または GEMINI_CLI_TRUST_WORKSPACE=true で回避する（facts/gemini-cli/trusted-folders.md）

Headless mode

概要

仕様

起動条件

出力形式（--output-format）

JSON 出力

ストリーミング JSON 出力

終了コード

使い方の例

設定

制約・注意点

関連

出力形式（`--output-format`）