Configuration Guide

Configuration & Settings

Customize Gemini CLI to fit your workflow. Learn about configuration files, environment variables, and all available settings.

Configuration Methods

Config Files

JSON/YAML configuration files

• ~/.config/gemini/config.json
• Project-specific configs
• JSON or YAML format
• Version controlled

Environment Variables

Shell environment configuration

• GEMINI_API_KEY
• GEMINI_MODEL
• System-wide settings
• CI/CD friendly

CLI Commands

Interactive configuration

• gemini config set
• gemini config get
• Runtime overrides
• Command-line flags

Configuration File Setup

Configuration File Locations

Configuration Priority

Gemini CLI looks for configuration in this order:

Command-line flags (highest priority)
Environment variables
Project config file (./gemini.config.json)
User config file (~/.config/gemini/config.json)
Global config file (/etc/gemini/config.json)
Default values (lowest priority)

User Configuration

Personal settings that apply to all projects for the current user.

# Create user config directory
mkdir -p ~/.config/gemini

# Create config file
cat > ~/.config/gemini/config.json << 'EOF'
{
  "auth": {
    "apiKey": "your-api-key-here",
    "method": "api-key"
  },
  "models": {
    "default": "gemini-pro",
    "temperature": 0.7,
    "maxTokens": 2048
  },
  "output": {
    "format": "markdown",
    "color": true,
    "streaming": true
  }
}
EOF

Configuration Reference

Authentication

API keys, OAuth, and credentials

Setting	Type	Description	Default
`auth.apiKey`	string	Google AI Studio API key	-
`auth.method`	enum	api-key, oauth, service-account	api-key
`auth.tokenRefresh`	boolean	Auto-refresh OAuth tokens	true
`auth.credentialsFile`	string	Path to service account JSON	-

Models & AI

Model selection and AI parameters

Setting	Type	Description	Default
`models.default`	string	Default model to use	gemini-pro
`models.temperature`	number	Creativity level (0.0-1.0)	0.7
`models.maxTokens`	number	Maximum response length	2048
`models.topP`	number	Nucleus sampling parameter	0.9

Output & Display

Formatting and display options

Setting	Type	Description	Default
`output.format`	enum	text, markdown, json, yaml	markdown
`output.color`	boolean	Enable colored output	true
`output.streaming`	boolean	Stream responses as they generate	true
`output.verbose`	boolean	Show detailed information	false

Performance

Caching, timeouts, and optimization

Setting	Type	Description	Default
`cache.enabled`	boolean	Enable response caching	true
`cache.ttl`	number	Cache TTL in seconds	3600
`network.timeout`	number	Request timeout in ms	30000
`network.retries`	number	Number of retry attempts	3

Environment Variables

Environment variables provide a convenient way to configure Gemini CLI, especially in automated environments like CI/CD pipelines.

Available Environment Variables

Complete list of supported environment variables

Variable	Config Equivalent	Description
`GEMINI_API_KEY`	`auth.apiKey`	Google AI Studio API key
`GEMINI_MODEL`	`models.default`	Default model to use
`GEMINI_TEMPERATURE`	`models.temperature`	Default temperature setting
`GEMINI_MAX_TOKENS`	`models.maxTokens`	Maximum tokens per response
`GEMINI_TIMEOUT`	`network.timeout`	Request timeout in milliseconds
`GEMINI_CONFIG_FILE`	-	Path to custom config file
`GEMINI_CACHE_DIR`	`cache.directory`	Cache directory path
`GEMINI_LOG_LEVEL`	`logging.level`	Logging level (debug, info, warn, error)

Setting Environment Variables

# Temporary (current session)
export GEMINI_API_KEY="your-api-key"
export GEMINI_MODEL="gemini-pro"
export GEMINI_TEMPERATURE="0.8"

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export GEMINI_API_KEY="your-api-key"' >> ~/.bashrc
echo 'export GEMINI_MODEL="gemini-pro"' >> ~/.bashrc
source ~/.bashrc

Advanced Configuration

Configuration Profiles

Use different configurations for different environments

# Create development profile
gemini config profile create development
gemini config set models.temperature 0.9 --profile development

# Create production profile  
gemini config profile create production
gemini config set models.temperature 0.3 --profile production

# Switch profiles
gemini config profile use development

# List profiles
gemini config profile list

Configuration Validation

Validate your configuration for errors

# Validate current configuration
gemini config validate

# Validate specific config file
gemini config validate --file ./custom-config.json

# Check configuration completeness
gemini config check

# Show effective configuration
gemini config show --resolved

Configuration Schema

JSON schema for configuration validation

# Generate configuration schema
gemini config schema > gemini-config.schema.json

# Validate against schema
npm install -g ajv-cli
ajv validate -s gemini-config.schema.json -d your-config.json

Configuration Migration

Version Compatibility

Configuration format may change between major versions. Use migration tools to update your configuration files.

Migration Commands

# Check if migration is needed
gemini config migrate --check

# Migrate configuration to latest format
gemini config migrate --backup

# Migrate specific file
gemini config migrate --file old-config.json --output new-config.json

# Show migration preview
gemini config migrate --dry-run

Configuration Best Practices

Best Practices

Use project-specific configs for teams
Store sensitive data in environment variables
Version control your config files
Use profiles for different environments
Document custom configurations
Validate configs before deployment

Avoid These Mistakes

Don't commit API keys to version control
Don't use overly high temperature values
Don't set timeout values too low
Don't ignore configuration validation errors
Don't use production configs in development
Don't modify global configs without testing

Configuration Complete!

You now know how to configure Gemini CLI for optimal performance and workflow integration.

Start Building

Apply your configuration in practice

Explore Commands

Learn about all available commands

Commands Getting Started