Gemini CLI Cheatsheet

Q: How do I install and authenticate Gemini CLI?

Install with `npm install -g @google/gemini-cli` or run directly with `npx @google/gemini-cli`. Authenticate via 'Sign in with Google' (recommended) or set `export GEMINI_API_KEY="YOUR_KEY"` and select 'Use Gemini API key' on first launch. For enterprise: use Vertex AI with service accounts.

Q: How do I use Gemini CLI non-interactively?

Use `gemini -p "your prompt"` for a single response. Pipe input: `cat file.txt | gemini`. For JSON output (scripting): `gemini -p "prompt" --output-format json`. For real-time streaming: `gemini -p "prompt" --output-format stream-json`.

Q: What is GEMINI.md and how do I use it?

GEMINI.md is a context file that provides instructions to the model. Generate one for your project with `/init` in the CLI. Place at `~/.gemini/GEMINI.md` (global) or project root for project-specific context. Use `@file.md` syntax to import modular instructions. View combined context with `/memory show`.

Q: How do I use MCP servers with Gemini CLI?

Configure MCP servers in `settings.json` under `mcpServers` or use the `/mcp` commands. List with `/mcp list`, view details with `/mcp desc`, enable/disable with `/mcp enable ` / `/mcp disable `, and reload after config changes with `/mcp reload`.

Q: How do I save and resume sessions?

Gemini CLI auto-saves all sessions. Save a checkpoint: `/resume save my-tag`. List checkpoints: `/resume list`. Resume: `/resume resume my-tag`. Export: `/resume share session.md`. Delete: `/resume delete my-tag`. For API debugging: `/resume debug`.

Gemini CLI is Google's open-source AI agent that brings the power of Gemini directly into your terminal. Supports interactive chat, code generation and understanding, file operations, shell commands, web search, MCP protocol extensions, and subagent orchestration. Free tier: 60 requests/min, 1,000 requests/day.

Updated: 2026-07-20·68 commands

Quick Start

``bash # Install npm install -g @google/gemini-cli

# Or run without installing npx @google/gemini-cli

# Start interactive session gemini

# Non-interactive mode gemini -p "What is the capital of Japan?"

# Use a specific model gemini -m gemini-2.5-flash -p "Write a Python script"

# Pipe input cat README.md | gemini`

`Installation Options`

Method

Command


npm (global) npm install -g @google/gemini-cli
npx (no install) npx @google/gemini-cli
Homebrew (macOS/Linux) brew install gemini-cli
MacPorts (macOS) sudo port install gemini-cli
Preview channel npm install -g @google/gemini-cli@preview
Nightly channel npm install -g @google/gemini-cli@nightly

Authentication
Method Setup Best For

Sign in with Google Run gemini, choose Sign in with Google Individuals, free tier
Gemini API Key export GEMINI_API_KEY="YOUR_KEY" Developers, headless
Vertex AI (ADC) gcloud auth application-default login + export GOOGLE_CLOUD_PROJECT="..." Enterprise teams
Vertex AI (SA Key) export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json" CI/CD, non-interactive

### Environment Persistence

Add to ~/.bashrc or ~/.zshrc:`bash export GEMINI_API_KEY="YOUR_KEY" # Or for Vertex AI: export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID" export GOOGLE_CLOUD_LOCATION="us-central1"`

Or use a .env file at ~/.gemini/.env (global) or ./.gemini/.env (project).

`Command-Line Flags`

Flag

Description

Example


-m, --model Specify Gemini model gemini -m gemini-2.5-pro -p "..."
-p, --prompt Non-interactive prompt gemini -p "Explain this code"
-i, --prompt-interactive Start interactive with initial prompt gemini -i "Refactor this module"
-d, --debug Enable debug mode gemini -d
--sandbox Isolate tool execution (Docker/Podman) gemini --sandbox -p "rm test"
--yolo Auto-approve all tool calls gemini --yolo -p "Deploy"
--output-format json JSON output (scripting) gemini -p "..." --output-format json
--output-format stream-json Real-time JSON events gemini -p "..." --output-format stream-json
--include-directories Multi-directory workspace gemini --include-directories ../lib,../docs
--checkpointing Enable session checkpointing gemini --checkpointing

