Where Gemini CLI Stores Configuration Files

Understanding where Gemini CLI stores its configuration files helps you customize your setup, backup your settings, and troubleshoot issues. This guide covers all configuration locations across macOS, Windows, and Linux.

Complete Directory Structure

Gemini CLI organizes configuration files in a predictable hierarchy:

~/.gemini/                          # Main configuration directory
  settings.json                     # User settings
  GEMINI.md                         # Global custom instructions
  .env                              # API key (optional)
  extensions/                       # Custom extensions
  tmp/                              # Temporary and session data
    <project_hash>/                 # Per-project data
      chats/                        # Session history
      shell_history                 # Command history

<project_root>/                     # Your project directory
  GEMINI.md                         # Project-specific instructions
  .gemini/
    settings.json                   # Project-specific settings

System locations (platform-specific):
  macOS: /Library/Application Support/GeminiCli/system-defaults.json
  Linux: /etc/gemini-cli/settings.json
  Windows: C:\ProgramData\gemini-cli\settings.json

Main Configuration Directory

The primary configuration directory is ~/.gemini/ in your home folder.

Location by platform:

This directory is created automatically the first time you run Gemini CLI.

Configuration Files Explained

User Settings (settings.json)

Location: ~/.gemini/settings.json

This file contains your personal Gemini CLI preferences:

{
  "theme": "dark",
  "model": "gemini-2.0-flash-exp",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/files"]
    }
  },
  "sandbox": true,
  "autoApprove": []
}

Common settings:

• theme: UI color scheme (dark, light, auto)
• model: Default Gemini model to use
• mcpServers: MCP server configurations
• sandbox: Whether to run commands in a sandboxed environment
• autoApprove: Commands that run without confirmation

GEMINI.md (Custom Instructions)

Global location: ~/.gemini/GEMINI.md

Project location: <project_root>/GEMINI.md

This file contains custom instructions that Gemini CLI includes in every conversation. Use it to define coding standards, preferred patterns, or project context.

Example GEMINI.md:

# Project Guidelines

- Use TypeScript for all new code
- Follow the existing code style
- Write tests for new features
- Use meaningful variable names

The project-level GEMINI.md takes precedence over the global one when working in that project directory.

Project Settings

Location: <project_root>/.gemini/settings.json

Project-specific settings override user settings when working in that directory. This is useful for:

• Different MCP configurations per project
• Project-specific model preferences
• Custom sandbox rules

System Defaults

System administrators can set organization-wide defaults:

These settings apply to all users on the system but can be overridden by user or project settings.

Credential Storage

OAuth Credentials (Login with Google)

When you authenticate with "Login with Google," credentials are stored securely in your system keychain:

To view or manage these credentials:

macOS:

1. Open Keychain Access
2. Search for "gemini" or "google"
3. View or delete the credential

Linux:

secret-tool search service gemini-cli

Windows:

1. Open Credential Manager
2. Look under Windows Credentials
3. Find entries related to Gemini CLI

API Key Storage

If you prefer using an API key instead of OAuth:

Environment variable (recommended):

export GEMINI_API_KEY="your-api-key-here"

File-based (optional): Create ~/.gemini/.env:

GEMINI_API_KEY=your-api-key-here

Session and History Storage

Session History

Location: ~/.gemini/tmp/<project_hash>/chats/

Gemini CLI stores conversation history for each project. The project hash is generated from the absolute path of your project directory.

To find your current project's session directory:

# The hash is based on your project path
ls ~/.gemini/tmp/

Shell History

Location: ~/.gemini/tmp/<project_hash>/shell_history

Commands executed through Gemini CLI are stored separately from your system shell history.

Extensions Directory

Location: ~/.gemini/extensions/

Custom extensions and plugins are stored here. Extensions can add new capabilities to Gemini CLI.

Environment Variables

Environment variables provide another way to configure Gemini CLI and take precedence over file-based settings:

To set environment variables permanently:

macOS/Linux (add to ~/.zshrc or ~/.bashrc):

export GEMINI_API_KEY="your-api-key-here"

Windows (PowerShell profile):

$env:GEMINI_API_KEY="your-api-key-here"

Configuration Precedence

Settings are applied in this order (later entries override earlier ones):

1. Built-in defaults (lowest priority)
2. System defaults (/Library/Application Support/GeminiCli/system-defaults.json)
3. User settings (~/.gemini/settings.json)
4. Project settings (<project>/.gemini/settings.json)
5. System settings (rare, for IT-managed configurations)
6. Environment variables
7. CLI arguments (highest priority)

Example: If you set model in your user settings but pass --model on the command line, the CLI argument wins.

Backup and Migration

Backing Up Your Configuration

To backup your Gemini CLI configuration:

# Create a backup archive
tar -czvf gemini-backup.tar.gz ~/.gemini/

# Or copy specific files
cp ~/.gemini/settings.json ~/backup/
cp ~/.gemini/GEMINI.md ~/backup/

Important: OAuth credentials in the system keychain are not included in file backups. You will need to re-authenticate on restored systems.

Migrating to a New Machine

1. Copy configuration files:

# On old machine
tar -czvf gemini-config.tar.gz ~/.gemini/settings.json ~/.gemini/GEMINI.md

# Transfer to new machine, then:
tar -xzvf gemini-config.tar.gz -C ~/

2. Re-authenticate: Run gemini and complete the login flow

3. Reinstall extensions: If you had custom extensions, reinstall them

4. Verify MCP servers: Ensure any MCP server paths are updated for the new machine

Syncing with Dotfile Managers

If you use a dotfile manager like chezmoi, stow, or yadm:

# Add Gemini config to your dotfiles
chezmoi add ~/.gemini/settings.json
chezmoi add ~/.gemini/GEMINI.md

Troubleshooting

Settings Not Being Applied

1. Check file permissions:

ls -la ~/.gemini/settings.json

2. Validate JSON syntax:

cat ~/.gemini/settings.json | python -m json.tool

3. Check for conflicting environment variables:

env | grep -i gemini

Clearing All Configuration

To completely reset Gemini CLI:

# Backup first (optional)
mv ~/.gemini ~/.gemini.backup

# Remove the directory
rm -rf ~/.gemini

# Clear keychain credentials (macOS)
security delete-generic-password -s "gemini-cli" 2>/dev/null

# Restart Gemini CLI to recreate defaults
gemini

Finding the Configuration Used

To see which configuration files Gemini CLI is using:

gemini --verbose

This shows the loaded configuration sources and their values.

Next Steps

• Learn how to install Gemini CLI if you have not already
• Configure MCP integrations for extended capabilities
• Explore batch code analysis with Gemini's 1M token context