0
# Configuration Management
1

2
The Gemini CLI features a hierarchical configuration system that supports system-wide, user-specific, and workspace-specific settings with extensive customization options.
3

4
## Capabilities
5

6
### Settings Hierarchy
7

8
Configuration is loaded in order of precedence, with later scopes overriding earlier ones.
9

10
```typescript { .api }
11
enum SettingScope {
12
  SystemDefaults = 'systemDefaults',    // Built-in defaults
13
  System = 'system',                    // System-wide configuration
14
  User = 'user',                        // User home directory (~/.gemini/settings.json)
15
  Workspace = 'workspace'               // Project directory (.gemini/settings.json)
16
}
17
```
18

19
**File Locations:**
20

21
```bash
22
# System defaults (built-in)
23
# No file - hardcoded in application
24

25
# System-wide settings
26
/etc/gemini/settings.json
27

28
# User settings
29
~/.gemini/settings.json
30

31
# Workspace settings
32
.gemini/settings.json
33
```
34

35
### Settings Loading API
36

37
```typescript { .api }
38
/**
39
 * Load settings from all scopes, merging in hierarchy order
40
 * @param workspaceDir - Optional workspace directory path
41
 * @returns Loaded settings with scope access methods
42
 */
43
function loadSettings(workspaceDir?: string): LoadedSettings;
44

45
class LoadedSettings {
46
  /** Merged settings from all scopes */
47
  merged: Settings;
48

49
  /**
50
   * Get settings for specific scope
51
   * @param scope - Setting scope to retrieve
52
   * @returns Settings file for the scope
53
   */
54
  forScope(scope: SettingScope): SettingsFile;
55

56
  /**
57
   * Set value in specific scope
58
   * @param scope - Target scope for the setting
59
   * @param key - Setting key path (dot notation supported)
60
   * @param value - Value to set
61
   */
62
  setValue(scope: SettingScope, key: string, value: unknown): void;
63
}
64
```
65

66
## Settings Categories
67

68
### General Settings
69

70
Core application behavior and preferences.
71

72
```typescript { .api }
73
interface GeneralSettings {
74
  /** Preferred external editor command */
75
  preferredEditor?: string;
76

77
  /** Enable Vim mode for text editing */
78
  vimMode?: boolean;
79

80
  /** Disable automatic application updates */
81
  disableAutoUpdate?: boolean;
82

83
  /** Disable update notification prompts */
84
  disableUpdateNag?: boolean;
85

86
  /** File edit checkpointing configuration */
87
  checkpointing?: {
88
    enabled: boolean;
89
  };
90

91
  /** Enable prompt completion suggestions */
92
  enablePromptCompletion?: boolean;
93

94
  /** Enable debug-level keystroke logging */
95
  debugKeystrokeLogging?: boolean;
96
}
97
```
98

99
**Usage Examples:**
100

101
```json
102
{
103
  "general": {
104
    "preferredEditor": "code",
105
    "vimMode": true,
106
    "checkpointing": {
107
      "enabled": true
108
    }
109
  }
110
}
111
```
112

113
### UI Settings
114

115
Terminal interface appearance and behavior customization.
116

117
```typescript { .api }
118
interface UISettings {
119
  /** Active theme name */
120
  theme?: string;
121

122
  /** Custom theme definitions */
123
  customThemes?: Record<string, CustomTheme>;
124

125
  /** Hide window title bar */
126
  hideWindowTitle?: boolean;
127

128
  /** Hide helpful tips display */
129
  hideTips?: boolean;
130

131
  /** Hide startup banner */
132
  hideBanner?: boolean;
133

134
  /** Hide context summary display */
135
  hideContextSummary?: boolean;
136

137
  /** Hide footer information */
138
  hideFooter?: boolean;
139

140
  /** Show memory usage in status bar */
141
  showMemoryUsage?: boolean;
142

143
  /** Show line numbers in code blocks */
144
  showLineNumbers?: boolean;
145

146
  /** Show citation information */
147
  showCitations?: boolean;
148

149
  /** Custom witty loading phrases */
150
  customWittyPhrases?: string[];
151

152
  /** Footer component visibility settings */
153
  footer?: {
154
    hideCWD?: boolean;
155
    hideSandboxStatus?: boolean;
156
    hideModelInfo?: boolean;
157
  };
158

159
  /** Accessibility configuration */
160
  accessibility?: {
161
    /** Disable animated loading phrases */
162
    disableLoadingPhrases?: boolean;
163

164
    /** Enable screen reader optimizations */
165
    screenReader?: boolean;
166
  };
167
}
168
```
169

