gemini-api-cli

gemini-api CLI は、すべての Gemini API リソースをシェルのサブコマンドとして公開します。curl と比べて、メディアや文字起こしのコマンドは出力をデコードしてディスクに保存し、ファイルパスのみを表示します。-i はローカルファイルまたは files/<id> URI を添付します。--jq はインプロセスでフィールドを抽出します（デフォルトでは生の文字列を返し、外部の jq は不要です）。--dry-run はオフラインで、機密情報をマスクした HTTP リクエストをプレビューします。また、一覧エンドポイントは --all で自動ページネーションを行います（--max-pages N でページ数の上限を指定し、--page-size でサーバー側のページサイズを設定します）。

CLI と SDK

シェルでの作業には CLI、アプリケーションコードには SDK を使います。 ターミナル、スクリプト、CI ジョブから gemini-api を使って、メディアファイルの生成、ローカルの PDF や録音の分析、Deep Research の実行、エージェントのサンドボックスの管理を行います（gemini-api はステートレスな Gemini API クライアントで、対話型の @google/gemini-cli コーディングエージェントとは異なります）。呼び出しをアプリケーションのソースコード内に記述する場合や、双方向の Live API WebSocket が必要な場合は、Google GenAI SDK（gemini-api-dev、gemini-live-api-dev）を使います。

インストールと認証

# macOS / Linux (set GEMINI_VERSION=<tag> to pin a release)
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash

認証情報は次の順に解決されます（最初に一致したものが使われます）：--api-key / --access-token フラグ、GEMINI_API_KEY / GEMINI_ACCESS_TOKEN 環境変数、OS のキーチェーン、~/.config/gemini-api/config.yaml。

• 環境変数（エージェントと CI）：export GEMINI_API_KEY="..."
• ワークステーションのキー：gemini-api configure --api-key "..." は OS のキーチェーンに保存します。ヘッドレス Linux で config.yaml を使用するには、--no-keyring または GEMINI_NO_KEYRING=1 を指定します。gemini-api auth logout は保存されたキーを消去します。
• 有効な認証の確認：gemini-api whoami（JSON の場合は -o json を追加）を実行すると、マスクされた認証情報と、採用された情報源が表示されます。

認証で最もよくある落とし穴： エクスポート済みの GEMINI_API_KEY は、キーチェーンや config.yaml に保存された認証情報より優先され、その環境変数に属するプロジェクトに課金されます。どの情報源が採用されたかを確認するには gemini-api whoami を実行するか、環境変数を無視するには env -u GEMINI_API_KEY gemini-api ... を実行してください。

コマンド構成

gemini-api <intent> [prompt] [flags]          # task commands with model and modality presets
gemini-api <resource> <action> [flags]        # REST resource groups

コマンド一覧を表示するには gemini-api --help を、フラグと使用例を確認するには <subcommand> --help を実行してください（--usage は 45 KB の KDL 仕様を出力するため、コンテキストを節約するには --help を使用してください）。

コマンド	主なフラグ／操作	デフォルトのモデルと動作
generate [prompt]	-m、-i、--stdin、--system、--previous-interaction-id、--stream=false、--body	gemini-3.8-flash。テキストの差分を stdout にストリーミングします
image [prompt]	-m、-i、--aspect-ratio、--image-size（512..4K）、--previous-interaction-id、--out	gemini-nano-banana-2.1。画像を書き込み、パスを出力します
tts [text]	-f、--stdin、--voice（デフォルトは Kore）、--multi-speaker、--language、--out	gemini-3.8-flash-tts。24 kHz の WAV を書き込み、パスを出力します（保存されません）
music [prompt]	-m、-f、--stdin、--out、--body	lyria-3.5。音声トラックを書き込み、パスを出力します
video [prompt]	-m、-i、--aspect-ratio、--resolution（360p..4k）、--async、--resume、--out	gemini-omni-1.1-flash。完了までポーリングし、MP4 を書き込んでパスを出力します
analyze [question]	-i（必須、繰り返し指定可）、--stdin、--system、-m	gemini-3.8-flash。PDF、メディア、CSV／テキスト、YouTube URL に関する質問に回答します（保存されません）
transcribe	-i（必須、繰り返し指定可）、--format（md、text、json、srt）、--no-speakers、--no-timestamps、--out	gemini-3.8-flash。--out（または ./transcript-*）に書き込み、パスを出力します（保存されません）
agent	run、status、cancel、delete-interaction、create、list、get、delete	モデルまたは管理対象エージェントを実行します。カスタムエージェント定義を管理します
files	upload [--wait]、list、get、generated-files-list、register、delete	再利用可能な files/<id> URI をアップロードします（TTL は 48 時間、最大 2 GB、PDF は 50 MB）
models	（引数なし）、list [--all]、get <id>	引数なしの models はオフラインカタログを出力します。list と get はライブ API に問い合わせます
environments	create、list、get、delete、files、connect、poll、serve	リモートサンドボックスとワークスペースのスナップショット（エージェント基盤用の credentials、webhooks、triggers）

