0
# Configuration and Setup
1

2
Configuration management for Gemini CLI Core applications, providing centralized settings, authentication methods, storage management, and extensibility options.
3

4
## Capabilities
5

6
### Config Class
7

8
Main configuration management class that handles all application settings, authentication, and behavior configuration.
9

10
```typescript { .api }
11
/**
12
 * Main configuration management class for Gemini CLI Core applications
13
 */
14
class Config {
15
  constructor(parameters: ConfigParameters);
16

17
  // Initialization
18
  async initialize(): Promise<void>;
19

20
  // Authentication
21
  async refreshAuth(authMethod: AuthType): Promise<void>;
22
  getUserTier(): UserTierId | undefined;
23

24
  // Content generation
25
  getContentGenerator(): ContentGenerator;
26
  getContentGeneratorConfig(): ContentGeneratorConfig;
27

28
  // Model configuration
29
  getModel(): string;
30
  setModel(newModel: string): void;
31

32
  // Session management
33
  getSessionId(): string;
34
  getMaxSessionTurns(): number;
35

36
  // Tool approval settings
37
  getApprovalMode(): ApprovalMode;
38
  setApprovalMode(mode: ApprovalMode): void;
39

40
  // Extension management
41
  getExtensions(): GeminiCLIExtension[];
42

43
  // Telemetry settings
44
  getTelemetryEnabled(): boolean;
45
  getTelemetryLogPromptsEnabled(): boolean;
46
  getTelemetryTarget(): TelemetryTarget;
47
  getTelemetryOtlpEndpoint(): string;
48
  getTelemetryOutfile(): string | undefined;
49

50
  // File filtering options
51
  getFileFilteringOptions(): FileFilteringOptions;
52
  getFileFilteringRespectGitIgnore(): boolean;
53
  getFileFilteringRespectGeminiIgnore(): boolean;
54
  getEnableRecursiveFileSearch(): boolean;
55
  getFileFilteringDisableFuzzySearch(): boolean;
56

57
  // Directory and workspace
58
  getTargetDir(): string;
59
  getProjectRoot(): string;
60
  getWorkspaceContext(): WorkspaceContext;
61
  getWorkingDir(): string;
62

63
  // Tool management
64
  getToolRegistry(): ToolRegistry;
65
  getCoreTools(): string[] | undefined;
66
  getAllowedTools(): string[] | undefined;
67
  getExcludeTools(): string[] | undefined;
68

69
  // Memory management
70
  getUserMemory(): string;
71
  setUserMemory(newUserMemory: string): void;
72
  getGeminiMdFileCount(): number;
73
  setGeminiMdFileCount(count: number): void;
74
  shouldLoadMemoryFromIncludeDirectories(): boolean;
75

76
  // MCP server configuration
77
  getMcpServers(): Record<string, MCPServerConfig> | undefined;
78
  getMcpServerCommand(): string | undefined;
79
  getBlockedMcpServers(): Array<{ name: string; extensionName: string }>;
80

81
  // Services
82
  getFileService(): FileDiscoveryService;
83
  getFileSystemService(): FileSystemService;
84
  setFileSystemService(fileSystemService: FileSystemService): void;
85

86
  // Client instances
87
  getGeminiClient(): GeminiClient;
88
  getBaseLlmClient(): BaseLlmClient;
89

90
  // Git service
91
  async getGitService(): Promise<GitService>;
92
  async createToolRegistry(): Promise<ToolRegistry>;
93

94
  // Prompt registry
95
  getPromptRegistry(): PromptRegistry;
96

97
  // Feature flags and settings
98
  getDebugMode(): boolean;
99
  getFullContext(): boolean;
100
  getCheckpointingEnabled(): boolean;
101
  getAccessibility(): AccessibilitySettings;
102
  getShowMemoryUsage(): boolean;
103
  getUsageStatisticsEnabled(): boolean;
104
  getNoBrowser(): boolean;
105
  isBrowserLaunchSuppressed(): boolean;
106
  getIdeMode(): boolean;
107
  setIdeMode(value: boolean): void;
108
  getFolderTrustFeature(): boolean;
109
  getFolderTrust(): boolean;
110
  isTrustedFolder(): boolean;
111
  isInteractive(): boolean;
112
  getUseRipgrep(): boolean;
113
  getShouldUseNodePtyShell(): boolean;
114
  getSkipNextSpeakerCheck(): boolean;
115
  getScreenReader(): boolean;
116
  getEnablePromptCompletion(): boolean;
117
  getEnableToolOutputTruncation(): boolean;
118
  getTruncateToolOutputThreshold(): number;
119
  getTruncateToolOutputLines(): number;
120
  getUseSmartEdit(): boolean;
121

122
  // Fallback mode
123
  isInFallbackMode(): boolean;
124
  setFallbackMode(active: boolean): void;
125
  setFallbackModelHandler(handler: FallbackModelHandler): void;
126
  setQuotaErrorOccurred(value: boolean): void;
127
  getQuotaErrorOccurred(): boolean;
128

129
  // Additional methods
130
  getEmbeddingModel(): string;
131
  getSandbox(): SandboxConfig | undefined;
132
  isRestrictiveSandbox(): boolean;
133
  getQuestion(): string | undefined;
134
  getToolDiscoveryCommand(): string | undefined;
135
  getToolCallCommand(): string | undefined;
136
  getChatCompression(): ChatCompressionSettings | undefined;
137
  getProxy(): string | undefined;
138
  getBugCommand(): BugCommandSettings | undefined;
139
  getExtensionContextFilePaths(): string[];
140
  getCustomExcludes(): string[];
141
  getFileExclusions(): FileExclusions;
142
}
143

144
interface ConfigParameters {
145
  sessionId: string;
146
  targetDir: string;
147
  debugMode: boolean;
148
  cwd: string;
149
  model: string;
150
  embeddingModel?: string;
151
  sandbox?: SandboxConfig;
152
  question?: string;
153
  fullContext?: boolean;
154
  coreTools?: string[];
155
  allowedTools?: string[];
156
  excludeTools?: string[];
157
  toolDiscoveryCommand?: string;
158
  toolCallCommand?: string;
159
  mcpServerCommand?: string;
160
  mcpServers?: Record<string, MCPServerConfig>;
161
  userMemory?: string;
162
  geminiMdFileCount?: number;
163
  approvalMode?: ApprovalMode;
164
  showMemoryUsage?: boolean;
165
  contextFileName?: string | string[];
166
  accessibility?: AccessibilitySettings;
167
  telemetry?: TelemetrySettings;
168
  usageStatisticsEnabled?: boolean;
169
  fileFiltering?: {
170
    respectGitIgnore?: boolean;
171
    respectGeminiIgnore?: boolean;
172
    enableRecursiveFileSearch?: boolean;
173
    disableFuzzySearch?: boolean;
174
  };
175
  checkpointing?: boolean;
176
  proxy?: string;
177
  fileDiscoveryService?: FileDiscoveryService;
178
  includeDirectories?: string[];
179
  bugCommand?: BugCommandSettings;
180
  extensionContextFilePaths?: string[];
181
  maxSessionTurns?: number;
182
  experimentalZedIntegration?: boolean;
183
  listExtensions?: boolean;
184
  extensions?: GeminiCLIExtension[];
185
  blockedMcpServers?: Array<{ name: string; extensionName: string }>;
186
  noBrowser?: boolean;
187
  summarizeToolOutput?: Record<string, SummarizeToolOutputSettings>;
188
  folderTrustFeature?: boolean;
189
  folderTrust?: boolean;
190
  ideMode?: boolean;
191
  loadMemoryFromIncludeDirectories?: boolean;
192
  chatCompression?: ChatCompressionSettings;
193
  interactive?: boolean;
194
  trustedFolder?: boolean;
195
  useRipgrep?: boolean;
196
  shouldUseNodePtyShell?: boolean;
197
  skipNextSpeakerCheck?: boolean;
198
  extensionManagement?: boolean;
199
  enablePromptCompletion?: boolean;
200
  truncateToolOutputThreshold?: number;
201
  truncateToolOutputLines?: number;
202
  enableToolOutputTruncation?: boolean;
203
  eventEmitter?: EventEmitter;
204
  useSmartEdit?: boolean;
205
}
206
```
207

