Gemini API CLIとは? Claude Codeや Codexに Geminiの 画像生成・ 管理エージェントを 渡すGoogle製ステートレスCLIを 公式READMEから 読む
- #Gemini API CLI
- #CLI
コーディングエージェントに「画像を作って」「このPDFの内容を教えて」と頼みたくなる場面は増えています。Googleが公開しているgoogle-gemini/gemini-api-cliは、そうした作業をエージェント自身がシェルコマンド経由でGeminiに委任できるようにする、ステートレスなCLIです。公式READMEは「Gemini models and managed agents for the agent you already use」と位置づけており、Claude CodeやCodexなど“既に使っているエージェント”にGeminiの機能を渡す、という発想が特徴です。
この記事は、公式GitHubリポジトリの README・LICENSE・CONTRIBUTING.md・Releasesページを一次情報としています。このクラウド環境ではgo install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latestによるビルドを実行し、実際にgemini-apiのバイナリ(約25MB)を生成できました。一方で、新しく生成した実行ファイルをこの検証環境のセキュリティポリシー上直接実行することができず、また有効なGemini APIキーも用意していないため、--helpの実機出力やコマンドの実際の応答は確認できていません。本稿は公式リポジトリの記載内容の整理であることを先にお伝えします。
Gemini API CLIとは:エージェントに「渡す」ためのステートレスCLI
READMEによると、Gemini API CLIはCodex・Claude Code・Antigravity・OpenClaw・Hermesなど、シェルを扱えるエージェントに対してGemini APIの機能を渡すための単一バイナリです。エージェントが作業計画を立て、Gemini API CLIがモデル呼び出し・メディア生成・管理エージェントの起動を担う、という役割分担が明記されています。実行は毎回が独立しており、会話の文脈は保持しない「ステートレス」な設計で、必要な文脈はエージェント側が毎回渡す構成です。ライセンスはApache License 2.0(ソフトウェア本体)およびCreative Commons Attribution 4.0(その他の素材)のデュアル表記で、著作権表記は「Copyright 2026 Google LLC」でした。本稿執筆時点でスター数は512、フォーク数は82、GitHub上のトピックタグは gemini・gemini-api の2件です。
なぜ今このツールなのか:Gemini CLIの無料個人利用はAntigravity CLIに移行済み
Gemini API CLIを理解する上で欠かせないのが、姉妹プロジェクトであるgoogle-gemini/gemini-cli(コマンド名gemini)のREADMEに掲載されている告知です。そこには「Free individual access and Google AI Pro / Ultra(Google One)moved to Antigravity CLI on June 18, 2026」と明記されており、個人の無料利用やGoogle AI Pro/Ultraプランは2026年6月18日付でAntigravity CLI(コマンド名agy)に移行済みで、Gemini CLI自体は現在Gemini Code Assist Standard/EnterpriseまたはCode Assist for GitHubを使う組織向けの位置づけに変わったとされています。同じREADMEの表では、対話型のマルチエージェント開発ターミナルとしてAntigravity CLIが、組織向けのエージェントとして(この記事の対象である)Gemini API CLIがそれぞれ別物として並べられています。つまりGemini API CLIは、対話的にコードを書く「コーディングエージェント」ではなく、すでにあるエージェントにGeminiのモデルとメディア生成・管理エージェント機能を“関数呼び出しのように”渡すための補助的なCLIという位置づけです。
インストール方法と、このクラウド環境で実際に試した結果
READMEに記載されたインストール方法は4通りです。macOS/Linuxではcurl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh | bash、Windows(PowerShell)ではiwr -useb https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.ps1 | iex、Goが入っている環境ではgo install github.com/google-gemini/gemini-api-cli/cmd/gemini-api@latest、そしてGitHub Releasesからのビルド済みバイナリのダウンロードです。@mainを指定した開発版のビルドにはGo 1.26.10以上が必要と記載されています。
このクラウド環境ではGo 1.24系がすでに入っていたため、go install ... @latestを実行してみました。ログを見ると、要求バージョンに合わせてGoのツールチェインが自動的に1.26.11へ切り替わり、github.com/spf13/cobraやcharm.land/bubbleteaなどの依存パッケージを取得した上で、v0.4.6のビルドに成功しています。生成されたバイナリは$(go env GOPATH)/bin/gemini-apiに置かれ、サイズは約25.8MBでした。ビルドが通ったことから、依存関係の取得やコンパイルという面では公式の手順どおりに進められることは確認できましたが、前述のとおりこの先の実行確認はできていません。
コマンド構成:Create / Understand / Manage / Advancedの4系統
READMEのコマンド一覧表によると、gemini-apiのサブコマンドは大きく4系統に分かれています。「Create」系はgenerate(テキスト・マルチモーダル生成)、image(画像生成・編集)、tts(単一/複数話者の音声合成)、music(音楽生成)、video(対話的な動画生成・編集)。「Understand」系はanalyze(PDF・画像・音声・動画・CSV・YouTube URLへの質問応答)とtranscribe(音声・動画をmd/text/json/srt形式へ文字起こし)。「Manage」系はagent(モデルや管理エージェントの実行・状態確認・キャンセル)、files(Files APIでのアップロード・一覧・削除、保持期間48時間)、models(オフラインのモデルカタログ参照や、APIから取得するモデル一覧)、voices(カスタム音声の作成・管理)、configure/auth/whoami(認証・設定の管理)。「Advanced」系にはenvironments(セルフホスト環境を含むサンドボックス管理)、credentials(管理エージェント用の認証情報管理)、webhooks、triggers(管理エージェントのcronトリガー)が並びます。1つのバイナリに、モデル呼び出しからメディア生成、管理エージェントの運用管理までが詰め込まれている構成です。
エージェント向けの「自己説明」インターフェース
READMEが強調しているのは、このCLIが外部ドキュメントを読まなくてもエージェント自身で使い方を発見できるように作られている点です。--help/--usageでコマンドツリー全体をKDL形式の機械可読データとして取得でき、--schemaでリクエストボディのJSON Schema(draft 2020-12)をコマンドごとに出力できるとされています。--dry-runを付けると、認証情報やOSのキーチェーンへのアクセスを行わず、実際のネットワーク呼び出しもせずに、解決済みのHTTPリクエスト(認証情報は伏字)だけを確認できます。--agent-mode(または環境変数GEMINI_CLI_AGENT_MODE=1)を有効にすると、標準エラー出力の構造化やTOON形式の既定出力に切り替わり、終了コードも成功(0)・実行時/API失敗(1)・入力検証エラー(2)・認証エラー(3)に区別されると説明されています。READMEのクイックスタートには、AGENTS.mdやCLAUDE.mdといったエージェント設定ファイルに「gemini-apiをシェル経由で利用できる」ことを書き加える例が載っており、Claude Code自体の指示ファイルに組み込むことを前提にした作りであることがうかがえます。
想定ワークフロー例:画像生成とバックグラウンドの管理エージェント
README記載のワークフロー例の一つが、画像・音声・音楽・動画をその場で生成するものです。
MASCOT_PATH=$(gemini-api image \"A friendly robot mascot, soft studio lighting\" --out ./assets/mascot.jpg)\ngemini-api image \"Add a winter scarf and snowy background\" -i \"$MASCOT_PATH\" --out ./assets/mascot-winter.jpg\ngemini-api tts \"Welcome. Let's build something together.\" --out ./assets/welcome.wav
生成されたファイルパスだけが標準出力に返るため、呼び出し元のエージェントはそのパスを次の作業にそのまま使えるとされています。もう一つの例は、調査や多段階の作業を担う「管理エージェント」をバックグラウンドで起動するものです。
INTERACTION_ID=$(gemini-api agent run \"Research battery recycling approaches and cite sources\" \\\n --agent deep-research-preview-04-2026 \\\n --background \\\n --jq '.id')\ngemini-api agent status \"$INTERACTION_ID\" --stream=false --output-format json
--backgroundを付けるとストリームを張ったままにせず、返ってきたINTERACTION_IDを使って後から状態確認(agent status)やキャンセル(agent cancel)ができる、という流れです。READMEはこのCLI自身はローカルに会話状態を持たず、サーバー側のインタラクションやアップロード済みファイルの保持期限はAPI側が管理する、とも説明しています。
この記事で確認できなかったこと
このクラウド環境ではgo installによるビルド自体は成功し、実行ファイルの生成までは確認できました。しかし、新しく生成した実行ファイルをこの検証環境のセキュリティポリシー上直接実行することができなかったため、gemini-api --helpやgemini-api versionの実際の出力は確認していません。また有効なGemini APIキーも用意していないため、generate・image・analyze・agent runといったコマンドの実際のレスポンス、--dry-runが出力するリクエストプレビューの実物、--usageが出力するKDL形式の内容も未確認です。本稿はあくまで公式README・LICENSE・CONTRIBUTING.md・Releasesページという一次情報の記載に基づく整理です。
向いている場面・まだ注意が必要な場面
- 向いている:Claude CodeやCodexのようなコーディングエージェントに、画像・音声・動画の生成やPDF・動画の読解、あるいは時間のかかる調査タスクの委任先を持たせたい場合。
--schemaや--dry-runでリクエスト内容を事前に検証できる設計は、エージェントが自律的に試行する用途に向いていそうです - まだ注意が必要:README自身が「
gemini-apiはベータ版で、Gemini Interactions APIとともに変化し続けており、リリース間で破壊的変更が起こり得る」と明記しているほか、CONTRIBUTING.mdでは外部からのPull Requestを現時点では受け付けないとも書かれています。CI等で使う場合はREADMEの案内どおり特定のリリースバージョンに固定したほうが安全です。また、Gemini CLI・Antigravity CLI・Gemini API CLIという3つの似た名前のツールが並行して存在するため、導入前にどの役割のツールかを公式リポジトリのREADMEで確認することをおすすめします
まとめ
Gemini API CLIは、Gemini CLIやAntigravity CLIのような「対話的にコードを書くエージェント」そのものではなく、Claude CodeやCodexなど既存のエージェントにGeminiのモデル・メディア生成・管理エージェントという“道具”を渡すための、ステートレスな単一バイナリです。公式READMEの記載を整理した範囲では、--schemaや--dry-runによってエージェントが安全に試行できるよう設計されている点が特徴的でした。このクラウド環境ではgo installによるビルドまでは確認できたものの、実機での実行やAPIキーを使った実際の応答確認はできなかったため、導入を検討する場合は公式リポジトリの手順に沿って、自分の環境で一度動かしてみることをおすすめします。
