Gemini CLI authentication setup

概要

Google での認証方法。個人アカウント、組織アカウント、Gemini API キー、Vertex AI、ヘッドレスの各シナリオで推奨が異なる。

仕様

方法の選択

ユーザー種別 / シナリオ	推奨する認証方法	Google Cloud プロジェクトの要否
個人の Google アカウント	Sign in with Google	不要。ただし例外あり
会社・学校・Google Workspace アカウントの組織ユーザー	Sign in with Google	必要
Gemini API キーを持つ AI Studio ユーザー	Gemini API Key	不要
Google Cloud Vertex AI ユーザー	Vertex AI	必要
Headless mode	Gemini API Key または Vertex AI	Gemini API Key は不要、Vertex AI は必要

アカウント種別の定義:

個人の Google アカウント: Gemini Code Assist for individuals などの無料枠アカウント、および Google AI Pro / Ultra の有料サブスクリプション
組織アカウント: 会社・学校・Google Workspace など組織を通じた有料ライセンス。Google AI Ultra for Business を含む

Gemini CLI を動かしているターミナルと通信できるマシン上に web ブラウザが必要
Google AI Pro / Ultra の購読者は、その購読に紐づく Google アカウントを使う
gemini を起動して Sign in with Google を選ぶ。資格情報は以後のセッションのためにローカルにキャッシュされる

Google Cloud プロジェクトの設定が必要な条件

ほとんどの個人 Google アカウント（無料・有料とも）は認証に Google Cloud プロジェクトを必要としない。 次のいずれかに当てはまるときに必要。

会社・学校・Google Workspace アカウントを使っている
Google Developer Program の Gemini Code Assist ライセンスを使っている
Gemini Code Assist サブスクリプションのライセンスを使っている

手順:

Google Cloud プロジェクト ID を確認する
Gemini for Cloud API を有効にする
必要な IAM 権限を設定する
GOOGLE_CLOUD_PROJECT または GOOGLE_CLOUD_PROJECT_ID にプロジェクト ID を設定する。Gemini CLI はまず GOOGLE_CLOUD_PROJECT を確認し、無ければ GOOGLE_CLOUD_PROJECT_ID にフォールバックする

Gemini API キー

Google AI Studio で API キーを取得する
GEMINI_API_KEY 環境変数に設定する
gemini を起動して Use Gemini API key を選ぶ

API キーは機微な資格情報として扱う

Vertex AI

いずれの方法でも、Vertex AI API を有効にしたプロジェクト ID を GOOGLE_CLOUD_PROJECT に、リソースまたはジョブを動かす場所を GOOGLE_CLOUD_LOCATION に設定する必要がある。

A. Application Default Credentials（ADC、`gcloud`）

Google Cloud CLI が入っている場合の選択肢
GOOGLE_API_KEY や GEMINI_API_KEY を設定済みの場合、ADC を使うには unset する必要がある
gcloud auth application-default login → プロジェクト設定 → gemini を起動して Vertex AI を選ぶ

B. サービスアカウントの JSON キー

非対話環境、CI/CD パイプライン、組織がユーザーベースの ADC や API キー作成を制限している場合の選択肢
GOOGLE_API_KEY / GEMINI_API_KEY は unset する必要がある
サービスアカウントとキーを作り（"Vertex AI User" ロールを付与）、GOOGLE_APPLICATION_CREDENTIALS に JSON の絶対パスを設定する
サービスアカウントのキーファイルはリソースへのアクセス権を与えるため保護する

C. Google Cloud API キー

Google Cloud の API キーを取得して GOOGLE_API_KEY に設定する
"API keys are not supported by this API..." のようなエラーが出る場合、組織がこのサービスでの API キー利用を制限している可能性がある。他の Vertex AI 認証方法を試す

環境変数の永続化

シェルの設定ファイルに追記する（~/.bashrc、~/.zshrc、~/.profile、PowerShell の $PROFILE）
- 注意: シェル設定ファイルに API キーやサービスアカウントのパスを export すると、そのシェルから起動した任意のプロセスがそれを読める
.env ファイルを使う: プロジェクトディレクトリまたはホームディレクトリに .gemini/.env を作る。Gemini CLI は現在のディレクトリから上へ探し、次にホームの .gemini/.env を見て、最初に見つかったファイルから変数を読み込む
- 変数は最初に見つかったファイルから読み込まれ、マージはされない

Google Cloud 環境での実行

Cloud Shell 環境では、通常 Cloud Shell の資格情報で自動認証される
Compute Engine 環境では、メタデータサーバーの Application Default Credentials（ADC）を自動的に使う
自動認証に失敗した場合は対話的な方法を使う

ヘッドレスモード

既存の認証資格情報がキャッシュされていれば、それを使う
サインイン済みでない場合は、環境変数で認証を設定する必要がある（Gemini API Key または Vertex AI）

設定

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION"
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/keyfile.json"

unset GOOGLE_API_KEY GEMINI_API_KEY
gcloud auth application-default login

mkdir -p ~/.gemini
cat >> ~/.gemini/.env <<'EOF'
GOOGLE_CLOUD_PROJECT="your-project-id"
EOF

制約・注意点

認証方法によってクォータ、価格、利用規約、プライバシー通知が変わる