Configuration

### Settings Files (settings.json)

Precedence (highest to lowest): 1. Command-line arguments 2. Environment variables (including.envfiles) 3. System settings file —/etc/gemini-cli/settings.json4. Project settings file —.gemini/settings.json5. User settings file —~/.gemini/settings.json6. System defaults file —/etc/gemini-cli/system-defaults.json

### Common Settings

`json { "theme": "GitHub", "vimMode": true, "autoAccept": false, "sandbox": "docker", "checkpointing": { "enabled": true }, "general": { "preferredEditor": "vscode", "defaultApprovalMode": "default", "plan": { "enabled": true } } }`

### Context Files (GEMINI.md)

GEMINI.md files provide hierarchical context — more specific files override general ones: 1. Global:~/.gemini/GEMINI.md2. Project:/.gemini/GEMINI.md3. Sub-directory: Scanned for component-specific instructions

Generate starter: /init (inside CLI). Use @file.mdfor modular imports. View combined context:/memory show.

### Ignoring Files (.geminiignore)

Place .geminiignore in project root (syntax similar to .gitignore):`gitignore # .geminiignore /backups/ *.log secret-config.json`

`Slash Commands Reference`

### Session & Chat

Command

Description


/help or /? Display help
/clear Clear screen (or Ctrl+L)
/compress Summarize chat context to save tokens
/copy Copy last output to clipboard
/quit or /exit Exit CLI
/quit --delete Exit and delete session data
/rewind Navigate backward through conversation (Esc Esc shortcut)

### Checkpoints & Session Management
Command Description

/resume list List auto-saved sessions
/resume save Save checkpoint with tag
/resume resume Resume saved session
/resume delete Delete checkpoint
/resume share [filename] Export as Markdown/JSON
/resume debug Export API request JSON
/restore Undo file changes from tool execution

### Model & Generation
Command Description

/model set  [--persist] Switch model (optional persist)
/model manage Open model config dialog
/plan Switch to Plan Mode (read-only)
/init Generate GEMINI.md context file
/memory show Show combined context
/memory list List GEMINI.md files in use
/memory refresh Reload context files
/stats Session statistics
/stats model Token/quota usage stats
/stats tools Tool usage stats

### Agents & MCP
Command Description

/agents list List all subagents
/agents enable Enable subagent
/agents disable Disable subagent
/agents config Configure subagent
/agents reload Rescan agents directories
/mcp list List MCP servers/tools
/mcp desc List MCP with descriptions
/mcp enable Enable MCP server
/mcp disable Disable MCP server
/mcp reload Reload MCP servers
/mcp schema List MCP with schemas
/mcp auth Initiate MCP OAuth flow

### Extensions & Custom Commands
Command Description

/extensions list List installed extensions
/extensions install Install extension from git
/extensions update Update extension
/extensions uninstall Uninstall extension
/commands list List custom commands
/commands reload Reload custom commands

### Configuration & Tools
Command Description

/settings Open settings editor
/auth Change auth method
/theme Change visual theme
/vim Toggle vim mode
/editor Select preferred editor
/directory add Add workspace directory
/directory show Show workspace dirs
/tools List available tools
/tools desc List tools with descriptions
/permissions trust Trust directory
/setup-github Setup GitHub Actions CI

### System
Command Description

/about Show version info
/bug File a bug report
/docs Open docs in browser
/upgrade Upgrade to Code Assist
/hooks list List lifecycle hooks
/privacy Show privacy notice
/shells Toggle background shells view
/terminal-setup Configure multiline keybindings

Configuration File Examples

### Minimal .gemini/settings.json

`json { "theme": "GitHub Dark", "vimMode": false, "autoAccept": true, "general": { "preferredEditor": "cursor" }, "checkpointing": { "enabled": true } }`

