Gemini CLI — Configuration Reference (Enterprise)

Gemini CLI uses settings.json for configuration, .gemini/ for project files, and environment variables for auth and runtime overrides. Here's the complete reference.

settings.json

Located at ~/.gemini/settings.json (user) or .gemini/settings.json (workspace). Workspace values override user values. System administrators can also point to a system settings file with GEMINI_CLI_SYSTEM_SETTINGS_PATH.

{
  "general": {
    "vimMode": false,
    "defaultApprovalMode": "default",
    "checkpointing": {
      "enabled": true
    }
  },
  "ui": {
    "theme": "GitHub",
    "showLineNumbers": true
  },
  "model": {
    "name": "gemini-3.1-pro-preview",
    "maxSessionTurns": -1,
    "compressionThreshold": 0.6
  },
  "tools": {
    "sandbox": "sandbox-exec",
    "shell": {
      "enableInteractiveShell": true,
      "showColor": false
    },
    "useRipgrep": true
  },
  "context": {
    "fileName": ["GEMINI.md"],
    "includeDirectories": []
  },
  "security": {
    "toolSandboxing": false
  }
}

Model Settings

The example above uses configured values; the table lists the schema defaults.

Sandbox Configuration

{
  "tools": {
    "sandbox": "docker"
  }
}

tools.sandbox is unset by default, which leaves sandboxing disabled. Set it to true to enable sandboxing, or to a provider name such as "sandbox-exec", "docker", "podman", "runsc", "lxc", or "windows-native" to select a provider explicitly. You can also enable sandboxing per run with -s / --sandbox or GEMINI_SANDBOX; the command-line flag takes precedence over the environment variable, which takes precedence over the settings file.

.gemini/ Directory

.gemini/
├── settings.json          # Workspace configuration
└── GEMINI.md              # Optional project instructions

GEMINI.md can also live at the project root. Gemini CLI loads it as project memory; context.fileName changes the filename and context.includeDirectories adds directories to scan.

MCP Server Configuration

Add MCP servers under the top-level mcpServers key in settings.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/absolute/path/to/project"
      ]
    }
  }
}

The Filesystem server requires at least one allowed directory argument. The official GitHub and Postgres reference servers are archived, and their npm packages are deprecated; browse the MCP Registry for maintained alternatives.

Use /mcp in a session to inspect server status and tools.

Extensions

Extensions package prompts, MCP servers, and commands. They are installed and managed with the gemini extensions command rather than listed in settings.json:

gemini extensions install <source>
gemini extensions list
gemini extensions update <name>
gemini extensions disable <name>
gemini extensions enable <name>
gemini extensions uninstall <name>

Hooks

Hooks are configured in settings.json under the top-level hooks key. Each event takes an array of matcher entries with command hooks:

{
  "hooks": {
    "AfterTool": [
      {
        "matcher": "write_file|replace",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint"
          }
        ]
      }
    ]
  }
}

Hook events include BeforeTool, AfterTool, BeforeAgent, AfterAgent, BeforeModel, AfterModel, Notification, SessionStart, SessionEnd, and PreCompress. Hooks are not shell scripts stored in .gemini/hooks/.

Environment Variables

Related Pages

• MCP Setup in Gemini CLI — step-by-step MCP configuration
• Gemini CLI Getting Started — Installation and setup
• Prompt Engineering in Gemini CLI — prompting and context strategy
• MCP Section — Browse MCP servers

Sources

• Gemini CLI configuration
• Gemini CLI sandboxing
• Gemini CLI hooks
• Gemini CLI extensions
• Gemini CLI authentication
• MCP reference servers