208
### Authentication Types
209

210
Enumeration of supported authentication methods for different deployment scenarios.
211

212
```typescript { .api }
213
/**
214
 * Authentication provider types for content generation
215
 */
216
enum AuthType {
217
  /** OAuth personal authentication with Google */
218
  LOGIN_WITH_GOOGLE = 'oauth-personal',
219
  /** Direct Gemini API key authentication */
220
  USE_GEMINI = 'gemini-api-key',
221
  /** Vertex AI service authentication */
222
  USE_VERTEX_AI = 'vertex-ai',
223
  /** Google Cloud Shell built-in authentication */
224
  CLOUD_SHELL = 'cloud-shell'
225
}
226

227
enum AuthProviderType {
228
  /** Dynamic OAuth discovery */
229
  DYNAMIC_DISCOVERY = 'DYNAMIC_DISCOVERY',
230
  /** Google credentials provider */
231
  GOOGLE_CREDENTIALS = 'GOOGLE_CREDENTIALS'
232
}
233
```
234

235
### Approval Modes
236

237
Tool execution approval modes that control how tools are confirmed before execution.
238

239
```typescript { .api }
240
/**
241
 * Tool execution approval modes
242
 */
243
enum ApprovalMode {
244
  /** Default approval mode - prompt for confirmation */
245
  DEFAULT = 'default',
246
  /** Auto-approve edit operations */
247
  AUTO_EDIT = 'autoEdit',
248
  /** Auto-approve all operations (proceed without confirmation) */
249
  YOLO = 'yolo'
250
}
251
```
252

