Intermediate

Gemini CLI Configuration

Customize Gemini CLI to match your workflow. Learn about settings files, model selection, custom instructions, extensions, environment variables, and MCP server support.

Settings Files

Gemini CLI uses a layered configuration system with settings files at different levels:

Level Location Scope
Global ~/.gemini/settings.json All projects on your machine
Project .gemini/settings.json Current project only
settings.json
{
  "model": "gemini-2.5-pro",
  "temperature": 0.7,
  "maxOutputTokens": 8192,
  "sandbox": false,
  "theme": "dark",
  "autoApprove": false,
  "excludePatterns": [
    "node_modules/**",
    "dist/**",
    ".git/**",
    "*.lock"
  ]
}

Model Selection

Choose the right Gemini model for your task:

Terminal
# Use Pro for complex tasks (default)
$ gemini --model gemini-2.5-pro

# Use Flash for fast, simple tasks
$ gemini --model gemini-2.5-flash

# Set default model in settings
$ gemini config set model gemini-2.5-flash

# Check current model
$ gemini config get model
Model Best For Speed Cost
gemini-2.5-pro Complex tasks, multi-file edits, architecture Moderate Higher
gemini-2.5-flash Quick questions, simple edits, exploration Fast Lower
Cost tip: Use Flash as your default model for everyday tasks. Switch to Pro only when you need deeper reasoning, multi-file refactoring, or complex architectural analysis. This can reduce your token usage significantly.

Custom Instructions

Provide project-specific context and rules that Gemini CLI follows in every interaction:

GEMINI.md (project root)
# Project: E-Commerce API

## Tech Stack
- Node.js 20 with TypeScript
- Express.js for REST API
- PostgreSQL with Prisma ORM
- Jest for testing
- Docker for deployment

## Coding Standards
- Use functional programming patterns
- All functions must have TypeScript types
- Use Prisma for all database operations
- Follow REST naming conventions
- Write tests for all new functions

## Architecture
- Routes in src/routes/
- Business logic in src/services/
- Database queries in src/repositories/
- Shared types in src/types/
- Utilities in src/utils/

## Important Notes
- Never modify migration files directly
- Always use environment variables for secrets
- Rate limiting is required on all public endpoints

Extensions

Extend Gemini CLI's capabilities with custom extensions and integrations:

settings.json - Extensions
{
  "extensions": {
    "web-search": {
      "enabled": true
    },
    "image-generation": {
      "enabled": true,
      "model": "imagen-3"
    }
  }
}

Environment Variables

Configure Gemini CLI behavior through environment variables:

Shell Configuration
# Authentication
export GEMINI_API_KEY="your-api-key"

# Model selection
export GEMINI_MODEL="gemini-2.5-pro"

# Proxy settings (for corporate networks)
export HTTP_PROXY="http://proxy:8080"
export HTTPS_PROXY="http://proxy:8080"

# Logging
export GEMINI_LOG_LEVEL="debug"

# Custom config directory
export GEMINI_CONFIG_DIR="~/.config/gemini"

MCP Server Support

Gemini CLI supports the Model Context Protocol (MCP), allowing you to connect it to external tools and data sources:

settings.json - MCP Servers
{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    },
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/dir"
      ]
    }
  }
}
💡
What is MCP? The Model Context Protocol is an open standard for connecting AI models to external data sources and tools. It lets Gemini CLI interact with databases, APIs, file systems, and more through a standardized interface.

Popular MCP Servers

  • PostgreSQL/MySQL: Query and manage databases directly from Gemini CLI
  • GitHub: Read issues, PRs, and repository data
  • Filesystem: Access files outside the project directory
  • Slack: Read and send messages in channels
  • Google Drive: Access and search documents
  • Custom servers: Build your own MCP server for any data source

💡 Try It: Create a GEMINI.md

Create a GEMINI.md file in one of your projects with details about the tech stack, coding standards, and architecture. Then start Gemini CLI and ask it to explain the project. Notice how it uses the custom instructions to provide more contextual answers.

Good custom instructions dramatically improve the quality and consistency of Gemini CLI's output for your specific project.

Ready to Go Deeper?

Live instructor-led courses from our partners. Affiliate disclosure.