モデルの選択： デフォルトの gemini-3.8-flash、高度な推論とコーディング向けの gemini-4-argon、または高スループット向けの gemini-3.5-flash-lite を使用してください。画像には gemini-nano-banana-2.1、gemini-3.1-flash-lite-image、または gemini-3-pro-image を使用してください。非推奨の gemini-2.5-*、gemini-2.0-*、gemini-1.5-* モデルは使用しないでください。

グローバルフラグ

フラグ	用途
-o、--output-format	pretty（デフォルト）、json、toon、yaml、table
-q、--jq	組み込みの jq 式で JSON 出力をフィルタリングします（--raw-output はデフォルトで true です）
--agent-mode	stdout にコンパクトな TOON を、stderr に構造化された JSON エラーを出力します
--no-interactive	プロンプト、TUI フォーム、explore を無効にします
--dry-run	オフラインで入力を検証し、マスキングされた HTTP リクエストをプレビューします（-o json は JSON を出力します）
-d、--debug	HTTP リクエストとレスポンスの詳細を stderr に記録します

終了コード：0 は成功、1 は実行時または API エラー（失敗または未完了の実行を含む）、2 は使用方法または検証エラー、3 は認証エラーです。--server-url、ページネーション、認証フラグについては gemini-api --help-global を参照してください。

出力

メディア（image、tts、music、video）と transcribe はファイルをローカルに書き込み、stdout にはファイルパスのみを出力します。-o json を追加してもファイルは書き込まれ、{path, mime_type, size_bytes, response_id, status} が出力されます。

ストリーミングと JSON の形式： generate と agent run はデフォルトで返信テキストをプレーンテキストとしてストリーミングするため、-o json のみを指定すると NDJSON イベントが出力されます。1 つの JSON オブジェクト {id, status, steps, usage} を出力するには、--stream=false -o json を渡してください（--stream=false のみを指定するとメタデータが YAML で出力され、--jq または --background を指定するとストリーミングは自動的に無効になります）。返信テキストは .candidates[] ではなく、.steps[] の model_output に格納されています（下記の agent status を参照）。ページネーションを行う list コマンドでは、--jq はページごとのエンベロープに対して実行されます（.models[]?.name、.agents[]?.id）。

入力

• -i / --input は、generate、image、video、analyze、transcribe、agent run でメディアやドキュメントを添付します（繰り返し指定できます）。約 14 MB までのローカルパス（base64 の上限は 20 MB）、files/<id> URI、または YouTube URL を指定できます。より大きなファイルや再利用するファイルは、gemini-api files upload <path> --wait で一度アップロードしてください。
• -f / --file は、tts と music でプロンプトテキストをファイルから読み込みます。**パイプで渡すテキストには --stdin が必要です。**プレーンテキストを generate、image、video、analyze にパイプで渡す場合は、--stdin を指定してください。指定しないと、パイプ入力は JSON の --body として解析されます。
• --body は、Gemini API の生の JSON をインライン、@file.json、または @- で渡します（フラグとマージされ、キーが重複すると終了コード 2 で終了します）。response_format スキーマ、tools（google_search、code_execution、url_context、関数宣言）、generation_config、environment、または store に使用してください。
• **--schema をそのまま出力しないでください。**約 91 KB の圧縮 JSON が出力され、--jq の実行前に終了します。jq にパイプしてください：

  gemini-api generate --schema | jq '."$defs".ModelInteraction.properties | keys'
  