170
**Usage Examples:**
171

172
```json
173
{
174
  "ui": {
175
    "theme": "dracula",
176
    "showMemoryUsage": true,
177
    "hideFooter": false,
178
    "customWittyPhrases": [
179
      "Thinking deeply...",
180
      "Processing your request..."
181
    ],
182
    "accessibility": {
183
      "screenReader": true
184
    }
185
  }
186
}
187
```
188

189
### Model Settings
190

191
AI model configuration and behavior settings.
192

193
```typescript { .api }
194
interface ModelSettings {
195
  /** Model name/identifier */
196
  name?: string;
197

198
  /** Maximum conversation turns before compression */
199
  maxSessionTurns?: number;
200

201
  /** Tool output summarization settings */
202
  summarizeToolOutput?: Record<string, any>;
203

204
  /** Chat compression configuration */
205
  chatCompression?: Record<string, any>;
206

207
  /** Skip next speaker validation check */
208
  skipNextSpeakerCheck?: boolean;
209
}
210
```
211

212
**Usage Examples:**
213

214
```json
215
{
216
  "model": {
217
    "name": "gemini-2.0-flash-exp",
218
    "maxSessionTurns": 50
219
  }
220
}
221
```
222

223
### Context Settings
224

225
Context loading and file discovery configuration.
226

227
```typescript { .api }
228
interface ContextSettings {
229
  /** Context file name(s) to load */
230
  fileName?: string | string[];
231

232
  /** Context import format */
233
  importFormat?: 'tree' | 'flat';
234

235
  /** Maximum directories to discover */
236
  discoveryMaxDirs?: number;
237

238
  /** Additional directories to include in context */
239
  includeDirectories?: string[];
240

241
  /** Load memory from include directories */
242
  loadMemoryFromIncludeDirectories?: boolean;
243

244
  /** File filtering options */
245
  fileFiltering?: {
246
    /** Respect .gitignore files */
247
    respectGitIgnore?: boolean;
248

249
    /** Respect .geminiignore files */
250
    respectGeminiIgnore?: boolean;
251

252
    /** Enable recursive file search */
253
    enableRecursiveFileSearch?: boolean;
254

255
    /** Disable fuzzy file matching */
256
    disableFuzzySearch?: boolean;
257
  };
258
}
259
```
260

261
**Usage Examples:**
262

263
```json
264
{
265
  "context": {
266
    "fileName": ["GEMINI.md", "README.md"],
267
    "importFormat": "tree",
268
    "includeDirectories": ["src", "docs"],
269
    "fileFiltering": {
270
      "respectGitIgnore": true,
271
      "enableRecursiveFileSearch": true
272
    }
273
  }
274
}
275
```
276

277
### Tools Settings
278

279
Tool availability and behavior configuration.
280

281
```typescript { .api }
282
interface ToolsSettings {
283
  /** Sandbox configuration (boolean or image URI) */
284
  sandbox?: boolean | string;
285

286
  /** Use pseudo-terminal for shell commands */
287
  usePty?: boolean;
288

289
  /** Automatically accept tool usage */
290
  autoAccept?: boolean;
291

292
  /** Core tools always available */
293
  core?: string[];
294

295
  /** Tools allowed without confirmation */
296
  allowed?: string[];
297

298
  /** Tools to exclude from availability */
299
  exclude?: string[];
300

301
  /** Command for tool discovery */
302
  discoveryCommand?: string;
303

304
  /** Command for tool execution */
305
  callCommand?: string;
306

307
  /** Use ripgrep for search operations */
308
  useRipgrep?: boolean;
309

310
  /** Enable tool output truncation */
311
  enableToolOutputTruncation?: boolean;
312

313
  /** Threshold for output truncation */
314
  truncateToolOutputThreshold?: number;
315

316
  /** Number of lines to keep when truncating */
317
  truncateToolOutputLines?: number;
318
}
319
```
320

