gemini-cli

Gemini CLI Configuration

Note on Deprecated Configuration Format

This document describes the legacy v1 format for the settings.json file. This format is now deprecated.

For details on the new, recommended format, please see the current Configuration documentation.

Gemini CLI offers several ways to configure its behavior, including environment variables, command-line arguments, and settings files. This document outlines the different configuration methods and available settings.

Configuration layers

Configuration is applied in the following order of precedence (lower numbers are overridden by higher numbers):

  1. Default values: Hardcoded defaults within the application.
  2. System defaults file: System-wide default settings that can be overridden by other settings files.
  3. User settings file: Global settings for the current user.
  4. Project settings file: Project-specific settings.
  5. System settings file: System-wide settings that override all other settings files.
  6. Environment variables: System-wide or session-specific variables, potentially loaded from .env files.
  7. Command-line arguments: Values passed when launching the CLI.

Settings files

Gemini CLI uses JSON settings files for persistent configuration. There are four locations for these files:

Note on environment variables in settings: String values within your settings.json files can reference environment variables using either $VAR_NAME or ${VAR_NAME} syntax. These variables will be automatically resolved when the settings are loaded. For example, if you have an environment variable MY_API_TOKEN, you could use it in settings.json like this: "apiKey": "$MY_API_TOKEN".

Note for Enterprise Users: For guidance on deploying and managing Gemini CLI in a corporate environment, please see the Enterprise Configuration documentation.

The .gemini directory in your project

In addition to a project settings file, a project’s .gemini directory can contain other project-specific files related to Gemini CLI’s operation, such as:

Available settings in settings.json:

Troubleshooting File Search Performance

If you are experiencing performance issues with file searching (e.g., with @ completions), especially in projects with a very large number of files, here are a few things you can try in order of recommendation:

  1. Use .geminiignore: Create a .geminiignore file in your project root to exclude directories that contain a large number of files that you don’t need to reference (e.g., build artifacts, logs, node_modules). Reducing the total number of files crawled is the most effective way to improve performance.

  2. Disable Fuzzy Search: If ignoring files is not enough, you can disable fuzzy search by setting disableFuzzySearch to true in your settings.json file. This will use a simpler, non-fuzzy matching algorithm, which can be faster.

  3. Disable Recursive File Search: As a last resort, you can disable recursive file search entirely by setting enableRecursiveFileSearch to false. This will be the fastest option as it avoids a recursive crawl of your project. However, it means you will need to type the full path to files when using @ completions.

Example settings.json:

{
  "theme": "GitHub",
  "sandbox": "docker",
  "toolDiscoveryCommand": "bin/get_tools",
  "toolCallCommand": "bin/call_tool",
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    },
    "anotherServer": {
      "command": "node",
      "args": ["mcp_server.js", "--verbose"]
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "logPrompts": true
  },
  "usageStatisticsEnabled": true,
  "hideTips": false,
  "hideBanner": false,
  "maxSessionTurns": 10,
  "summarizeToolOutput": {
    "run_shell_command": {
      "tokenBudget": 100
    }
  },
  "excludedProjectEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"],
  "includeDirectories": ["path/to/dir1", "~/path/to/dir2", "../path/to/dir3"],
  "loadMemoryFromIncludeDirectories": true
}

Shell History

The CLI keeps a history of shell commands you run. To avoid conflicts between different projects, this history is stored in a project-specific directory within your user’s home folder.

Environment Variables & .env Files

Environment variables are a common way to configure applications, especially for sensitive information like API keys or for settings that might change between environments. For authentication setup, see the Authentication documentation which covers all available authentication methods.

The CLI automatically loads environment variables from an .env file. The loading order is:

  1. .env file in the current working directory.
  2. If not found, it searches upwards in parent directories until it finds an .env file or reaches the project root (identified by a .git folder) or the home directory.
  3. If still not found, it looks for ~/.env (in the user’s home directory).

Environment Variable Exclusion: Some environment variables (like DEBUG and DEBUG_MODE) are automatically excluded from being loaded from project .env files to prevent interference with gemini-cli behavior. Variables from .gemini/.env files are never excluded. You can customize this behavior using the excludedProjectEnvVars setting in your settings.json file.

Command-Line Arguments

Arguments passed directly when running the CLI can override other configurations for that specific session.

Context Files (Hierarchical Instructional Context)

While not strictly configuration for the CLI’s behavior, context files (defaulting to GEMINI.md but configurable via the contextFileName setting) are crucial for configuring the instructional context (also referred to as “memory”) provided to the Gemini model. This powerful feature allows you to give project-specific instructions, coding style guides, or any relevant background information to the AI, making its responses more tailored and accurate to your needs. The CLI includes UI elements, such as an indicator in the footer showing the number of loaded context files, to keep you informed about the active context.

Example Context File Content (e.g., GEMINI.md)

Here’s a conceptual example of what a context file at the root of a TypeScript project might contain:

# Project: My Awesome TypeScript Library

## General Instructions:

- When generating new TypeScript code, please follow the existing coding style.
- Ensure all new functions and classes have JSDoc comments.
- Prefer functional programming paradigms where appropriate.
- All code should be compatible with TypeScript 5.0 and Node.js 20+.

## Coding Style:

- Use 2 spaces for indentation.
- Interface names should be prefixed with `I` (e.g., `IUserService`).
- Private class members should be prefixed with an underscore (`_`).
- Always use strict equality (`===` and `!==`).

## Specific Component: `src/api/client.ts`

- This file handles all outbound API requests.
- When adding new API call functions, ensure they include robust error handling and logging.
- Use the existing `fetchWithRetry` utility for all GET requests.

## Regarding Dependencies:

- Avoid introducing new external dependencies unless absolutely necessary.
- If a new dependency is required, please state the reason.

This example demonstrates how you can provide general project context, specific coding conventions, and even notes about particular files or components. The more relevant and precise your context files are, the better the AI can assist you. Project-specific context files are highly encouraged to establish conventions and context.

By understanding and utilizing these configuration layers and the hierarchical nature of context files, you can effectively manage the AI’s memory and tailor the Gemini CLI’s responses to your specific needs and projects.

Sandboxing

The Gemini CLI can execute potentially unsafe operations (like shell commands and file modifications) within a sandboxed environment to protect your system.

Sandboxing is disabled by default, but you can enable it in a few ways:

By default, it uses a pre-built gemini-cli-sandbox Docker image.

For project-specific sandboxing needs, you can create a custom Dockerfile at .gemini/sandbox.Dockerfile in your project’s root directory. This Dockerfile can be based on the base sandbox image:

FROM gemini-cli-sandbox

# Add your custom dependencies or configurations here
# For example:
# RUN apt-get update && apt-get install -y some-package
# COPY ./my-config /app/my-config

When .gemini/sandbox.Dockerfile exists, you can use BUILD_SANDBOX environment variable when running Gemini CLI to automatically build the custom sandbox image:

BUILD_SANDBOX=1 gemini -s

Usage Statistics

To help us improve the Gemini CLI, we collect anonymized usage statistics. This data helps us understand how the CLI is used, identify common issues, and prioritize new features.

What we collect:

What we DON’T collect:

How to opt out:

You can opt out of usage statistics collection at any time by setting the usageStatisticsEnabled property to false in your settings.json file:

{
  "usageStatisticsEnabled": false
}
This site is open source. Improve this page.