📌 はじめに
Gemini CLIは、GoogleのAI「Gemini」をターミナルから直接使えるオープンソースツールです。この記事は、公式ドキュメント全体を網羅した究極のリファレンスとして、初心者から上級者まですべての人に役立つよう設計されています。
✨ Gemini CLIでできること
- 🤖 AIとの対話(Gemini 2.0 Flash Experimental)
- 📁 ローカルファイルの読み書き
- 🔧 シェルコマンドの実行
- 🌐 Web検索・ページ取得
- 🔌 カスタムツールの統合(MCP)
- 🛡️ サンドボックスでの安全な実行
🚀 クイックスタート
最速セットアップ(3分で開始)
# 1. インストール(Node.js 18以上が必要)
npm install -g @google/gemini-cli
# 2. 起動
gemini
# 3. 認証(3つから選ぶ)
◻︎ Googleログイン → ブラウザで認証(推奨)
◻︎ APIキー → export GEMINI_API_KEY="取得したキー"
◻︎ Vertex AI → gcloud auth application-default login
最初のコマンド
# 基本的な質問
gemini -p "TypeScriptとJavaScriptの違いを教えて"
# ファイルを読んで分析
gemini -p "@package.json このプロジェクトの依存関係を説明して"
# 対話モード
gemini
> こんにちは!何か手伝えることはある?
🔑 認証方法完全ガイド
方法1: Googleアカウント(推奨・無料)
gemini # 初回起動時にブラウザで認証
- メリット: 無料で60リクエスト/分、1000リクエスト/日
-
注意: Workspaceアカウントは
GOOGLE_CLOUD_PROJECT
設定が必要
方法2: Gemini APIキー
# AI Studioで取得: https://aistudio.google.com/app/apikey
export GEMINI_API_KEY="your-api-key"
# または.envファイルに記載
echo 'GEMINI_API_KEY=your-api-key' > .env
方法3: Vertex AI(企業向け)
# 認証設定
gcloud auth application-default login
# 環境変数設定
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
export GOOGLE_GENAI_USE_VERTEXAI=true
📋 コマンド完全リファレンス
🎯 基本コマンド
コマンド | 説明 | 例 |
---|---|---|
/help または /?
|
ヘルプ表示 | /help |
/clear または Ctrl+L
|
画面クリア | /clear |
/quit または /exit
|
終了 | /quit |
/about |
バージョン情報 | /about |
/stats |
セッション統計(トークン使用量等) | /stats |
/theme |
テーマ変更ダイアログ | /theme |
/auth |
認証方法の変更 | /auth |
💾 セッション管理
# 会話を保存
/chat save my-feature-discussion
# 保存した会話を再開
/chat resume my-feature-discussion
# 保存済み会話一覧
/chat list
# 会話を要約して圧縮(トークン節約)
/compress
🧠 メモリ(コンテキスト)管理
# 現在のメモリ内容を表示
/memory show
# メモリに情報を追加
/memory add このプロジェクトはTypeScriptを使用
# メモリを再読み込み
/memory refresh
🛠️ ツール管理
# 利用可能なツール一覧
/tools
# ツールの詳細説明を表示
/tools desc
# 説明を非表示
/tools nodesc
# MCPサーバー状態確認
/mcp
# MCPツールの詳細表示
/mcp desc
# スキーマ表示
/mcp schema
🔄 チェックポイント(復元機能)
# チェックポイント機能を有効化して起動
gemini --checkpointing
# 利用可能なチェックポイント一覧
/restore
# 特定のチェックポイントに復元
/restore 2025-06-22T10-00-00_000Z-my-file.txt-write_file
🐛 その他のコマンド
# バグ報告(GitHubイシュー作成)
/bug タイトル
# エディタ選択
/editor
📂 ファイル操作マスターガイド
@ コマンド(ファイル読み込み)
# 単一ファイル
@README.md このファイルを要約して
# ディレクトリ全体
@src/ このコードベースの構造を説明して
# グロブパターン
@src/**/*.ts すべてのTypeScriptファイルをレビューして
# 複数指定
@package.json @tsconfig.json これらの設定は整合性が取れてる?
# スペースを含むパス
@My\ Documents/file.txt
自動除外されるもの(respectGitIgnore: true
の場合):
.git/
node_modules/
dist/
.env
- その他
.gitignore
の内容
📝 ファイルシステムツール詳細
1. list_directory - ディレクトリ一覧
// 基本使用
list_directory(path="/home/user/project")
// 除外パターン付き
list_directory(
path="/home/user/project",
ignore=["*.log", "temp/*"],
respect_git_ignore=true
)
2. read_file - ファイル読み込み
// テキストファイル全体
read_file(path="/home/user/file.txt")
// 行範囲指定(100行目から50行)
read_file(
path="/home/user/large.log",
offset=100,
limit=50
)
// 画像・PDFも対応(base64で返却)
read_file(path="/home/user/diagram.png")
3. write_file - ファイル書き込み
write_file(
file_path="/home/user/new_file.py",
content="#!/usr/bin/env python3\n\nprint('Hello, World!')"
)
// → 差分確認画面が表示される
4. glob (FindFiles) - パターン検索
// プロジェクト内のすべてのテストファイル
glob(pattern="**/*.test.{js,ts}")
// 特定ディレクトリ内のMarkdown
glob(
pattern="*.md",
path="/home/user/docs",
case_sensitive=false
)
5. search_file_content (SearchText) - 内容検索
// 正規表現でコード検索
search_file_content(
pattern="function\\s+calculate.*\\(",
path="/home/user/project",
include="*.js"
)
6. replace (Edit) - ファイル編集
// 精密な置換(前後3行以上のコンテキスト推奨)
replace(
file_path="/home/user/config.json",
old_string='{\n "version": "1.0.0",\n "name": "old-name"',
new_string='{\n "version": "2.0.0",\n "name": "new-name"',
expected_replacements=1
)
7. read_many_files - 複数ファイル読み込み
// 複数パターンと除外
read_many_files(
paths=["src/**/*.ts", "tests/**/*.test.ts"],
include=["*.d.ts"],
exclude=["**/*.spec.ts", "node_modules/**"],
respect_git_ignore=true
)
🔧 シェルコマンド実行
! コマンド(シェルモード)
# 単発実行
!npm test
# シェルモード切り替え
!
Shell> ls -la
Shell> git status
Shell> exit # または再度 !
# バックグラウンド実行
!npm run dev &
# ディレクトリ指定
run_shell_command(
command="npm install",
directory="frontend",
description="フロントエンドの依存関係インストール"
)
🌐 Web機能
web_search - Google検索
google_web_search(query="Gemini CLI 使い方 2025")
// → 検索結果の要約と引用付きで返却
web_fetch - ページ取得
// 単一URL
web_fetch(prompt="https://example.com/article を要約して")
// 複数URL比較(最大20)
web_fetch(
prompt="次の2つの記事の主張の違いを説明して: " +
"https://site1.com/article1 と " +
"https://site2.com/article2"
)
🧩 メモリツール(save_memory)
// ユーザー設定を記憶
save_memory(fact="私の好きなプログラミング言語はRustです")
// プロジェクト情報を記憶
save_memory(fact="このプロジェクトではpnpmを使用しています")
// 保存先: ~/.gemini/GEMINI.md の ## Gemini Added Memories セクション
⚙️ 設定ファイル完全ガイド
設定ファイルの場所と優先順位
- デフォルト値(最低優先度)
- ~/.gemini/settings.json(ユーザー設定)
- .gemini/settings.json(プロジェクト設定)
- 環境変数
- コマンドライン引数(最高優先度)
settings.json 完全リファレンス
{
// 基本設定
"theme": "GitHub", // テーマ: Default, Dracula, GitHub等
"contextFileName": "GEMINI.md", // または ["GEMINI.md", "AI_CONTEXT.md"]
"preferredEditor": "vscode", // diff表示用エディタ
// 認証とモデル
"model": "gemini-2.0-flash-exp", // 使用モデル
// ツール設定
"coreTools": ["read_file", "write_file", "run_shell_command"], // 使用可能ツール
"excludeTools": ["dangerous_tool"], // 除外するツール
"autoAccept": false, // 安全な操作の自動承認(非推奨)
// ファイルフィルタリング
"fileFiltering": {
"respectGitIgnore": true, // .gitignore考慮
"enableRecursiveFileSearch": true // 再帰検索
},
// サンドボックス
"sandbox": "docker", // false, true, "docker", "podman"
// カスタムツール
"toolDiscoveryCommand": "bin/discover-tools",
"toolCallCommand": "bin/call-tool",
// MCPサーバー
"mcpServers": {
"github": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "ghcr.io/github/github-mcp-server"],
"env": {
"GITHUB_TOKEN": "$GITHUB_PERSONAL_ACCESS_TOKEN"
},
"timeout": 10000,
"trust": false
},
"customServer": {
"command": "python",
"args": ["-m", "my_mcp_server"],
"cwd": "./mcp-servers",
"trust": true // 確認なしで実行(注意!)
}
},
// チェックポイント
"checkpointing": {
"enabled": true
},
// バグ報告カスタマイズ
"bugCommand": {
"urlTemplate": "https://github.com/myorg/myrepo/issues/new?title={title}&body={info}"
},
// テレメトリ
"telemetry": {
"enabled": false,
"target": "local", // "local" or "gcp"
"otlpEndpoint": "http://localhost:4317",
"logPrompts": true
},
// 使用統計
"usageStatisticsEnabled": true
}
環境変数での設定値参照
{
"mcpServers": {
"myServer": {
"env": {
"API_KEY": "$MY_SECRET_KEY", // または
"TOKEN": "${GITHUB_TOKEN}" // どちらの形式もOK
}
}
}
}
🔌 MCP(Model Context Protocol)サーバー
MCPサーバーのセットアップ
- 設定ファイルに追加
{
"mcpServers": {
"myTools": {
"command": "node",
"args": ["mcp-server.js"],
"cwd": "./tools"
}
}
}
- 接続確認
/mcp # サーバー状態とツール一覧表示
MCPサーバーの実装例
// mcp-server.js
import { Server } from '@modelcontextprotocol/sdk';
const server = new Server({
name: 'my-tools',
version: '1.0.0'
});
// ツール定義
server.setRequestHandler('tools/list', async () => ({
tools: [{
name: 'get_weather',
description: '天気情報を取得',
inputSchema: {
type: 'object',
properties: {
location: { type: 'string', description: '地域名' }
},
required: ['location']
}
}]
}));
// ツール実行
server.setRequestHandler('tools/call', async (request) => {
if (request.params.name === 'get_weather') {
const { location } = request.params.arguments;
// 実装...
return { content: [{ type: 'text', text: `${location}の天気は晴れです` }] };
}
});
server.connect();
トランスポート種別
-
Stdio(標準):
command
で指定 -
SSE:
url: "http://localhost:8080/sse"
-
HTTP Streaming:
httpUrl: "http://localhost:3000/mcp"
🛡️ サンドボックス完全ガイド
有効化方法(優先順位順)
-
コマンドフラグ:
gemini -s
またはgemini --sandbox
-
環境変数:
export GEMINI_SANDBOX=docker
-
設定ファイル:
"sandbox": true
macOS Seatbeltプロファイル
# プロファイル選択
export SEATBELT_PROFILE=permissive-open # デフォルト
# 利用可能なプロファイル
- permissive-open # 書き込み制限、ネットワーク許可
- permissive-closed # 書き込み制限、ネットワーク禁止
- restrictive-open # 厳格な制限、ネットワーク許可
- restrictive-closed # 最大制限
カスタムDockerサンドボックス
.gemini/sandbox.Dockerfile
:
FROM gemini-cli-sandbox
# カスタム依存関係
RUN apt-get update && apt-get install -y \
postgresql-client \
redis-tools
# プロジェクト固有の設定
COPY requirements.txt /tmp/
RUN pip install -r /tmp/requirements.txt
ビルドと実行:
BUILD_SANDBOX=1 gemini -s
Linux UID/GID設定
# ホストのUID/GIDを強制
export SANDBOX_SET_UID_GID=true
# UID/GIDマッピング無効化
export SANDBOX_SET_UID_GID=false
📊 テレメトリとモニタリング
ローカルテレメトリ(Jaeger)
# 自動セットアップと起動
npm run telemetry -- --target=local
# ブラウザで確認
open http://localhost:16686
Google Cloudテレメトリ
# 設定
export OTLP_GOOGLE_CLOUD_PROJECT="your-project-id"
# 起動
npm run telemetry -- --target=gcp
収集されるデータ
- ツール呼び出し: 名前、実行時間、成功/失敗
- APIリクエスト: モデル、トークン使用量、レイテンシ
- セッション情報: 設定、有効なツール
収集されないデータ:
- 個人情報(名前、メール等)
- プロンプトの内容(
logPrompts: false
の場合) - ファイルの内容
オプトアウト
{
"usageStatisticsEnabled": false
}
🔧 コマンドライン引数
# モデル指定
gemini -m gemini-2.0-flash-thinking-exp-1219
# 非対話モード
gemini -p "質問内容"
# 全ファイルをコンテキストに含める
gemini -a
# デバッグモード
gemini -d
# YOLOモード(すべて自動承認 - 危険!)
gemini --yolo
# チェックポイント有効
gemini --checkpointing
# ヘルプ
gemini -h
📝 GEMINI.md(階層的コンテキスト)
読み込み順序
- ~/.gemini/GEMINI.md(グローバル)
- プロジェクトルートから上位ディレクトリ
- 現在のディレクトリ以下のサブディレクトリ
効果的なGEMINI.md例
# プロジェクト: Next.js Eコマースサイト
## 技術スタック
- Next.js 14 (App Router)
- TypeScript 5.3
- Tailwind CSS
- Prisma ORM
- PostgreSQL
## コーディング規約
- コンポーネント: PascalCase
- 関数: camelCase
- 定数: UPPER_SNAKE_CASE
- インデント: 2スペース
- セミコロン: なし
## プロジェクト構造
- app/: App Routerページ
- components/: 再利用可能コンポーネント
- lib/: ユーティリティ関数
- prisma/: データベーススキーマ
## 重要な注意事項
- 環境変数は.env.localに記載
- APIルートはapp/api/配下
- 認証にはNextAuthを使用
## Git慣習
- feat: 新機能
- fix: バグ修正
- docs: ドキュメント
- style: フォーマット
- refactor: リファクタリング
🚨 トラブルシューティング
よくあるエラーと解決法
1. 認証エラー
# エラー: Failed to login. Message: Request contains an invalid argument
# 解決法1: APIキーを使用
export GEMINI_API_KEY="your-api-key"
# 解決法2: Google Cloudプロジェクト設定
export GOOGLE_CLOUD_PROJECT="your-project-id"
2. MODULE_NOT_FOUND
# 解決法
npm install
npm run build
3. Operation not permitted(サンドボックス)
# 一時的に無効化
gemini # -sなしで起動
# または設定で無効化
echo '{"sandbox": false}' > .gemini/settings.json
4. MCPサーバー接続エラー
# デバッグ手順
1. コマンドを直接実行して確認
2. /mcp で状態確認
3. --debug_mode で詳細ログ確認
4. タイムアウト値を増やす
デバッグテクニック
# 環境変数確認
echo $GEMINI_API_KEY
# 現在の設定確認
cat ~/.gemini/settings.json
cat .gemini/settings.json
# メモリ内容確認
/memory show
# ツール一覧確認
/tools desc
# 統計情報でトークン使用量確認
/stats
💡 ベストプラクティス
1. プロジェクトごとの設定
# プロジェクトルートに設定ファイル作成
mkdir -p .gemini
cat > .gemini/settings.json << EOF
{
"contextFileName": "AI_CONTEXT.md",
"sandbox": "docker",
"checkpointing": {"enabled": true}
}
EOF
# プロジェクト固有のコンテキスト
cat > .gemini/AI_CONTEXT.md << EOF
# このプロジェクトについて
技術的な詳細と規約...
EOF
2. 安全な実行
# 常にサンドボックスで実行
alias gemini-safe='gemini --sandbox'
# 重要な操作前にチェックポイント
gemini --checkpointing
3. 効率的なファイル操作
# .gitignoreを活用
echo "*.log" >> .gitignore
echo "temp/" >> .gitignore
# 大きなファイルは範囲指定
"@large.log:1000-1100 この範囲のエラーを分析"
4. MCPサーバーの管理
# 開発用と本番用を分離
# .gemini/settings.json (開発)
# ~/.gemini/settings.json (共通)
# trustは最小限に
"trust": false # デフォルト
5. トークン管理
# 定期的に統計確認
/stats
# 長い会話は圧縮
/compress
# 不要な詳細は省く
"@src/重要なファイルだけ.ts" # 全体ではなく
🎯 実践的な使用例
コードレビュー自動化
#!/bin/bash
# code-review.sh
BRANCH=$(git branch --show-current)
FILES=$(git diff main...$BRANCH --name-only)
gemini -p "@$FILES mainブランチとの差分をレビューして、以下の観点でフィードバックをください:
1. バグの可能性
2. パフォーマンスの問題
3. セキュリティリスク
4. コーディング規約違反"
ドキュメント生成
# API ドキュメント生成
gemini -p "@src/**/*.ts すべての公開APIのドキュメントをOpenAPI形式で生成して"
# README更新
gemini -p "@package.json @src/ このプロジェクトのREADME.mdを生成して。インストール方法、使用例、APIリファレンスを含めて"
テスト生成
# ユニットテスト
gemini -p "@src/utils.ts この関数のJestテストを書いて。エッジケースも含めて"
# E2Eテスト
gemini -p "@app/ このアプリケーションのCypressE2Eテストを書いて"
リファクタリング
# 段階的リファクタリング
gemini --checkpointing -p "@src/legacy.js このコードをTypeScriptに変換して、モダンな書き方にリファクタリング"
🎊 まとめ
Gemini CLIは単なるAIチャットツールではなく、開発ワークフローを根本から変える強力なツールです。この記事を参照しながら、まずは基本的な使い方から始めて、徐々に高度な機能を活用していってください。
次のステップ
-
今すぐ始める:
npm install -g @google/gemini-cli
-
プロジェクトに導入:
.gemini/
ディレクトリを作成 - チームで活用: settings.jsonを共有
- 貢献する: GitHubでイシューやPR
Happy Coding with Gemini CLI! 🚀✨