Complete reference for Gemini CLI v0.16.0+
npm install -g @google/gemini-cli
# Or without installing:
npx @google/gemini-cli# Option 1: API Key
export GEMINI_API_KEY=your_key
# Option 2: OAuth (interactive)
gemini # First run prompts for auth| Flag | Short | Description |
|---|---|---|
--yolo |
-y |
Auto-approve all tool calls |
--output-format |
-o |
Output format: text, json, stream-json |
--model |
-m |
Model selection (e.g., gemini-2.5-flash) |
| Flag | Short | Description |
|---|---|---|
--resume |
-r |
Resume session by index or "latest" |
--list-sessions |
List available sessions | |
--delete-session |
Delete session by index |
| Flag | Short | Description |
|---|---|---|
--sandbox |
-s |
Run in isolated sandbox |
--approval-mode |
default, auto_edit, or yolo |
|
--timeout |
Request timeout in ms | |
--checkpointing |
Enable file change snapshots |
| Flag | Description |
|---|---|
--include-directories |
Add directories to workspace |
--allowed-tools |
Restrict available tools |
--allowed-mcp-server-names |
Restrict MCP servers |
| Flag | Short | Description |
|---|---|---|
--debug |
-d |
Enable debug output |
--version |
-v |
Show version |
--help |
-h |
Show help |
--list-extensions |
-l |
List installed extensions |
--prompt-interactive |
-i |
Interactive mode with initial prompt |
gemini "prompt" -o text
# Returns: Human-readable responsegemini "prompt" -o jsonReturns structured data:
{
"response": "The actual response content",
"stats": {
"models": {
"gemini-2.5-flash": {
"api": {
"totalRequests": 3,
"totalErrors": 0,
"totalLatencyMs": 5000
},
"tokens": {
"prompt": 1500,
"candidates": 500,
"total": 2000,
"cached": 800,
"thoughts": 150,
"tool": 50
}
}
},
"tools": {
"totalCalls": 2,
"totalSuccess": 2,
"totalFail": 0,
"byName": {
"google_web_search": {
"count": 1,
"success": 1,
"durationMs": 3000
}
}
}
}
}Real-time newline-delimited JSON events for monitoring long tasks.
| Model | Use Case | Context |
|---|---|---|
gemini-3-pro |
Complex tasks (default) | 1M tokens |
gemini-2.5-flash |
Quick tasks, lower latency | Large |
gemini-2.5-flash-lite |
Fastest, simplest tasks | Medium |
# Default (Pro)
gemini "complex analysis" -o text
# Flash for speed
gemini "simple task" -m gemini-2.5-flash -o textPriority order (highest first):
/etc/gemini-cli/settings.json(system)~/.gemini/settings.json(user).gemini/settings.json(project)
{
"security": {
"auth": {
"selectedType": "oauth-personal"
}
},
"general": {
"previewFeatures": true,
"vimMode": false,
"checkpointing": true
},
"mcpServers": {}
}Create .gemini/GEMINI.md in project root:
# Project Context
Project description and guidelines.
## Coding Standards
- Standards Gemini should follow
## When Making Changes
- Guidelines for modificationsLike .gitignore, excludes files from context:
node_modules/
dist/
*.log
.env
gemini --list-sessionsOutput:
Available sessions for this project (5):
1. Create task manager (10 minutes ago) [uuid]
2. Review code (20 minutes ago) [uuid]
...
# By index
echo "follow-up question" | gemini -r 1 -o text
# Latest session
echo "continue" | gemini -r latest -o text- 60 requests per minute
- 1000 requests per day
- CLI auto-retries with exponential backoff
- Message:
"quota will reset after Xs" - Typical wait: 1-5 seconds
- Use
gemini-2.5-flashfor simple tasks - Batch operations into single prompts
- Run long tasks in background
In interactive mode, these slash commands are available:
| Command | Purpose |
|---|---|
/help |
Show available commands |
/tools |
List available tools |
/stats |
Show token usage |
/compress |
Summarize context to save tokens |
/restore |
Restore file checkpoints |
/chat save <tag> |
Save conversation |
/chat resume <tag> |
Resume conversation |
/memory show |
Display GEMINI.md context |
/memory refresh |
Reload context files |
echo "What is 2+2?" | gemini -o text
cat file.txt | gemini "summarize this" -o textIn prompts, reference files with @:
gemini "Review @./src/main.js for bugs" -o textIn interactive mode, prefix with !:
> !git status
| Shortcut | Function |
|---|---|
Ctrl+L |
Clear screen |
Ctrl+V |
Paste from clipboard |
Ctrl+Y |
Toggle YOLO mode |
Ctrl+X |
Open in external editor |
| Issue | Solution |
|---|---|
| "API key not found" | Set GEMINI_API_KEY env var |
| "Rate limit exceeded" | Wait for auto-retry or use Flash |
| "Context too large" | Use .geminiignore or be specific |
| "Tool call failed" | Check JSON stats for details |
gemini "prompt" --debug -o textFull error reports saved to:
/var/folders/.../gemini-client-error-*.json