Configure Gemini CLI with settings.json

• System defaults file: /etc/gemini-cli/system-defaults.json (Linux), C:\ProgramData\gemini-cli\system-defaults.json (Windows), or /Library/Application Support/GeminiCli/system-defaults.json (macOS). Lowest precedence of the files.
• User settings file: ~/.gemini/settings.json. Applies to all your sessions and overrides system defaults.
• Project settings file: .gemini/settings.json in your project root. Overrides user settings and system defaults.
• System settings file: /etc/gemini-cli/settings.json (Linux), C:\ProgramData\gemini-cli\settings.json (Windows), or /Library/Application Support/GeminiCli/settings.json (macOS). Overrides all other settings files.

Full order, lowest to highest: built-in defaults, the system defaults file, the user file, the project file, the system settings file, environment variables, and then command-line arguments. String values can reference environment variables as $VAR_NAME, ${VAR_NAME}, or ${VAR_NAME:-DEFAULT_VALUE}.

Settings are grouped into categories, and each setting must sit inside its top-level category object. Common ones are general (for example vimMode and defaultApprovalMode), ui (for example theme), model (for example name), context, tools, and mcp. Editors can validate the file against the schema published in the gemini-cli repo at schemas/settings.schema.json.

{
  "general": {
    "vimMode": true,
    "defaultApprovalMode": "auto_edit"
  },
  "ui": {
    "theme": "GitHub"
  },
  "tools": {
    "sandbox": "docker"
  }
}

general.defaultApprovalMode accepts default, auto_edit, or plan. YOLO mode cannot be set here. You can only turn it on from the command line with --yolo or --approval-mode=yolo.

Add servers under the top-level mcpServers object. Each server needs at least one of command (a local stdio server), url (a Server-Sent Events endpoint), or httpUrl (a streamable HTTP endpoint). If you set more than one, httpUrl wins, then url, then command. Optional fields include args, env, cwd, headers, timeout (in milliseconds), trust, includeTools, and excludeTools. Avoid underscores in server names: use my-server, not my_server.

{
  "mcpServers": {
    "python-tools": {
      "command": "python",
      "args": ["server.py"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      }
    },
    "remote-tools": {
      "httpUrl": "https://api.example.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      },
      "timeout": 5000
    }
  }
}

gemini mcp add writes to the project file .gemini/settings.json by default. Use -s user to write to ~/.gemini/settings.json instead. The transport defaults to stdio, and you can choose http or sse with -t or --transport.

gemini mcp add -e API_KEY=123 my-stdio-server /path/to/server arg1 arg2
gemini mcp add --transport http http-server https://api.example.com/mcp/
gemini mcp add -s user --transport http --header "Authorization: Bearer abc123" secure-http https://api.example.com/mcp/
gemini mcp list

Gemini CLI loads context files, named GEMINI.md by default, and sends their combined contents with every prompt. It loads a global ~/.gemini/GEMINI.md, then GEMINI.md files in your workspace directories and their parent directories. When a tool touches a file or folder, it also picks up GEMINI.md files in that directory and its ancestors, up to a trusted root. Run /memory show to see the combined context and /memory reload to rescan. A GEMINI.md file can pull in other files with @file.md imports.

To use AGENTS.md or other file names, set context.fileName in settings.json. It accepts a single string or an array of names.

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}