321
**Usage Examples:**
322

323
```json
324
{
325
  "tools": {
326
    "sandbox": true,
327
    "autoAccept": false,
328
    "allowed": ["file_edit", "shell", "web_search"],
329
    "useRipgrep": true,
330
    "enableToolOutputTruncation": true,
331
    "truncateToolOutputThreshold": 1000
332
  }
333
}
334
```
335

336
### Security Settings
337

338
Security, authentication, and trust configuration.
339

340
```typescript { .api }
341
interface SecuritySettings {
342
  /** Folder trust system configuration */
343
  folderTrust?: {
344
    enabled: boolean;
345
  };
346

347
  /** Authentication configuration */
348
  auth?: {
349
    /** Currently selected authentication type */
350
    selectedType?: AuthType;
351

352
    /** Enforced authentication type (if set) */
353
    enforcedType?: AuthType;
354

355
    /** Use external authentication provider */
356
    useExternal?: boolean;
357
  };
358
}
359

360
enum AuthType {
361
  LOGIN_WITH_GOOGLE = 'login_with_google',
362
  CLOUD_SHELL = 'cloud_shell'
363
  // Additional auth types available
364
}
365
```
366

367
**Usage Examples:**
368

369
```json
370
{
371
  "security": {
372
    "folderTrust": {
373
      "enabled": true
374
    },
375
    "auth": {
376
      "selectedType": "login_with_google",
377
      "useExternal": false
378
    }
379
  }
380
}
381
```
382

383
### MCP Settings
384

385
Model Context Protocol server configuration.
386

387
```typescript { .api }
388
interface MCPSettings {
389
  /** Default server command template */
390
  serverCommand?: string;
391

392
  /** Globally allowed MCP server names */
393
  allowed?: string[];
394

395
  /** Globally excluded MCP server names */
396
  excluded?: string[];
397
}
398

399
interface MCPServerConfig {
400
  // Stdio transport
401
  command?: string;
402
  args?: string[];
403
  env?: Record<string, string>;
404

405
  // HTTP/SSE transport
406
  url?: string;
407
  httpUrl?: string;
408
  headers?: Record<string, string>;
409

410
  // Configuration
411
  timeout?: number;
412
  trust?: boolean;
413
  description?: string;
414
  includeTools?: string[];
415
  excludeTools?: string[];
416
  extensionName?: string;
417
}
418
```
419

420
### IDE Settings
421

422
IDE integration and mode configuration.
423

424
```typescript { .api }
425
interface IDESettings {
426
  /** Enable IDE integration mode */
427
  enabled?: boolean;
428

429
  /** Whether user has seen IDE integration nudge */
430
  hasSeenNudge?: boolean;
431
}
432
```
433

434
### Privacy Settings
435

436
Privacy and usage statistics configuration.
437

438
```typescript { .api }
439
interface PrivacySettings {
440
  /** Enable collection of usage statistics */
441
  usageStatisticsEnabled?: boolean;
442
}
443
```
444

445
### Experimental Settings
446

447
Settings for experimental features and functionality.
448

449
```typescript { .api }
450
interface ExperimentalSettings {
451
  /** Enable extension management features */
452
  extensionManagement?: boolean;
453
}
454
```
455

456
### Extensions Settings
457

458
Configuration for extension system and management.
459

460
```typescript { .api }
461
interface ExtensionsSettings {
462
  /** List of disabled extensions */
463
  disabled?: string[];
464

465
  /** Workspaces where migration nudge has been shown */
466
  workspacesWithMigrationNudge?: string[];
467
}
468
```
469

470
### Advanced Settings
471

