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-cliconfigurationgemini-yamlmcpsandbox

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

KeyDescriptionDefault
model.nameModel IDgemini-2.5-pro
model.thinkingBudgetThinking token budget4000
model.temperature0.0–2.0 (lower = more deterministic)Depends on model
model.maxOutputTokensMax output per request16384

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

VariablePurpose
GOOGLE_API_KEYAPI key auth (alternative to OAuth2)
GOOGLE_APPLICATION_CREDENTIALSService account JSON path
GEMINI_MODELOverride default model
GEMINI_SANDBOX_MODEOverride sandbox mode
GEMINI_LOG_LEVELdebug/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