release notes を上から読んでいて、10/27 の行で手が止まりました。「Gemini API CLI（gemini-api）がベータで登場」。名前のなかに Gemini も CLI も入っているので、一瞬、既存の Gemini CLI の新しい姿だと受け取ってしまったのです。
念のため GitHub の README を開いて、読み違いに気づきました。別の道具でした。入れてから気づくより、入れる前に気づけてよかったと思っています。ここからは、README と install スクリプトの冒頭を読んで私が付けた線引きを、書き残してまいります。
なお、先にお断りしておきます。私はこの記事を書いた時点で、gemini-api を実際に走らせて課金の出る呼び出しをしたわけではありません。ここに書くのは「読んで確かめられたこと」と「入れる前に私が決めたこと」です。動作の実測値は載せていません。
最初にお伝えしたいのは、コーディングエージェントではないということ
README の説明を要約すると、gemini-api は Gemini Interactions API をシェルから呼ぶための単機能コマンド群です。Go 製の単一バイナリで、ローカルに会話の状態を持ちません。
一方、Gemini CLI は対話しながらファイルを読み書きし、コマンドを実行するコーディングエージェントでした。個人向けの提供が 6/18 で止まったことは、先に個人向け提供停止の移行計画にまとめています。つまり gemini-api を「Gemini CLI の置き換え」として入れても、期待した動きにはなりません。
| 道具 | 役割 | 状態の持ち方 | 向いている場面 |
|---|---|---|---|
| Antigravity CLI など（旧 Gemini CLI の後継の流れ） | 対話してコードを書き換えるエージェント | セッション単位 | 人が横にいる開発作業 |
| gemini-api（ベータ） | Interactions API を呼ぶ 1 回きりのコマンド | CLI 側は持たない | スクリプト・CI・他のエージェントからの呼び出し |
| google-genai SDK | アプリのコードから API を呼ぶ | コード側で管理 | 製品に組み込む処理 |
README が挙げているコマンドは、生成系（generate・image・tts・music・video）、理解系（analyze・transcribe）、管理系（agent・files・models・configure・whoami）、それに environments・credentials・webhooks・triggers です。眺めてみて、これは「人が使う道具」というより、シェルを扱えるエージェントや CI が持ち歩く道具箱なのかもしれません。
入れる前に確かめられること — dry-run と whoami
多言語のストア文面や画像の下ごしらえを、個人開発のなかでスクリプトから回す場面を考えると、この道具が効きそうな場所は思い浮かびます。ただ、ベータで課金が絡む道具に、最初から本番のキーを渡したくはありません。
そこで私が最初に試すと決めたのは、ネットワークに出ない --dry-run です。README によれば、入力を検証し、認証情報を伏せた HTTP リクエストを表示するだけで、通信もキーチェーンの読み取りも行いません。
# 解決したいこと: 課金の前に「何が送られるか」を目で確かめる
# 試すキーはまだ設定しない。--dry-run は通信しない
gemini-api generate "Hello from my agent" --dry-run
# 送るリクエストの型を知りたいときは JSON Schema を書き出す
gemini-api image --schema > image-schema.json
# コマンド全体の地図（フラグ・既定値・環境変数）を機械可読な形で出す
gemini-api --usage > gemini-api-usage.kdlなぜこの順にするのか。--schema と --usage で「何を渡せるか」を先に把握し、--dry-run で「実際に何が組み立てられるか」を確かめれば、課金の出る呼び出しをする前に、引数の取り違えをほとんど潰せるからです。出力の細部は私の環境ではまだ見ていないので、お手元で確かめていただければ幸いです。
キーを設定するときは、環境変数か configure を使います。どのキーが効いているかは whoami で確かめられます。
# 作業用の端末にだけキーを置く場合
export GEMINI_API_KEY="YOUR_API_KEY"
gemini-api whoami # 有効な設定と、認証情報の出どころを確認するREADME では、キーを OS のキーチェーンか ~/.config/gemini-api/config.yaml に保存することもできると案内されています。共有の CI 端末に configure で永続化するのは避け、そこでは環境変数だけで渡すのが私の好みです。
CI に入れるなら、版を固定する
README は、ベータなので版の間で破壊的な変更がありうると注意しています。そのうえで CI や自動化では特定のリリースを固定するよう勧めています。
install スクリプトの冒頭を読むと、GEMINI_VERSION で版を、GEMINI_INSTALL_DIR で入れる先を指定できると書かれていました。既定は /usr/local/bin、書けないときは ~/.local/bin に入れる作りのようです。
# 解決したいこと: 「最新」ではなく、確かめた版だけを CI に入れる
# 1) スクリプトを一度ファイルに落として、中身を読んでから実行する
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh -o install.sh
less install.sh
# 2) 版と入れ先を明示する（VERSION は GitHub Releases で確認した値に置き換える）
GEMINI_VERSION="vX.Y.Z" GEMINI_INSTALL_DIR="$HOME/.local/bin" bash install.shREADME にある curl ... | bash の一行は手軽ですが、私は一度ファイルに落として読んでから実行するようにしています。外から取ってきたスクリプトに、読まずに権限を渡すことは避けています。ベータの道具ならなおさらです。
読み飛ばしかけた点 — 「CLI が状態を持たない」は「何も残らない」ではない
最初のうち、私は「ステートレス」という言葉を、そのまま「どこにも履歴が残らない」と受け取りかけていました。結果から言うと、それは読み違いです。
README が述べているのは、CLI がローカルに会話の状態を持たない、という点だけです。サーバー側の interaction や、アップロードしたファイルには、それぞれの保持の仕組みがあります。さらに 10/26 の release notes では、新しい有料プロジェクトで Generate Content API の store が既定でオンになりました。個人情報を含む入力をスクリプトに流すなら、CLI の性質ではなく、呼び出し先の保存設定を見る必要があります。
この点は、状態をサーバー側に置くか手元で刈り込むかを比べたInteractions API の状態管理の記事とも地続きです。
読み違えに気づいたあとで、私は次のように線引きを改めました。CLI が忘れることと、サーバーが覚えていることは、別々に確かめます。 個人開発の手元スクリプトでも、この二つを混ぜないようにしています。
どこから始めるか
私の現時点の判断は、次のとおりです。
- 人が横にいる開発作業は、これまでどおり対話型のエージェントに任せ、
gemini-apiには置き換えません - シェルや CI から 1 回きりで呼びたい処理だけを、
gemini-apiの候補にします - 候補にした処理は、まず
--dry-runと--schemaで形を確かめ、課金の出る呼び出しはその後にします - CI へ入れる前に、版を固定し、スクリプトの中身を読みます
似た整理は、Gemini CLI と Claude Code の比較でも、役割で道具を分ける形で書いています。
まずは手元の端末で gemini-api generate "Hello from my agent" --dry-run を一本だけ打ち、何が組み立てられるかを眺めるところから始めていただければと思います。ベータの道具とは、そのくらいの距離から付き合い始めるのがちょうどよい——と、いまは感じています。