Configuration Files Management

Master configuration file management for Gemini CLI to customize behavior, manage settings, and organize multiple environments.

Configuration File Locations

Gemini CLI looks for configuration files in these locations (in order of priority):

1. Project-specific config

./gemini.config.json

./.gemini/config.json

Highest priority, overrides all other settings

2. User config

# Linux

~/.config/gemini-cli/config.json

# macOS

~/Library/Application Support/gemini-cli/config.json

# Windows

%APPDATA%\gemini-cli\config.json

User-specific settings

3. Global config

# Linux/macOS

/etc/gemini-cli/config.json

# Windows

C:\ProgramData\gemini-cli\config.json

System-wide defaults

Configuration File Structure

Complete configuration example:

{ "apiKey": "AIza...", "model": "gemini-pro", "temperature": 0.7, "maxTokens": 2048, "timeout": 30000, "output": { "format": "markdown", "highlighting": true, "pager": "auto" }, "mcpServers": { "filesystem": { "command": "npx", "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"] } }, "aliases": { "explain": "Explain this code: ", "review": "Review this code for issues: ", "test": "Generate unit tests for: " }, "safety": { "blockThreshold": "BLOCK_MEDIUM_AND_ABOVE", "categories": ["HARM_CATEGORY_HARASSMENT"] } }

Configuration Options

Core Settings

OptionTypeDefaultDescription
apiKeystring-Google AI API key
modelstring"gemini-pro"Default model to use
temperaturenumber0.7Response randomness (0.0-1.0)
maxTokensnumber2048Maximum response length
timeoutnumber30000Request timeout (milliseconds)

Output Settings

"output": { "format": "markdown", // markdown, plain, json "highlighting": true, // syntax highlighting "pager": "auto", // auto, always, never "streaming": true, // stream responses "quiet": false // suppress non-essential output }

Safety Settings

"safety": { "blockThreshold": "BLOCK_MEDIUM_AND_ABOVE", "categories": [ "HARM_CATEGORY_HARASSMENT", "HARM_CATEGORY_HATE_SPEECH", "HARM_CATEGORY_SEXUALLY_EXPLICIT", "HARM_CATEGORY_DANGEROUS_CONTENT" ] }

Managing Multiple Configurations

Environment-Specific Configs

Development config:

# gemini.dev.json

{ "apiKey": "dev-api-key", "model": "gemini-pro", "temperature": 0.9, "output": { "format": "plain" } }

Production config:

# gemini.prod.json

{ "apiKey": "prod-api-key", "model": "gemini-pro", "temperature": 0.3, "timeout": 60000, "output": { "quiet": true } }

Usage:

gemini --config gemini.dev.json "test prompt"

gemini --config gemini.prod.json "production prompt"

Project-Specific Configs

Create project config:

# In your project directory

mkdir .gemini

cat > .gemini/config.json << 'EOF'

{ "model": "gemini-pro", "aliases": { "docs": "Generate documentation for: ", "fix": "Fix this bug: " }, "mcpServers": { "git": { "command": "npx", "args": ["@modelcontextprotocol/server-git", "."] } } } EOF

Configuration Management Commands

View current configuration:

gemini config show

gemini config show --source # Show where settings come from

Edit configuration:

gemini config edit

gemini config edit --global

Set individual options:

gemini config set model gemini-ultra

gemini config set temperature 0.5

gemini config set output.format markdown

Validate configuration:

gemini config validate

gemini config validate --file gemini.dev.json

Configuration Templates

Minimal Config

{ "apiKey": "your-api-key-here" }

Developer Config

{ "apiKey": "your-api-key", "model": "gemini-pro", "temperature": 0.8, "output": { "format": "markdown", "highlighting": true }, "aliases": { "code": "Help me with this code: ", "debug": "Debug this issue: ", "optimize": "Optimize this code: " } }

Enterprise Config

{ "apiKey": "enterprise-api-key", "model": "gemini-pro", "temperature": 0.3, "timeout": 60000, "safety": { "blockThreshold": "BLOCK_LOW_AND_ABOVE" }, "output": { "quiet": true, "format": "json" }, "logging": { "level": "info", "file": "/var/log/gemini-cli.log" } }

Best Practices

✅ Do

  • • Use project-specific configs for different codebases
  • • Version control your project configs (but not API keys)
  • • Use environment variables for sensitive data
  • • Validate configs after changes
  • • Document custom aliases and settings

❌ Don't

  • • Commit API keys to version control
  • • Use overly complex nested configurations
  • • Ignore configuration validation errors
  • • Set extremely high timeout values
  • • Override safety settings unnecessarily

Next Steps

Ready to customize your Gemini CLI configuration:

Environment VariablesMCP ConfigurationConfig Templates