Gemini CLI — Configuration Reference
Complete Gemini CLI configuration reference. Covers gemini.yaml settings, MCP integration, .gemini/ directory conventions, sandbox configuration, extension management, and environment variables.
Gemini CLI — Configuration Reference
Gemini CLI uses gemini.yaml for settings, .gemini/ for project files, and environment variables for auth. Here's the complete reference.
gemini.yaml
Located at ~/.gemini/gemini.yaml (global) or .gemini/gemini.yaml (project). Project takes precedence:
# gemini.yaml
version: "1"
model:
name: gemini-2.5-pro
thinkingBudget: 4000
temperature: 0.2
maxOutputTokens: 16384
sandbox:
mode: workspace
allowedDirectories:
- ./src
- ./lib
- ./public
- ./tests
allowedCommands:
- npm
- npx
- git
- node
extensions:
- google-drive
- google-calendar
- gmail
- google-sheets
ide:
theme: auto
logging:
level: info
file: ~/.gemini/logs/session.log
Model Settings
| Key | Description | Default |
|---|---|---|
model.name | Model ID | gemini-2.5-pro |
model.thinkingBudget | Thinking token budget | 4000 |
model.temperature | 0.0–2.0 (lower = more deterministic) | Depends on model |
model.maxOutputTokens | Max output per request | 16384 |
Sandbox Configuration
sandbox:
mode: workspace # workspace | read-only | isolated | full
allowedDirectories: # Only relevant for workspace mode
- ./src
- ./lib
- ./tests
blockedDirectories:
- ./node_modules
- ./.env
- ./secrets
allowedCommands: # Commands the sandbox allows
- npm
- npx
- git
- node
- python3
blockedCommands: # Explicitly blocked
- sudo
- rm
- chmod
- chown
Extensions
Enable Google service integrations:
extensions:
- google-drive # Read/write Drive files
- google-calendar # Check/create calendar events
- gmail # Read/send emails
- google-sheets # Read/write spreadsheets
- google-docs # Read/write documents
Check enabled extensions:
gemini extensions list
gemini extensions enable google-drive
gemini extensions disable gmail
.gemini/ Directory
.gemini/
├── gemini.yaml # Project configuration
├── GEMINI.md # Project system instructions
├── extensions/ # Extension configs
│ ├── google-drive.yaml
│ └── gmail.yaml
├── rules/ # Additional rules files
│ ├── security.md
│ └── conventions.md
└── hooks/ # Pre/post action hooks
├── pre-execute.sh
└── post-execute.sh
MCP Server Configuration
Add MCP servers in gemini.yaml:
mcp:
servers:
filesystem:
command: npx
args:
- "-y"
- "@modelcontextprotocol/server-filesystem"
- "./"
github:
command: npx
args:
- "-y"
- "@modelcontextprotocol/server-github"
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
postgres:
command: npx
args:
- "-y"
- "@modelcontextprotocol/server-postgres"
- "postgresql://localhost:5432/mydb"
Environment Variables
| Variable | Purpose |
|---|---|
GOOGLE_API_KEY | API key auth (alternative to OAuth2) |
GOOGLE_APPLICATION_CREDENTIALS | Service account JSON path |
GEMINI_MODEL | Override default model |
GEMINI_SANDBOX_MODE | Override sandbox mode |
GEMINI_LOG_LEVEL | debug/info/warn/error |
Hook Scripts
Run validation automatically:
# .gemini/hooks/pre-execute.sh
#!/bin/bash
if echo "$GEMINI_COMMAND" | grep -q "npm install"; then
echo "⚠️ Package installation detected."
echo " Review the package.json changes before proceeding."
exit 1 # Block the command
fi
exit 0
Related Pages
- Gemini CLI Getting Started — Installation and setup
- Prompt Engineering in Gemini CLI — Ralph loop and prompts
- MCP Section — Browse MCP servers
Related Articles
Cline — AI Coding Tool Guide
VS Code extension for autonomous AI coding. Browser automation, MCP server creation, terminal control, and prompt patterns for complex multi-step development workflows.
Continue.dev — AI Coding Tool Guide
Open-source AI code assistant. Local model support, custom slash commands, configuration, and integration with Ollama, LM Studio, and cloud APIs.
Tabnine — AI Coding Tool Guide
Enterprise-focused AI code assistant with code privacy, on-premise deployment, and team learning. Configuration and prompt patterns for Tabnine Chat.