メディア、分析、文字起こし

HERO=$(gemini-api image "Isometric cloud database icon" --aspect-ratio 16:9 --image-size 2K --out ./hero.jpg)
gemini-api image "Add warm sunset lighting" -i "$HERO" --out ./hero-sunset.jpg

gemini-api tts "Alice: Ready to ship? Bob: Checks are green." \
  --multi-speaker "Alice=Kore,Bob=Puck" --out ./dialogue.wav

VID_ID=$(gemini-api video "Aerial coastal cliffs at sunrise" --aspect-ratio 16:9 --resolution 1080p --async)
gemini-api video --resume "$VID_ID" --out ./cliffs.mp4

FILE_URI=$(gemini-api files upload ./call.mp4 --wait)   # prints files/<id>
gemini-api analyze -i "$FILE_URI" "List action items with owners and timestamps."
gemini-api transcribe -i "$FILE_URI" --format srt --out ./call.srt

管理対象のエージェントとサンドボックス

• deep-research-preview-04-2026 と deep-research-max-preview-04-2026：--background を指定して実行し、agent status で状態を確認します。
• antigravity-preview-09-2026（Bash、Python、Node、ファイル操作、ウェブ検索が利用できる Linux サンドボックス）：--body に environment（"remote"）または environment_id を指定します。

ID の使い分け： agent status、agent cancel、agent delete-interaction には実行 ID（v1_...）を指定します。agent create、agent get、agent list、agent delete はカスタムエージェントのみを管理します（組み込みエージェントは gemini-api models に表示されます。agent list と environments list の件数は --page-size 10 で制限してください）。

RUN_ID=$(gemini-api agent run "Compare WebRTC SFU architectures with primary sources." \
  --agent deep-research-preview-04-2026 --background --jq '.id')
gemini-api agent status "$RUN_ID" --jq '.status'   # queued | in_progress | completed | failed
gemini-api agent status "$RUN_ID" \
  --jq '[.steps[]? | select(.type=="model_output") | .content[]? | select(.type=="text") | .text] | join("")'

ENV_ID=$(gemini-api agent run "Benchmark radix sort vs timsort in Python and write results.csv." \
  --agent antigravity-preview-09-2026 --body '{"environment": "remote"}' --jq '.environment_id')
gemini-api environments files list -e "$ENV_ID" -r
gemini-api environments files download "$ENV_ID" results.csv --out ./results.csv

gemini-api agent create --id code-reviewer --base-agent antigravity-preview-09-2026 \
  --system-instruction "Review diffs for race conditions and auth bugs."

マルチターンと構造化出力

呼び出しはデフォルトで状態をサーバー側に保存する（store は true）ため、マルチターンの連鎖では --previous-interaction-id のみが必要です（system_instruction、tools、generation_config はターンごとに適用されます。store を false に設定すると、previous_interaction_id と background は無効になります）。

TURN1=$(gemini-api generate "Propose 2 indexing strategies for time-series logs." --jq '.id')
gemini-api generate "Compare them for write-heavy workloads." --previous-interaction-id "$TURN1"

スキーマ制約付きの JSON 出力には、--stdin と --body を組み合わせます：

cat build.log | gemini-api generate "Extract unique compiler errors." --stdin --stream=false --body '{
  "response_format": {
    "type": "text", "mime_type": "application/json",
    "schema": {"type": "object", "properties": {"errors": {"type": "array", "items": {"type": "string"}}}, "required": ["errors"]}
  },
  "store": false
}'

CLI の全リファレンス：aistudio.google.com/docs/cli.md；ドキュメントのインデックス：llms.txt。