0
# Gemini CLI
1

2
Gemini CLI is an open-source AI agent that brings the power of Gemini directly into your terminal. It provides lightweight access to Gemini models with a comprehensive set of developer-focused features including built-in tools for Google Search grounding, file operations, shell commands, web fetching, and extensible architecture through Model Context Protocol (MCP) support.
3

4
## Package Information
5

6
- **Package Name**: @google/gemini-cli
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install -g @google/gemini-cli`
10
- **Binary Command**: `gemini`
11

12
## Core Imports
13

14
The Gemini CLI is primarily designed as a command-line binary tool and does not expose a public programmatic API for import. It is intended to be used via the `gemini` command-line interface.
15

16
```bash
17
# Install and use as CLI tool
18
npm install -g @google/gemini-cli
19
gemini --help
20
```
21

22
## Basic Usage
23

24
### Interactive Mode
25

26
```bash
27
# Start interactive conversation
28
gemini
29

30
# Start with initial prompt
31
gemini "Explain TypeScript generics"
32

33
# Use with specific model
34
gemini --model gemini-2.0-flash-exp "Review this code"
35

36
# Enable sandbox mode
37
gemini --sandbox "Create a Node.js server"
38
```
39

40
### Non-Interactive Mode
41

42
```bash
43
# Process input from stdin
44
echo "What is recursion?" | gemini --prompt "Explain this concept"
45

46
# One-shot prompt execution
47
gemini --prompt "Generate a README for my project" --yolo
48
```
49

50
## Architecture
51

52
Gemini CLI is built around several key architectural components:
53

54
- **CLI Interface**: Command-line interface with rich option parsing and interactive/non-interactive modes
55
- **React Terminal UI**: Built with Ink framework providing rich terminal interactions with themes and accessibility support
56
- **Configuration System**: Hierarchical settings management across system, user, and workspace scopes
57
- **Extension System**: Plugin architecture allowing custom extensions with MCP server integration
58
- **Theme Engine**: Customizable visual themes for terminal interface with built-in and custom theme support
59
- **Tool Integration**: Built-in tools for file operations, web access, shell commands with extensible tool framework
60
- **Authentication**: Multi-provider authentication system supporting Google OAuth and other auth methods
61

62
## Capabilities
63

64
### Command Line Interface
65

66
Core CLI functionality with comprehensive option support for model selection, execution modes, context configuration, and tool management.
67

68
```typescript { .api }
69
// Global CLI options interface
70
interface CliArgs {
71
  // Model and generation
72
  model?: string;
73
  prompt?: string;
74
  promptInteractive?: string;
75

76
  // Execution environment
77
  sandbox?: boolean | string;
78
  sandboxImage?: string;
79
  debug?: boolean;
80
  yolo?: boolean;
81
  approvalMode?: 'default' | 'auto_edit' | 'yolo';
82

83
  // Context and files
84
  allFiles?: boolean;
85
  includeDirectories?: string[];
86
  checkpointing?: boolean;
87

88
  // Tool configuration
89
  allowedTools?: string[];
90
  allowedMcpServerNames?: string[];
91
  extensions?: string[];
92
  listExtensions?: boolean;
93

94
  // Telemetry and monitoring
95
  telemetry?: boolean;
96
  telemetryTarget?: 'local' | 'gcp';
97
  telemetryOtlpEndpoint?: string;
98
  telemetryOtlpProtocol?: 'grpc' | 'http';
99
  telemetryLogPrompts?: boolean;
100
  telemetryOutfile?: string;
101
  showMemoryUsage?: boolean;
102

103
  // UI and accessibility
104
  screenReader?: boolean;
105
  sessionSummary?: string;
106
  proxy?: string;
107
  experimentalAcp?: boolean;
108

109
  // Positional arguments
110
  promptWords?: string[];
111
}
112
```
113

114
[Command Line Interface](./cli-interface.md)
115

116
### Interactive Commands
117

118
Slash commands and interactive features for managing conversations, settings, tools, and extensions within the terminal interface.
119

120
```typescript { .api }
121
// Interactive slash commands (invoked via /command syntax)
122
type SlashCommand =
123
  | 'help' | 'quit' | 'exit' | 'clear' | 'stats'
124
  | 'settings' | 'theme' | 'auth' | 'memory'
125
  | 'tools' | 'extensions' | 'mcp'
126
  | 'chat' | 'vim' | 'editor';
127
```
128

129
[Interactive Commands](./interactive-commands.md)
130

131
### Configuration Management
132

133
Hierarchical settings system supporting system-wide, user-specific, and workspace-specific configuration with extensive customization options.
134

135
```typescript { .api }
136
interface Settings {
137
  general?: GeneralSettings;
138
  ui?: UISettings;
139
  model?: ModelSettings;
140
  context?: ContextSettings;
141
  tools?: ToolsSettings;
142
  security?: SecuritySettings;
143
  mcp?: MCPSettings;
144
  mcpServers?: Record<string, MCPServerConfig>;
145
}
146

147
enum SettingScope {
148
  SystemDefaults = 'systemDefaults',
149
  System = 'system',
150
  User = 'user',
151
  Workspace = 'workspace'
152
}
153
```
154

155
[Configuration Management](./configuration.md)
156

157
### Extension System
158

159
Plugin architecture enabling custom functionality through extensions and MCP (Model Context Protocol) server integration.
160

161
```typescript { .api }
162
interface Extension {
163
  path: string;
164
  config: ExtensionConfig;
165
  contextFiles: string[];
166
  installMetadata?: ExtensionInstallMetadata;
167
}
168

169
interface ExtensionConfig {
170
  name: string;
171
  version: string;
172
  mcpServers?: Record<string, MCPServerConfig>;
173
  contextFileName?: string | string[];
174
  excludeTools?: string[];
175
}
176
```
177

178
[Extension System](./extensions.md)
179

180
### MCP Integration
181

182
Model Context Protocol integration for connecting external tools and services with support for multiple transport types and server management.
183

184
```typescript { .api }
185
interface MCPServerConfig {
186
  // Stdio transport
187
  command?: string;
188
  args?: string[];
189
  env?: Record<string, string>;
190

191
  // HTTP/SSE transport
192
  url?: string;
193
  httpUrl?: string;
194
  headers?: Record<string, string>;
195

196
  // Configuration
197
  timeout?: number;
198
  trust?: boolean;
199
  description?: string;
200
  includeTools?: string[];
201
  excludeTools?: string[];
202
}
203
```
204

205
[MCP Integration](./mcp-integration.md)
206

207
### Theme System
208

209
Comprehensive theming system with built-in themes, custom theme support, and accessibility features for terminal interface customization.
210

211
```typescript { .api }
212
interface Theme {
213
  name: string;
214
  type: 'light' | 'dark' | 'ansi' | 'custom';
215
  primary?: string;
216
  secondary?: string;
217
  background?: string;
218
  foreground?: string;
219
}
220

221
interface ThemeManager {
222
  getAvailableThemes(): string[];
223
  setActiveTheme(name: string): void;
224
  getActiveTheme(): Theme;
225
  loadCustomThemes(themes: Record<string, Theme>): void;
226
}
227
```
228

229
[Theme System](./themes.md)