30秒で理解する Gemini CLI
・何者か：Googleが公式に公開する、ターミナルで動くオープンソースのAIエージェント（google-gemini/gemini-cli、Apache 2.0、GitHubで10万スター超）
・始め方：npm install -g @google/gemini-cli の後 gemini と打つだけ。Googleアカウントでログインすれば無料枠は1分60回・1日1,000回
・強み：最大100万トークンのコンテキスト、Google検索グラウンディング標準搭載、GEMINI.mdによるプロジェクト指示、MCP連携、Agent Skills対応
「Gemini CLI」はGoogleが公式に公開しているコマンドライン型のAIエージェントだ。ブラウザのGeminiやGoogle AI Studioを開かなくても、ターミナルから直接Geminiモデルに指示を出し、コードを読ませ、ファイルを編集させ、シェルコマンドまで実行させられる。この記事ではGoogle公式リポジトリの一次情報をもとに、インストールから認証、主要コマンド、GEMINI.md設定、そしてClaude CodeやCodex CLIとの違いまでを通しで整理する。
AIをターミナルから操るという発想は、AnthropicのClaude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引きが火を付け、いまやAIコーディングCLIの一大ジャンルになっている。Gemini CLIはその系譜にGoogleが本気で投じたツールであり、寛容な無料枠を武器に裾野を広げている。
Gemini CLIは、AIコーディングツールを横断的に使いこなす「バイブコーディング」の一角を占めるツールでもある。ツール選定や実践ワークフローの全体像は Vibe Codingとは？AIコーディングの始め方・ツール比較・実践ワークフロー2026 を先に押さえておくと、本記事の位置づけがつかみやすい。
Gemini CLIとは——コマンドラインで動くGoogle公式AIエージェント
Gemini CLIは公式に「Geminiの力をターミナルに直接持ち込むオープンソースのAIエージェント」と説明されている。単なるチャットのラッパーではなく、ファイルシステム操作・シェルコマンド実行・Web取得・Google検索といった組み込みツールを持ち、与えたタスクを自分で分解して実行まで完了させる自律エージェントとして設計されている点が核心だ。
リポジトリはgoogle-gemini/gemini-cliで公開され、ライセンスはApache 2.0、実装はTypeScriptが中心だ。GitHubスターは10万を超え、リリース数は500以上と更新ペースが非常に速い。本記事執筆時点の安定版はv0.46.0（2026年6月10日）で、週次・日次で新バージョンが出る活発なプロジェクトになっている。
最大の特徴は「Googleアカウントのログインだけで寛容な無料枠が使える」点だ。Googleログイン経由なら1分あたり60リクエスト・1日あたり1,000リクエストが無料で割り当てられる。APIキーの発行やクレジットカード登録なしに、本格的なエージェント作業を体験できる敷居の低さは大きな魅力だ。
Gemini CLIが何を解決するのかを一言でいえば、「エディタとブラウザを行き来しながら手でやっていたコード読解・修正・調査を、ターミナルの中で対話ひとつに畳み込む」ことだ。従来はコードをコピーしてブラウザのGeminiに貼り、返ってきた答えを手でエディタに戻す、という往復が発生していた。Gemini CLIはその往復を消し、AIがローカルのファイルを直接読み書きし、必要ならシェルコマンドやWeb検索まで自分で実行する。何を代替するのかという視点でも整理しやすい。単なるチャットボットの置き換えではなく、GitHub CopilotのようなIDE補完、ブラウザ版Gemini、そして「ドキュメントを検索して読む」という調査作業そのものを、コマンドライン上のひとつのエージェントに束ねる。とくにGoogle検索グラウンディングが標準で組み込まれているため、「最新のライブラリ仕様を調べてからコードを直す」といった調査込みのタスクを、外部ツールを継ぎ足さずに1本のCLIで完結できるのが独自の立ち位置だ。
何ができるか：主要機能一覧
公式が挙げる代表的な機能は次の通りだ。コード補完にとどまらず、大規模コードベースの理解からマルチモーダル入力、外部ツール連携までを一本のCLIでカバーする。
| 機能 | 概要 |
|---|---|
| コード理解・生成 | 大規模コードベースを読み込み、文脈に沿った生成・修正を行う |
| マルチモーダル入力 | PDF・画像・スケッチを入力として扱える |
| Google検索グラウンディング | 検索結果を根拠にした最新情報の取得が標準で組み込み |
| MCP連携 | Model Context Protocolで外部ツール・サービスを統合 |
| チェックポイント | 会話の状態を保存・復元（checkpointing） |
| トークンキャッシュ | 繰り返しの文脈送信を圧縮しコストを抑える |
| GEMINI.md | プロジェクト固有の指示を全リクエストに自動添付 |
| Agent Skills | agentskills.io標準の「スキル」で専門能力を後付け |
| GitHub連携 | 専用のGitHub Action経由でCIに組み込み可能 |
無料枠でどこまでできるか
Googleログイン方式の無料枠は1分60回・1日1,000回。Gemini APIキー方式の無料ティアも1日1,000回が用意されている。個人開発や学習なら無料枠の範囲で十分実用的に回る。組織利用や上限超過時にCode Assistライセンス・Vertex AIへ切り替える設計だ。
下図はGemini CLIの全体像だ。ユーザーの指示が組み込みツール群とMCPサーバー、そして複数のGeminiモデルへどう流れるかを俯瞰している。
ターミナル入力"] --> CLI["Gemini CLI
エージェント本体"] CLI --> CTX["GEMINI.md
プロジェクト指示"] CLI --> TOOLS["組み込みツール
ファイル / シェル / Web検索"] CLI --> MCP["MCPサーバー
GitHub / Slack / DB など"] CLI --> MODEL["Geminiモデル
Gemini 3 Pro / 2.5 Flash"] MODEL --> ROUTE["モデルルーティング
失敗時に自動フォールバック"]
Gemini CLIのインストール（npm・npx・Homebrew）
Gemini CLIはNode.js上で動くため、まずNode.jsが入っている前提でインストールする。公式リポジトリはNode.js 20以上を要求しており、古いバージョンだと起動時にエラーになる。node -vでバージョンを確認し、20未満ならNode.js公式やnvmなどで上げておく。導入方法は複数あり、用途に応じて選べる。一番素直なのはnpmでのグローバルインストールだ。
# npmでグローバルインストール（推奨）
npm install -g @google/gemini-cli
# インストールせずに一回だけ試す
npx @google/gemini-cli
# macOS / Linux（Homebrew）
brew install gemini-cli
# macOS（MacPorts）
sudo port install gemini-cli
インストールが終わったら、gemini --versionでバージョンが表示されるか確かめてから、プロジェクトのディレクトリでgeminiと打つだけで対話モード（REPL）が立ち上がる。初回起動時は認証方法を選ぶ画面が出るので、まずはGoogleログインを選ぶのが手早い。アップデートはgemini updateで最新の安定版に上げられる。npm install -gで権限エラー（EACCES）が出る場合は、sudoで無理に入れるより、nvmでユーザー領域にNode.jsを入れ直すかnpmのグローバルディレクトリを自分のホーム配下に変更するのが安全だ。まず試すだけならインストール不要のnpx @google/gemini-cliが手軽で、環境を汚さずに最新版を都度ダウンロードして実行できる。
リリースチャンネルを使い分けられるのもポイントだ。安定版は毎週火曜に、先行版は週次、開発版は毎日更新される。新機能をいち早く試したい場合はバージョン指定でインストールチャンネルを切り替えればよい。
# 安定版（既定。毎週火曜更新）
npm install -g @google/gemini-cli@latest
# プレビュー版（先行機能。毎週火曜更新）
npm install -g @google/gemini-cli@preview
# ナイトリー版（毎日更新）
npm install -g @google/gemini-cli@nightly
会社のプロキシ環境などNode.jsを直接入れにくいケースでは、Anaconda経由で隔離環境にNode.jsを用意してからインストールする方法も公式に案内されている。restricted環境での導入に詰まったら、conda環境を作ってその中でnpm install -g @google/gemini-cliを実行する手が使える。
認証の3つの方法——Googleログイン・APIキー・Vertex AI
Gemini CLIの認証は大きく3通りある。それぞれ無料枠の条件と向いている用途が違うので、自分の状況に合うものを選ぶ。下の図でまず全体像をつかむとよい。
無料 60回/分・1000回/日"] Q1 -->|"スクリプト連携したい"| APIKEY["GEMINI_API_KEY
無料ティア 1000回/日"] Q1 -->|"組織のGCP基盤で"| VERTEX["Vertex AI
GOOGLE_API_KEY + フラグ"] GLOGIN --> PAID["上限超過時:
GOOGLE_CLOUD_PROJECT で
Code Assistライセンス"]
方法1：Googleログイン（最も手軽）
ターミナルでgeminiと打つと、ブラウザが開いて「Sign in with Google」を選ぶ流れになる。これだけで無料枠（1分60回・1日1,000回）が割り当てられる。個人で試すなら迷わずこれでよい。
# 起動してブラウザでGoogleログインを選ぶだけ
gemini
# 有料のCode Assistライセンスを使う場合はプロジェクトIDを指定
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
gemini
方法2：Gemini APIキー（スクリプト連携向け）
Google AI Studioで取得したAPIキーを環境変数GEMINI_API_KEYに入れて使う方法だ。CI/CDやスクリプトから非対話で呼び出すときに向いている。無料ティアでも1日1,000リクエストが使える。
# Google AI Studioでキーを取得し環境変数にセット
export GEMINI_API_KEY="YOUR_API_KEY"
gemini
方法3：Vertex AI（組織・GCP基盤向け）
Google CloudのVertex AI経由で使う場合は、GOOGLE_API_KEYと、Vertex利用を明示するGOOGLE_GENAI_USE_VERTEXAI=trueをセットする。社内のGCP課金やガバナンスに乗せたい組織向けの構成だ。
export GOOGLE_API_KEY="YOUR_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini
どれを選ぶべきか
迷ったらまずGoogleログイン方式で体験するのが一番速い。スクリプトやCIに組み込むならGEMINI_API_KEY方式、会社のGCP課金・監査要件に合わせるならVertex AI方式、という整理で問題ない。
3つの認証方式は「無料枠の性格」も少しずつ違う。Googleログイン方式の無料枠（1分60回・1日1,000回）は個人が対話しながら使う分には十分だが、大量のファイルを一気に読ませたり短時間に連続実行したりすると分あたりの上限に当たりやすい。その場合はモデルをflash系に落としてリクエスト単価を軽くする、あるいはリクエストを間引く、といった調整が効く。一方でGemini APIキー方式の無料ティア（1日1,000回）は非対話のスクリプトから叩く前提のため、CIの定期ジョブや一括処理と相性がよい。上限を超えて安定運用したくなったら、Googleログイン方式のままGOOGLE_CLOUD_PROJECTを指定してGoogle CloudのCode Assistライセンス（有料枠）に載せるのが最短の移行経路だ。プロジェクトIDを一度指定してしまえば、コマンドの打ち方は無料枠のときと変わらない。組織で監査ログや課金の一元管理が要件になるなら、最初からVertex AI方式でGCPのガバナンスに乗せておくと後の移行コストが小さい。要は「個人＝Googleログイン」「自動化＝APIキー」「組織＝Vertex AI」を軸に、上限に当たったら一段上へ、という増やし方が定石だ。
主要コマンドとスラッシュコマンド一覧
Gemini CLIの操作は「ターミナルから打つCLIコマンド」と「対話中に打つスラッシュコマンド」の2系統に分かれる。まずCLI側の基本を押さえる。
# 対話モード（REPL）を起動
gemini
# 非対話で一度だけ問い合わせ（CI向け）
gemini -p "summarize README.md"
# 実行して、そのまま対話を続ける
gemini -i "このプロジェクトの目的は?"
# 直近のセッションを再開
gemini -r "latest"
# パイプで標準入力を渡す
cat logs.txt | gemini
# 出力をJSONで受け取る（スクリプト連携）
gemini -p "依存関係を一覧" --output-format json
よく使うフラグは次の通り。モデル指定の--model、承認モードの--approval-mode、安全実行の--sandboxあたりは覚えておくと便利だ。
| フラグ | 別名 | 役割 |
|---|---|---|
--model |
-m |
使うモデルを指定（auto/pro/flash/flash-lite など） |
--prompt |
-p |
プロンプトを渡して非対話実行 |
--prompt-interactive |
-i |
実行後にそのまま対話継続 |
--approval-mode |
— | ツール実行の承認方式（default/auto_edit/yolo/plan） |
--sandbox |
-s |
サンドボックス環境で安全に実行 |
--include-directories |
— | ワークスペースに追加ディレクトリを含める |
--resume |
-r |
過去セッションを再開（latestや番号指定） |
--output-format |
-o |
出力形式（text/json/stream-json） |
--worktree |
-w |
新しいgit worktreeで起動（要experimental設定） |
使えるモデルとエイリアス
--modelにはエイリアスと正式名のどちらも渡せる。普段はエイリアスで十分だ。Gemini 3系は最大100万トークンの長大なコンテキストに対応する。
| エイリアス | 解決先 | 用途 |
|---|---|---|
auto |
gemini-2.5-pro または gemini-3-pro-preview |
既定。preview有効なら先行モデルへ |
pro |
gemini-2.5-pro / gemini-3-pro-preview |
複雑な推論タスク |
flash |
gemini-2.5-flash |
速度と性能のバランス型 |
flash-lite |
gemini-2.5-flash-lite |
最速・軽量タスク向け |
モデルの優先順位は「--modelフラグ→環境変数GEMINI_MODEL→settings.jsonのmodel.name」の順で決まる。さらにモデルルーティング機能があり、選択中のモデルがクォータ超過やサーバーエラーで失敗したときに自動でフォールバックモデルへ切り替えてくれる。実験的機能として、ローカルのGemmaモデルにルーティング判断を任せるgemini gemma setupも用意されている。
使い分けの目安はシンプルで、難しい設計や広いコードベースの読解にはpro、こまめな修正や定型作業にはflash、大量の軽いリクエストを高速にさばきたいときはflash-liteを選ぶ。無料枠は分あたり・日あたりのリクエスト数で制限されるので、flash系に寄せるほど同じ枠内で多く回せる。まずは既定のautoに任せておき、レスポンスが物足りない場面だけ--model proで明示的に上げる、という運用がもっとも無駄がなく、無料枠の消費も抑えられる。
スラッシュコマンドとアットマーク・シェル連携
対話中はスラッシュコマンドで状態を操作する。代表的なものは次の通りだ。
・/help：全コマンドのヘルプを表示
・/memory show／/memory reload：GEMINI.mdの内容確認・再読み込み
・/mcp reload：MCPサーバーの再起動・再読み込み
・/commands list／/commands reload：カスタムコマンドの一覧・再読み込み
・/skills reload／/agents reload：スキル・エージェントの再読み込み
・/plan [goal]：プランモードへ切り替え（読み取り専用で設計を固める）
・/quit：対話セッションを終了
これに加えて、@で特定ファイルを文脈に取り込んだり、@githubのように登録済みMCPサーバーを名指しで呼び出したりできる。!を頭に付けるとシェルコマンドのパススルー実行になる。@github 私のオープン中のPRを一覧してや@slack 今日のコミットの要約を #dev に送ってといった自然言語の指示が、そのままMCP経由のアクションになる点がエージェントらしいところだ。
プランモードで「設計してから実装」する
/planまたはキーボードのShift+Tabで承認モードを循環（Default→Auto-Edit→Plan）させると、読み取り専用のプランモードに入れる。これはコードを書き換える前に、調査・設計・戦略合意を済ませるための環境だ。プランモードは既定で有効になっており、いきなりファイルを変更されるのが不安な場面で重宝する。gemini --approval-mode=planで起動時から有効にもできる。
組み込みツール：ファイル・シェル・Web・メモリ
Gemini CLIが「チャットのラッパー」ではなく「エージェント」と呼べるのは、モデルが自分で呼び出せる組み込みツールを最初から備えているからだ。ユーザーが「このバグを直して」と指示すると、Gemini CLIは自分でファイルを読み、修正を書き込み、テストコマンドを走らせ、必要ならWebで最新仕様を調べる——という一連の動作を、追加設定なしで実行できる。主な組み込みツールは次のカテゴリに分かれる。
・ファイルシステム：ファイルやディレクトリの読み取り・書き込み・一覧・検索。複数ファイルをまたいだ一括読み取りで大規模コードベースの文脈を取り込む
・シェル実行：npm testやgit statusなどのコマンドを実行し、その出力を次の判断材料にする
・Web取得（fetch）：指定URLのページ内容を取り込んで文脈に加える
・Google検索グラウンディング：検索結果を根拠に、モデルの学習時点より新しい情報を取得する
・メモリ（save_memory）：会話をまたいで覚えておきたい事実を保存する
これらのツールは実行前に承認を求めるのが既定の挙動で、ファイル書き換えやシェル実行のたびに「実行してよいか」を確認する。危険なコマンドを勝手に走らせない安全弁として機能するわけだ。前述の承認モード（Default／Auto-Edit／yolo／plan）は、この確認の粒度を切り替えるスイッチだと理解すると腑に落ちる。信頼できる作業はAuto-Editで確認を減らし、未知のリポジトリはplanで読み取り専用に固める、といった使い分けができる。
GEMINI.md・カスタムコマンド・MCP・設定で自分仕様にする
Gemini CLIを「自分のプロジェクト専用アシスタント」に育てる鍵がGEMINI.mdだ。プロンプトのたびに同じ前提を書き直す代わりに、コーディング規約やプロジェクトの背景を一度書いておけば、全リクエストに自動で添付される。
読み込みは階層構造になっている。~/.gemini/GEMINI.mdが全プロジェクト共通の指示、ワークスペース配下のGEMINI.mdがそのプロジェクト固有の指示、そしてツールがファイルにアクセスした瞬間にその近辺を走査して読み込むJIT（必要時読み込み）の3層だ。CLIのフッターに読み込まれたコンテキストファイル数が出るので、意図した指示が効いているか一目で確認できる。
# Project: My TypeScript Library
**General Instructions**
- 新規のTypeScriptコードは既存のスタイルに合わせる
- すべての関数とクラスにJSDocコメントを付ける
- 適切な場面では関数型のパラダイムを優先する
**Coding Style**
- インデントはスペース2つ
- インターフェース名は接頭辞 I を付ける（例: IUserService）
- 厳密等価（=== と !==）を常に使う
この仕組みはClaude CodeのCLAUDE.md、Codex CLIのAGENTS.mdと同じ思想だ。エージェントに渡す「常駐の前提知識」をファイルで管理する流れは、いまやAIコーディングCLIの共通作法になっている。
繰り返し使うプロンプトは、カスタムコマンドとしてTOMLファイルに保存できる。~/.gemini/commands/test.tomlを置けば/test、<project>/.gemini/commands/git/commit.tomlを置けば/git:commitという名前空間付きコマンドになる。プロジェクト側のコマンドはユーザー側より優先されるので、チームで共有しつつ個人設定を上書きできる。
# ~/.gemini/commands/review.toml
description = "ステージ済みの差分をレビューする"
prompt = """
git diffのステージ済み変更をレビューし、
バグ・セキュリティ・可読性の観点で指摘してください。
対象: {{args}}
"""
さらに、agentskills.io標準に準拠したAgent Skillsで専門能力を後付けできる。スキルはセキュリティ監査やクラウドデプロイといった手順とリソースを1つのディレクトリにまとめたもので、gemini skills install <ソース>で導入し、タスクに合致したときだけ自動で有効化される。~/.gemini/skills/がユーザー単位、.gemini/skills/がワークスペース単位の配置場所だ。
MCPで外部ツールとつなぐ
Gemini CLIの拡張性を一段引き上げるのがMCP（Model Context Protocol）への対応だ。MCPは「AIエージェントに外部ツール・データソースをつなぐための共通規格」で、GitHub・Slack・データベースなどをMCPサーバーとして登録すると、Gemini CLIから自然言語でそれらを操作できるようになる。登録はgemini mcp addコマンドで行う。
# stdio型のMCPサーバーを登録（コマンドを起動して標準入出力でやり取り）
gemini mcp add github npx -y @modelcontextprotocol/server-github
# HTTP型のサーバーを登録する場合
gemini mcp add --transport http mytools https://example.com/mcp
# ユーザー単位（全プロジェクト共通）で登録
gemini mcp add --scope user github npx -y @modelcontextprotocol/server-github
# 登録済みサーバーの一覧
gemini mcp list
登録後は対話中に@github 私のオープン中のPRを一覧してのようにアットマークでサーバーを名指しして呼び出す。設定を変えたときは/mcp reloadで再読み込みできる。MCPを噛ませることで、Gemini CLIは「コードを書くエージェント」から「開発環境全体を操作するエージェント」へ広がる。同じMCP規格はClaude CodeやCodex CLIも採用しており、一度作ったMCPサーバーは各CLI間で使い回せるのも利点だ。
settings.jsonとチェックポイントで挙動を整える
プロジェクトやユーザー単位の細かな挙動はsettings.jsonで制御する。~/.gemini/settings.jsonがユーザー全体、ワークスペース配下の.gemini/settings.jsonがプロジェクト固有の設定で、後者が優先される。既定モデルの固定、テーマ、ツールの自動承認範囲、実験的機能の有効化などをここにまとめておくと、起動のたびにフラグを打ち直す必要がなくなる。
{
"model": { "name": "gemini-2.5-pro" },
"general": { "checkpointing": { "enabled": true } },
"experimental": { "worktrees": true }
}
checkpointingを有効にすると、ファイルを編集する前の状態が自動で保存され、エージェントの変更が気に入らなければ巻き戻せる。AIに大きくコードをいじらせるときの「取り消しボタン」として効く安全機能だ。設定が意図通り効いているかは、対話中の/memory showや起動時のフッター表示で確認できる。
Claude Code・Codex CLIとの違い
「ターミナルで動くAIコーディングエージェント」というジャンルには、Gemini CLIのほかにAnthropicのClaude Code、OpenAIのCodex CLIがある。三者は競合しつつ補完的でもあり、土台のモデルと設定ファイル、無料枠の考え方が異なる。
| 項目 | Gemini CLI | Claude Code | Codex CLI |
|---|---|---|---|
| 提供元 | Anthropic | OpenAI | |
| 土台モデル | Gemini 3 / 2.5系 | Claude Sonnet 5 / Opus 4.8 | GPT-5.5系 |
| ライセンス | Apache 2.0（OSS） | 公式CLI | Apache 2.0（OSS） |
| 設定ファイル | GEMINI.md |
CLAUDE.md |
AGENTS.md |
| 無料での入口 | Googleログインで60回/分・1000回/日 | 要サブスク/API | ChatGPTプラン/API |
| コンテキスト | 最大100万トークン（Gemini 3） | モデル依存 | モデル依存 |
| 検索グラウンディング | Google検索が標準搭載 | Web検索ツール | Web検索（既定有効） |
| MCP連携 | 対応 | 対応 | 対応 |
Gemini CLIの差別化ポイントは「寛容な無料枠」「100万トークンの長大コンテキスト」「Google検索グラウンディングの標準搭載」の3点だ。とくにGoogleアカウントだけで本格的なエージェント作業を無料で試せる敷居の低さは、初めてAIコーディングCLIに触れる人にとって大きい。
一方で、Claude Codeは緻密なペアプログラミング体験と運用ノウハウの蓄積、Codex CLIはOpenAIエコシステムとの統合や非対話自動化に強みがある。実務では「設計はClaude Code、検索を絡めた調査はGemini CLI」のように使い分ける開発者も増えている。各ツールの詳細はClaude Codeの実装手引きとCodex CLI 使い方完全ガイドを参照してほしい。Gemini単体のWeb版・API活用はGeminiの使い方で別途まとめている。
2026年後半のアップデートで各社のモデル世代も動いている。Claude CodeはClaude Sonnet 5世代に移り、Opus級の品質をSonnet価格帯で使える構成が既定になった（詳細はClaude Sonnet 5解説）。Gemini CLI側もGemini 3系の既定化が進み、100万トークンの長大コンテキストと無料枠の広さから「大規模コンテキストの調査・読解はGemini CLI、緻密な実装はClaude Code」という住み分けがより明確になっている。
結局どれを選ぶべきかは、目的とコストで割り切ると迷わない。「まず無料でAIコーディングを体験したい」「お金をかけずに大きめのコードベースをまとめて読ませたい」ならGemini CLIが第一候補になる。Googleアカウントさえあれば始められ、100万トークンのコンテキストで数十ファイルを一度に渡せるうえ、Google検索グラウンディングで最新情報の裏取りまで1本で完結するからだ。一方で日々の実装を腰を据えて任せるならClaude Code、OpenAIのモデルやChatGPTのサブスクを既に使っているならCodex CLI、という選び方になる。3つは排他ではないので、設定ファイルこそGEMINI.md／CLAUDE.md／AGENTS.mdと別々だが、同じリポジトリで併用し、タスクによって呼び分ける開発者も多い。まずは無料のGemini CLIで「ターミナル内でAIにコードを触らせる」という感覚に慣れるのが、どのCLIに進むにしても遠回りにならない。
Gemini CLIのトラブルシューティングとまとめ
導入時につまずきやすいポイントと対処を整理する。多くは認証・モデル・権限まわりに集約される。
認証エラー・無料枠の上限に当たる
gemini起動時に認証が通らない場合は、まずどの認証方式を使っているか確認する。Googleログイン方式で1分60回・1日1,000回の上限に達するとレート制限がかかる。継続的に上限へ当たるなら、GEMINI_API_KEY方式に切り替えるか、GOOGLE_CLOUD_PROJECTを指定してCode Assistライセンス・Vertex AIへ移行する。
モデルが意図通り選ばれない
--modelを指定しても別モデルで動いているように見えるときは、優先順位を思い出す。--modelフラグが最優先で、次に環境変数GEMINI_MODEL、最後にsettings.jsonのmodel.nameだ。加えてモデルルーティングが働くと、選択中モデルの失敗時に自動でフォールバックすることがある。意図せぬ切り替えが起きたら、フォールバックの確認プロンプトが出ていないか見直す。
ファイル変更を勝手に行われたくない
エージェントが確認なしにファイルを書き換えるのが不安なら、承認モードを使う。Shift+TabでDefault→Auto-Edit→Planを循環でき、/planで読み取り専用のプランモードに入れば、設計を固めてから実装に移れる。逆にCIなどで全自動にしたい場合は--approval-mode=yoloを使う（旧--yoloは非推奨）。
コマンド実行を隔離したい
未知のリポジトリでシェルコマンドを走らせるのが怖いときは--sandbox（-s）でサンドボックス環境内に隔離して実行する。git worktreeと組み合わせる--worktree（-w）も、作業を本流から切り離して試すのに役立つ（experimental.worktrees: trueの設定が必要）。
カスタムコマンドやMCPが反映されない
.tomlのカスタムコマンドを追加・編集したのに反映されないときは、CLIを再起動せずとも/commands reloadで読み込み直せる。MCPサーバーの設定を変えた場合は/mcp reload、GEMINI.mdを更新した場合は/memory reloadで再読み込みする。設定が効いているかは/memory showやgemini mcp listで確認できる。
企業プロキシ・ネットワーク環境でつながらない
社内ネットワークやプロキシ環境では、Googleログインのブラウザ認証やAPI通信がプロキシに阻まれて失敗することがある。多くはHTTPS_PROXY／HTTP_PROXY環境変数をプロキシのURLに設定することで解決する。ブラウザ認証のリダイレクトが戻ってこない場合は、GoogleログインをあきらめてGEMINI_API_KEY方式に切り替えるほうが早いこともある。そもそもNode.jsをインストールできない厳しい環境では、前述のAnaconda/conda経由でNode.jsを隔離環境に用意する手が有効だ。Web検索グラウンディングが効かないように見えるときは、対象モデルや認証方式によって使える機能が違う点、そしてプロキシがGoogleの検索エンドポイントへの通信を遮断していないかを順に確認するとよい。
GEMINI.mdの指示が効いていないように見える
「規約を書いたのにGeminiが守らない」ときは、まずCLIフッターに表示される読み込み済みコンテキストファイル数を見る。0件なら、そもそもGEMINI.mdが読み込まれていない。ファイル名の綴り（大文字小文字）と置き場所（~/.gemini/GEMINI.mdかワークスペース直下か）を確認し、/memory showで実際に読み込まれている内容を表示させて突き合わせる。指示が長すぎて他の文脈に埋もれている場合は、要点を箇条書きに絞ると効きが良くなる。
まとめ：まずGoogleログインで触ってみる
Gemini CLIは、Googleアカウントひとつで本格的なAIコーディングエージェントを無料で試せる、入口の広いツールだ。npm install -g @google/gemini-cliしてgeminiと打つだけで対話が始まり、GEMINI.mdで自分のプロジェクト専用に育て、MCPやAgent Skillsで能力を拡張していける。最大100万トークンのコンテキストとGoogle検索グラウンディングという土台の強さは、調査を絡めた開発タスクで効いてくる。無料枠で感触をつかんだら、認証をAPIキーやVertex AIに切り替えて自動化やチーム利用へ広げる、という順序で無理なくステップアップできる。Claude CodeやCodex CLIと使い分けながら、自分のワークフローに合うCLIを見極めていくとよい。
参照ソース
・google-gemini/gemini-cli — GitHub公式リポジトリ（README・インストール・認証・機能の一次情報）
・Gemini CLI cli-reference — 公式ドキュメント（コマンド・フラグ・モデル一覧）
・Gemini CLI gemini-md / custom-commands / skills / plan-mode — 公式ドキュメント