253
### Storage Management
254

255
File system storage management for application data, settings, and temporary files.
256

257
```typescript { .api }
258
/**
259
 * File system storage management for application data and settings
260
 */
261
class Storage {
262
  constructor(projectRoot?: string);
263
  
264
  // Global storage paths (static methods)
265
  static getGlobalGeminiDir(): string;
266
  static getMcpOAuthTokensPath(): string;
267
  static getGlobalSettingsPath(): string;
268
  static getInstallationIdPath(): string;
269
  static getGoogleAccountsPath(): string;
270
  static getUserCommandsDir(): string;
271
  static getGlobalMemoryFilePath(): string;
272
  static getGlobalTempDir(): string;
273
  static getGlobalBinDir(): string;
274
  static getOAuthCredsPath(): string;
275
  
276
  // Project-specific storage paths (instance methods)
277
  getGeminiDir(): string;
278
  getProjectTempDir(): string;
279
  ensureProjectTempDirExists(): void;
280
  getProjectRoot(): string;
281
  getHistoryDir(): string;
282
  getWorkspaceSettingsPath(): string;
283
  getProjectCommandsDir(): string;
284
  getProjectTempCheckpointsDir(): string;
285
  getExtensionsDir(): string;
286
  getExtensionsConfigPath(): string;
287
  getHistoryFilePath(): string;
288
}
289
```
290

291
### MCP Server Configuration
292

293
Configuration for Model Context Protocol servers and their integration settings.
294