472
Advanced configuration options for power users.
473

474
```typescript { .api }
475
interface AdvancedSettings {
476
  /** Automatically configure Node.js memory limits */
477
  autoConfigureMemory?: boolean;
478

479
  /** Configuration for the bug report command */
480
  bugCommand?: BugCommandSettings;
481
}
482

483
interface BugCommandSettings {
484
  /** Custom bug report template */
485
  template?: string;
486

487
  /** Additional data to include in bug reports */
488
  includeSystemInfo?: boolean;
489
}
490
```
491

492
**Complete Settings Interface:**
493

494
```typescript { .api }
495
interface Settings {
496
  general?: GeneralSettings;
497
  ui?: UISettings;
498
  model?: ModelSettings;
499
  context?: ContextSettings;
500
  tools?: ToolsSettings;
501
  security?: SecuritySettings;
502
  mcp?: MCPSettings;
503
  mcpServers?: Record<string, MCPServerConfig>;
504

505
  // Top-level settings
506
  useSmartEdit?: boolean;
507

508
  // Additional setting categories
509
  ide?: IDESettings;
510
  privacy?: PrivacySettings;
511
  experimental?: ExperimentalSettings;
512
  extensions?: ExtensionsSettings;
513
  advanced?: AdvancedSettings;
514
}
515
```
516

517
**Usage Examples:**
518

519
```json
520
{
521
  "mcp": {
522
    "allowed": ["weather-service", "calculator"],
523
    "excluded": ["untrusted-server"]
524
  },
525
  "mcpServers": {
526
    "weather-service": {
527
      "command": "npx",
528
      "args": ["weather-mcp-server"],
529
      "description": "Weather information provider",
530
      "trust": true
531
    },
532
    "api-gateway": {
533
      "url": "http://localhost:3000/mcp",
534
      "headers": {
535
        "Authorization": "Bearer token123"
536
      },
537
      "timeout": 5000
538
    }
539
  }
540
}
541
```
542

543
## Configuration Management API
544

545
### Settings File Operations
546

547
```typescript { .api }
548
interface SettingsFile {
549
  /** File path */
550
  path: string;
551

552
  /** Settings data */
553
  data: Partial<Settings>;
554

555
  /** Check if file exists */
556
  exists(): boolean;
557

558
  /** Load settings from file */
559
  load(): Partial<Settings>;
560

561
  /** Save settings to file */
562
  save(settings: Partial<Settings>): void;
563
}
564
```
565

566
### Configuration Validation
567

568
```typescript { .api }
569
/**
570
 * Validate settings configuration
571
 * @param settings - Settings object to validate
572
 * @returns Validation result with errors if any
573
 */
574
function validateSettings(settings: Settings): {
575
  valid: boolean;
576
  errors: string[];
577
  warnings: string[];
578
};
579
```
580

581
### Dynamic Configuration
582

583
Settings can be modified at runtime through the interactive interface:
584

585
```typescript { .api }
586
/**
587
 * Update setting value and persist to appropriate scope
588
 * @param key - Setting key path (e.g., "ui.theme")
589
 * @param value - New value
590
 * @param scope - Target scope for persistence
591
 */
592
function updateSetting(
593
  key: string,
594
  value: any,
595
  scope: SettingScope
596
): Promise<void>;
597
```
598

599
## Environment Variable Integration
600

601
Settings can reference environment variables for sensitive or deployment-specific values:
602

603
```json
604
{
605
  "tools": {
606
    "sandbox": "${SANDBOX_IMAGE_URI:-true}"
607
  },
608
  "mcp": {
609
    "serverCommand": "${MCP_SERVER_COMMAND}"
610
  }
611
}
612
```
613

614
## Configuration Migration
615

616
The configuration system includes migration support for handling breaking changes:
617

618
```typescript { .api }
619
interface ConfigMigration {
620
  /** Migration version identifier */
621
  version: string;
622

623
  /** Migration description */
624
  description: string;
625

626
  /** Migration function */
627
  migrate: (oldSettings: any) => Settings;
628
}
629
```