### MCP Server Config

`json { "mcpServers": { "my-tools": { "command": "node", "args": ["path/to/mcp-server.js"], "env": { "API_KEY": "$MY_API_TOKEN" } } } }`

`Built-in Tools`

Gemini CLI includes these built-in capabilities:

Setup & Auth(6)

Command	Level	Example
`npm install -g @google/gemini-cli` Install Gemini CLI globally	Basic	`npm install -g @google/gemini-cli`
`npx @google/gemini-cli` Run Gemini CLI directly without installation	Basic	`npx @google/gemini-cli`
`brew install gemini-cli` Install Gemini CLI via Homebrew	Basic	`brew install gemini-cli`
`export GEMINI_API_KEY="YOUR_KEY"` Set Gemini API key environment variable	Basic	`export GEMINI_API_KEY="AIza..."`
`export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"` Set Google Cloud project ID (for Vertex AI auth)	Intermediate	`export GOOGLE_CLOUD_PROJECT="my-gemini-project"`
`export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"` Set service account JSON key path (Vertex AI service account auth)	Intermediate	`export GOOGLE_APPLICATION_CREDENTIALS="/home/user/sa-key.json"`

Basic Usage(16)

Command	Level	Example
`gemini` Start interactive Gemini CLI session (default mode)	Basic	`gemini`
`gemini -p "prompt"` Run in non-interactive mode with a single prompt	Basic	`gemini -p "Explain the architecture of this project"`
`gemini -m gemini-2.5-flash` Specify Gemini model to use	Basic	`gemini -m gemini-2.5-flash`
`gemini --include-directories ../lib,../docs` Include multiple directories in workspace	Intermediate	`gemini --include-directories ../shared,../docs`
`gemini --sandbox -p "prompt"` Run in sandboxed environment (requires Docker/Podman)	Intermediate	`gemini --sandbox -p "Run make test"`
`gemini --output-format json` Output in JSON format (for scripting)	Intermediate	`gemini -p "List all functions" --output-format json`
`gemini --output-format stream-json` Output as real-time event stream JSON	Intermediate	`gemini -p "Run tests" --output-format stream-json`
`gemini --yolo` Auto-approve all tool calls (no confirmation)	Expert	`gemini --yolo -p "Deploy the app"`
`gemini -d` Enable debug mode	Intermediate	`gemini -d`
`gemini -i "initial prompt"` Start interactive mode with an initial prompt	Basic	`gemini -i "Help me refactor this module"`
`echo "Count to 10" \| gemini` Pipe input to Gemini CLI	Basic	`cat README.md \| gemini`
`/help` Display built-in help	Basic	`/help`
`/clear` Clear terminal screen (Ctrl+L shortcut)	Basic	`/clear`
`/about` Show version info	Basic	`/about`
`/quit` Exit the CLI	Basic	`/quit`
`/quit --delete` Exit and permanently delete session data	Intermediate	`/quit --delete`

Generation(12)

Command	Level	Example
`/init` Analyze current directory and generate a tailored GEMINI.md context file	Basic	`/init`
`/model set gemini-2.5-pro [--persist]` Switch model and optionally persist the setting	Basic	`/model set gemini-2.5-pro --persist`
`/model manage` Open model configuration dialog	Basic	`/model manage`
`/compress` Replace chat context with a summary to save tokens	Intermediate	`/compress`
`/plan` Switch to Plan Mode (read-only)	Basic	`/plan`
`/memory show` Display full concatenated GEMINI.md context content	Basic	`/memory show`
`/memory list` List all GEMINI.md file paths in use	Basic	`/memory list`
`/memory refresh` Reload all GEMINI.md context files	Basic	`/memory refresh`
`/stats` Show current session statistics (duration, tool calls, etc.)	Basic	`/stats`
`/stats model` Show model token usage and quota stats	Intermediate	`/stats model`
`/stats tools` Show tool usage frequency statistics	Intermediate	`/stats tools`
`/copy` Copy last CLI output to clipboard	Basic	`/copy`