295
```typescript { .api }
296
/**
297
 * Configuration for MCP (Model Context Protocol) servers
298
 */
299
class MCPServerConfig {
300
  constructor(
301
    command?: string,
302
    args?: string[],
303
    env?: Record<string, string>,
304
    cwd?: string,
305
    url?: string,
306
    httpUrl?: string,
307
    headers?: Record<string, string>,
308
    tcp?: string,
309
    timeout?: number,
310
    trust?: boolean
311
  );
312
}
313

314
interface MCPOAuthConfig {
315
  authorizationUrl: string;
316
  tokenUrl: string;
317
  clientId: string;
318
  scopes?: string[];
319
}
320
```
321

322
### Configuration Interfaces
323

324
Detailed configuration interfaces for various application aspects.
325

326
```typescript { .api }
327
/**
328
 * Accessibility configuration settings
329
 */
330
interface AccessibilitySettings {
331
  enableHighContrast?: boolean;
332
  enableLargeText?: boolean;
333
  enableScreenReader?: boolean;
334
}
335

336
/**
337
 * Bug reporting command settings
338
 */
339
interface BugCommandSettings {
340
  enabled: boolean;
341
  includeLogs?: boolean;
342
  includeConfig?: boolean;
343
}
344

345
/**
346
 * Chat compression configuration
347
 */
348
interface ChatCompressionSettings {
349
  enabled: boolean;
350
  threshold: number;
351
  targetSize: number;
352
}
353

354
/**
355
 * File filtering options for content discovery
356
 */
357
interface FileFilteringOptions {
358
  excludePatterns?: string[];
359
  includePatterns?: string[];
360
  maxFileSize?: number;
361
  excludeHidden?: boolean;
362
  respectGitIgnore?: boolean;
363
  respectGeminiIgnore?: boolean;
364
}
365

366
/**
367
 * Extension metadata and configuration
368
 */
369
interface GeminiCLIExtension {
370
  name: string;
371
  version: string;
372
  description?: string;
373
  author?: string;
374
  main: string;
375
  enabled: boolean;
376
  config?: Record<string, any>;
377
}
378

379
/**
380
 * Sandbox configuration for secure execution
381
 */
382
interface SandboxConfig {
383
  enabled: boolean;
384
  allowedCommands?: string[];
385
  restrictedPaths?: string[];
386
  timeoutMs?: number;
387
}
388

389
/**
390
 * Tool output summarization settings
391
 */
392
interface SummarizeToolOutputSettings {
393
  enabled: boolean;
394
  threshold: number;
395
  maxLength: number;
396
}
397

398
/**
399
 * Telemetry configuration settings
400
 */
401
interface TelemetrySettings {
402
  enabled: boolean;
403
  endpoint?: string;
404
  apiKey?: string;
405
  sampleRate?: number;
406
  includeErrorReports?: boolean;
407
}
408
```
409

410
### Constants and Defaults
411

412
Default values and constants used throughout the configuration system.
413

414
```typescript { .api }
415
/**
416
 * Default Gemini Flash model identifier
417
 */
418
const DEFAULT_GEMINI_FLASH_MODEL: string;
419

420
/**
421
 * Default file filtering configuration
422
 */
423
const DEFAULT_FILE_FILTERING_OPTIONS: FileFilteringOptions;
424

425
/**
426
 * Default memory file filtering options
427
 */
428
const DEFAULT_MEMORY_FILE_FILTERING_OPTIONS: FileFilteringOptions;
429

430
/**
431
 * Default tool output truncation threshold in characters
432
 */
433
const DEFAULT_TRUNCATE_TOOL_OUTPUT_THRESHOLD: number;
434

435
/**
436
 * Default tool output truncation lines
437
 */
438
const DEFAULT_TRUNCATE_TOOL_OUTPUT_LINES: number;
439

440
/**
441
 * Local gemini directory name
442
 */
443
const GEMINI_DIR: string;
444

445
/**
446
 * Google accounts file name
447
 */
448
const GOOGLE_ACCOUNTS_FILENAME: string;
449

450
/**
451
 * OAuth credentials file name
452
 */
453
const OAUTH_FILE: string;
454
```
455

