Gemini CLI Config Files & Related Files
| File / Artifact | Location | Scope / Purpose |
|---|---|---|
system-defaults.json |
System-wide directory, e.g. /etc/gemini-cli/system-defaults.json on Linux; C:\ProgramData\gemini-cli\system-defaults.json on Windows; or /Library/Application Support/GeminiCli/system-defaults.json on macOS. Google Gemini |
Base system defaults. Lowest precedence among settings files. Google Gemini |
settings.json (User) |
~/.gemini/settings.json in home directory Google Gemini+1 |
User-level config. Applies to all projects for that user. Google Gemini+1 |
settings.json (Project) |
.gemini/settings.json inside a project directory Google Gemini+1 |
Project-specific overrides. Settings that apply when you run inside that project. Google Gemini+1 |
| System settings override file | /etc/gemini-cli/settings.json (Linux), or equivalent for Windows/macOS. Google Gemini |
A system level file with higher precedence than other settings files (except env vars / CLI args). Used by admins. Google Gemini |
Environment variables / .env files |
Project directory or session environment and sometimes parent directories ─ e.g. shell envs or .env files. Medium+2Google Gemini+2 |
For settings that are sensitive or change frequently (API keys, project IDs). They can override file-based settings. Medium+1 |
GEMINI.md |
Global: ~/.gemini/GEMINI.md; Project: ./GEMINI.md or ancestor directories. Philschmid+1 |
Human-readable guidance / context for the model. Projects can override or supplement global contexts. Philschmid+1 |
Precedence / Override Order
Here is how Gemini CLI decides which config takes effect when there are conflicts. Highest precedence > lower precedence.
1. Command-line arguments 2. Environment variables (or `.env`) 3. Project settings file (`.gemini/settings.json`) 4. User settings file (`~/.gemini/settings.json`) 5. System settings override file (`/etc/gemini-cli/settings.json` etc.) 6. System defaults file (`/etc/gemini-cli/system-defaults.json`, or platform equivalent) 7. Built-in defaults (hardcoded values in the app)
Notes:
Some docs list two system settings files (“defaults” and “override”). The “override” one has higher precedence than user & project settings. Google Gemini
Environment variables and CLI arguments always override any setting from files. Medium+1
GEMINI.mdcontext files are loaded in a hierarchical manner: global then project then possibly subdirectory. It’s less about “override” of specific keys and more about how contexts are combined. Philschmid+1
Built-in defaults (hardcoded in binary)
│
├── System defaults file
│ └── /etc/gemini-cli/system-defaults.json
│
├── System settings override file
│ └── /etc/gemini-cli/settings.json
│
├── User settings
│ └── ~/.gemini/settings.json
│
├── Project settings
│ └── .gemini/settings.json
│
├── Environment variables / .env files
│ └── GEMINI_API_KEY=...
│
└── Command-line arguments
└── gemini --model=... --temperature=...
Special files (not strict overrides, but loaded if present):
~/.gemini/GEMINI.md
./GEMINI.md (project-level context)