Chat & Stream(7)

Command	Level	Example
`/resume list` List auto-saved session history	Basic	`/resume list`
`/resume save <tag>` Create a checkpoint tag for the current session	Basic	`/resume save before-refactor`
`/resume resume <tag>` Resume a previously saved session	Basic	`/resume resume before-refactor`
`/resume delete <tag>` Delete a saved checkpoint	Basic	`/resume delete stale-checkpoint`
`/resume share <filename>` Export session to Markdown or JSON file	Intermediate	`/resume share session-summary.md`
`/resume debug` Export most recent API request as JSON payload	Expert	`/resume debug`
`/rewind` Navigate backward through conversation history	Basic	`/rewind`

Configuration(10)

Command	Level	Example
`/editor` Open editor selection dialog	Basic	`/editor`
`/settings` Open settings editor (settings.json)	Basic	`/settings`
`/auth` Change authentication method	Basic	`/auth`
`/theme` Change visual theme	Basic	`/theme`
`/vim` Toggle vim mode on/off	Intermediate	`/vim`
`/directory add <path>` Add a workspace directory	Intermediate	`/directory add ../shared-lib`
`/directory show` Show all added workspace directories	Basic	`/directory show`
`/commands list` List all custom slash commands	Intermediate	`/commands list`
`/commands reload` Reload custom commands without restarting	Intermediate	`/commands reload`
`/permissions trust <path>` Trust a directory for tool access	Intermediate	`/permissions trust /home/user/projects`

Model Management(16)

Command	Level	Example
`/agents list` List all subagents (built-in, local, remote)	Intermediate	`/agents list`
`/agents enable <name>` Enable a specific subagent	Intermediate	`/agents enable code-reviewer`
`/agents disable <name>` Disable a specific subagent	Intermediate	`/agents disable code-reviewer`
`/agents config <name>` Configure subagent (model, temperature, limits)	Expert	`/agents config code-reviewer`
`/agents reload` Rescan ~/.gemini/agents and .gemini/agents	Intermediate	`/agents reload`
`/mcp list` List all MCP servers and tools	Intermediate	`/mcp list`
`/mcp desc` List MCP servers with descriptions	Intermediate	`/mcp desc`
`/mcp enable <name>` Enable a specific MCP server	Intermediate	`/mcp enable my-tools`
`/mcp disable <name>` Disable a specific MCP server	Intermediate	`/mcp disable my-tools`
`/mcp reload` Reload MCP servers	Intermediate	`/mcp reload`
`/mcp schema` List MCP servers with descriptions and JSON Schemas	Expert	`/mcp schema`
`/extensions list` List installed extensions	Intermediate	`/extensions list`
`/extensions install <repo>` Install extension from git repo	Intermediate	`/extensions install https://github.com/user/my-extension`
`/tools` List all available tools	Basic	`/tools`
`/tools desc` List tools with descriptions	Basic	`/tools desc`
`/setup-github` Set up GitHub Actions automation (issue triage/PR review)	Intermediate	`/setup-github`

File Management(1)

Command	Level	Example
`/restore` Restore project files to state before tool execution	Intermediate	`/restore`

FAQ

How do I install and authenticate Gemini CLI?

How do I use Gemini CLI non-interactively?

What is GEMINI.md and how do I use it?

How do I use MCP servers with Gemini CLI?

How do I save and resume sessions?

This cheatsheet is compiled from official tool documentation. Last updated: 2026-07-20.

File System	list_directory`,` glob`,` read_file`,` write_file`,` replace`,` search_file_content
Shell	run_shell_command `(executes shell commands — restrict with` excludeTools `in settings)`
Web	google_web_search`,` web_fetch
Memory	save_memory(fact="...") `— persist information across sessions`