456
### Additional Type Definitions
457

458
Core types used throughout the configuration system.
459

460
```typescript { .api }
461
/**
462
 * Content generator interface for AI model interactions
463
 */
464
interface ContentGenerator {
465
  generateContent(request: GenerateContentRequest): Promise<GenerateContentResponse>;
466
  generateContentStream(request: GenerateContentRequest): AsyncGenerator<GenerateContentResponse>;
467
  countTokens(request: CountTokensRequest): Promise<CountTokensResponse>;
468
  embedContent(request: EmbedContentRequest): Promise<EmbedContentResponse>;
469
}
470

471
/**
472
 * Configuration for content generators
473
 */
474
interface ContentGeneratorConfig {
475
  model: string;
476
  apiKey?: string;
477
  authType?: AuthType;
478
  projectId?: string;
479
  location?: string;
480
}
481

482
/**
483
 * Workspace context management for project awareness
484
 */
485
class WorkspaceContext {
486
  constructor(initialDirectories?: Set<string>);
487

488
  addDirectory(directory: string): void;
489
  removeDirectory(directory: string): void;
490
  getDirectories(): Set<string>;
491
  hasDirectory(directory: string): boolean;
492
  addListener(listener: () => void): void;
493
  removeListener(listener: () => void): void;
494
  clear(): void;
495
}
496

497
/**
498
 * Tool registry for managing available tools
499
 */
500
class ToolRegistry {
501
  constructor();
502

503
  addTool(tool: AnyDeclarativeTool): void;
504
  getTool(name: string): AnyDeclarativeTool | undefined;
505
  getTools(): AnyDeclarativeTool[];
506
  getFunctionDeclarations(): FunctionDeclaration[];
507
  removeTool(name: string): void;
508
  clear(): void;
509
}
510

511
/**
512
 * Base LLM client for model interactions
513
 */
514
class BaseLlmClient {
515
  constructor(config: Config);
516

517
  // Core client methods would be defined here
518
}
519

520
/**
521
 * File exclusion pattern management
522
 */
523
class FileExclusions {
524
  constructor();
525

526
  addExclusion(pattern: string): void;
527
  removeExclusion(pattern: string): void;
528
  isExcluded(filePath: string): boolean;
529
  getExclusions(): string[];
530
  clear(): void;
531
}
532

533
/**
534
 * Fallback model handler function type
535
 */
536
type FallbackModelHandler = (error: Error, currentModel: string) => Promise<string | null>;
537
```
538

539
**Usage Examples:**
540

541
```typescript
542
import { Config, AuthType, ApprovalMode, Storage } from '@google/gemini-cli-core';
543

544
// Basic configuration
545
const config = new Config({
546
  model: 'gemini-1.5-flash',
547
  apiKey: process.env.GEMINI_API_KEY,
548
  approvalMode: ApprovalMode.AUTO_EDIT
549
});
550

551
// Advanced configuration with filtering and telemetry
552
const advancedConfig = new Config({
553
  model: 'gemini-1.5-pro',
554
  fileFilteringOptions: {
555
    excludePatterns: ['*.log', 'node_modules/**'],
556
    maxFileSize: 1024 * 1024, // 1MB
557
    respectGitIgnore: true
558
  },
559
  telemetrySettings: {
560
    enabled: true,
561
    sampleRate: 0.1
562
  },
563
  chatCompressionSettings: {
564
    enabled: true,
565
    threshold: 32000,
566
    targetSize: 16000
567
  }
568
});
569

570
// Storage management
571
const storage = new Storage('/path/to/project');
572
const geminiDir = storage.getGeminiDir();
573
const historyPath = storage.getHistoryFilePath();
574

575
// Global storage paths
576
const globalSettings = Storage.getGlobalSettingsPath();
577
const tempDir = Storage.getGlobalTempDir();
578
```