npm (global)	npm install -g @google/gemini-cli
npx (no install)	npx @google/gemini-cli
Homebrew (macOS/Linux)	brew install gemini-cli
MacPorts (macOS)	sudo port install gemini-cli
Preview channel	npm install -g @google/gemini-cli@preview
Nightly channel	npm install -g @google/gemini-cli@nightly

Sign in with Google	Run gemini`, choose Sign in with Google`	Individuals, free tier
Gemini API Key	export GEMINI_API_KEY="YOUR_KEY"	Developers, headless
Vertex AI (ADC)	gcloud auth application-default login `+` export GOOGLE_CLOUD_PROJECT="..."	Enterprise teams
Vertex AI (SA Key)	export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"	CI/CD, non-interactive

-m, --model	Specify Gemini model	gemini -m gemini-2.5-pro -p "..."
-p, --prompt	Non-interactive prompt	gemini -p "Explain this code"
-i, --prompt-interactive	Start interactive with initial prompt	gemini -i "Refactor this module"
-d, --debug	Enable debug mode	gemini -d
--sandbox	Isolate tool execution (Docker/Podman)	gemini --sandbox -p "rm test"
--yolo	Auto-approve all tool calls	gemini --yolo -p "Deploy"
--output-format json	JSON output (scripting)	gemini -p "..." --output-format json
--output-format stream-json	Real-time JSON events	gemini -p "..." --output-format stream-json
--include-directories	Multi-directory workspace	gemini --include-directories ../lib,../docs
--checkpointing	Enable session checkpointing	gemini --checkpointing

/help `or` /?	Display help
/clear	Clear screen (or Ctrl+L`)`
/compress	Summarize chat context to save tokens
/copy	Copy last output to clipboard
/quit `or` /exit	Exit CLI
/quit --delete	Exit and delete session data
/rewind	Navigate backward through conversation (Esc Esc `shortcut)`

/resume list	List auto-saved sessions
/resume save	Save checkpoint with tag
/resume resume	Resume saved session
/resume delete	Delete checkpoint
/resume share [filename]	Export as Markdown/JSON
/resume debug	Export API request JSON
/restore	Undo file changes from tool execution

/model set [--persist]	Switch model (optional persist)
/model manage	Open model config dialog
/plan	Switch to Plan Mode (read-only)
/init	Generate GEMINI.md context file
/memory show	Show combined context
/memory list	List GEMINI.md files in use
/memory refresh	Reload context files
/stats	Session statistics
/stats model	Token/quota usage stats
/stats tools	Tool usage stats

/agents list	List all subagents
/agents enable	Enable subagent
/agents disable	Disable subagent
/agents config	Configure subagent
/agents reload	Rescan agents directories
/mcp list	List MCP servers/tools
/mcp desc	List MCP with descriptions
/mcp enable	Enable MCP server
/mcp disable	Disable MCP server
/mcp reload	Reload MCP servers
/mcp schema	List MCP with schemas
/mcp auth	Initiate MCP OAuth flow

/extensions list	List installed extensions
/extensions install	Install extension from git
/extensions update	Update extension
/extensions uninstall	Uninstall extension
/commands list	List custom commands
/commands reload	Reload custom commands

/settings	Open settings editor
/auth	Change auth method
/theme	Change visual theme
/vim	Toggle vim mode
/editor	Select preferred editor
/directory add	Add workspace directory
/directory show	Show workspace dirs
/tools	List available tools
/tools desc	List tools with descriptions
/permissions trust	Trust directory
/setup-github	Setup GitHub Actions CI

/about	Show version info
/bug	File a bug report
/docs	Open docs in browser
/upgrade	Upgrade to Code Assist
/hooks list	List lifecycle hooks
/privacy	Show privacy notice
/shells	Toggle background shells view
/terminal-setup	Configure multiline keybindings

Gemini CLI Cheatsheet

Quick Start

Installation Options

Authentication

Command-Line Flags

Configuration

Slash Commands Reference

Configuration File Examples

Built-in Tools

Tips & Tricks