Ever wish you could get AI help right from your terminal? Good news—you can. That’s exactly what the Gemini CLI is built for.
Think of it as your shortcut to Google’s Gemini models, without ever leaving your coding flow.
Whether you’re debugging, writing scripts, or just experimenting, this cheatsheet will walk you through the essentials. Don’t worry—it’s a straightforward process.
Table of Contents
What is Google Gemini CLI?
Gemini is a family of multimodal AI models developed by Google.
“Multimodal” means it can understand and work with different types of information, including text, images, audio, and video. This makes it incredibly versatile.
There are different versions of Gemini, like Gemini Pro and Gemini 2.5 Pro, each with its own strengths.
Gemini CLI is an open-source AI agent that brings the power of Gemini directly into your terminal. It provides lightweight access to Gemini, giving you the most direct path from your prompt to our model.
Why Gemini CLI?
- 🎯 Free tier: 60 requests/min and 1,000 requests/day with personal Google account
- 🧠 Powerful Gemini 2.5 Pro: Access to 1M token context window
- 🔧 Built-in tools: Google Search grounding, file operations, shell commands, web fetching
- 🔌 Extensible: MCP (Model Context Protocol) support for custom integrations
- 💻 Terminal-first: Designed for developers who live in the command line
- 🛡️ Open source: Apache 2.0 licensed
🚀 What You’ll Need
- A working terminal (Linux, macOS, or Windows with WSL).
- Node.js (for npm or npx).
- A Gemini API key from Google AI Studio.
⚙️ Installation Options
You’ve got two simple paths—pick whichever suits you:
See also: Mastering the Linux Command Line — Your Complete Free Training Guide
1. Global Installation (always available):
npm install -g @google/gemini-cli
2. Run Without Installing (quick test):
npx @google/gemini-cli
🔑 Authentication Setup
Before we can start working magic, you’ll need to authenticate with your Gemini API key.
Step 1: Get Your Key
Obtain your API key from Google AI Studio: https://aistudio.google.com/app/apikey
Step 2: Set Your Key (choose one method):
- Option A: Environment Variable Add this line to your shell profile (
~/.bashrc,~/.zshrc, etc.):export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"Restart your shell to make it permanent.
- Option B: Environment File Create a
.envfile inside~/.gemini/for global use (or./.gemini/for a single project):GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
💡 Basic Usage
Ready? Just open your terminal and try these:
Start in current directory
gemini
Include multiple directories
gemini --include-directories ../lib,../docs
Use specific model
gemini -m gemini-2.5-flash
Non-interactive mode for scripts
Get a simple text response:
gemini -p "Explain the architecture of this codebase"
For more advanced scripting, including how to parse JSON and handle errors, use the --output-format json flag to get structured output:
gemini -p "Explain the architecture of this codebase" --output-format json
Quick Examples
Start a new project
cd new-project/
gemini
> Write me a Discord bot that answers questions using a FAQ.md file I will provide
Analyze existing code
git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
gemini
Give me a summary of all of the changes that went in yesterday
Non-Interactive Mode – get one quick response:
gemini -p "Summarize the main points of the attached file. @./summary.txt"
Pipe Content – feed Gemini input from another command:
echo "Count to 10" | gemini
Sandbox Mode – run tools safely (requires Docker or Podman):
gemini --sandbox -p "your prompt"
✅ That’s it! You’re now ready to bring Gemini into your terminal workflow. Next time you’re stuck, just remember—you don’t need to switch apps. Gemini is right there with you.
Common Flags
| Flag | Alias | Description |
|---|---|---|
--model <model> | -m | Use a specific model. |
--prompt-interactive <prompt> | -i | Start an interactive session with an initial prompt. |
--debug | -d | Enable debug output. |
--yolo | Auto-approve all tool calls. | |
--checkpointing | Save a project snapshot before file modifications. |
⚙️ Configuration
Here we’ll introduce three important files that shape how the project works:
🛠 settings.json
Think of this as the “control panel” for your project. It defines how tools or extensions behave—like preferences and configuration switches that shape your development environment.
📖 GEMINI.md
This is your handbook. It usually explains the purpose of the project, how to use the Gemini CLI, and may include setup steps, usage notes, or best practices. It’s where you go to understand why and how things work.
🔑 .env
This file is all about secrets and environment-specific values—like API keys, tokens, or database URLs. It keeps sensitive details out of the code while still making them available when the app runs.
Settings (settings.json)
The settings.json file in the Gemini CLI is used to store configuration settings that control how the CLI interacts with the Gemini API and other related services.
- Purpose: This is the primary file for persistent configuration of the Gemini CLI’s behavior and features. It’s a JSON file that stores structured settings across various categories (e.g., UI theme, default model, tool behavior, privacy settings, logging).
- Scope: Can exist at system-wide, user-specific, or project-specific levels, with project settings overriding user settings, and user settings overriding system defaults.
- Content Examples:
- “general.vimMode”: true (enables Vim keybindings)
- “model.name“: “gemini-1.5-pro-latest” (sets default AI model)
- “tools.sandbox”: “docker” (enables Docker-based sandboxing)
Customize the CLI by creating a settings.json file in one of these locations, listed by priority:
- Project:
.gemini/settings.json - User:
~/.gemini/settings.json - System:
/etc/gemini-cli/settings.json
Example settings.json:
{
"theme": "GitHub",
"autoAccept": false,
"sandbox": "docker",
"vimMode": true,
"checkpointing": { "enabled": true },
"fileFiltering": { "respectGitIgnore": true },
"usageStatisticsEnabled": true,
"includeDirectories": ["../shared-library", "~/common-utils"],
"chatCompression": { "contextPercentageThreshold": 0.6 }
}
Key Settings:
autoAccept: Auto-approve read-only tool calls.sandbox: Isolate tool execution (e.g.,true,"docker").vimMode: Enable Vim-style editing.checkpointing: Enable the/restorecommand.includeDirectories: Define a multi-directory workspace.
Context (GEMINI.md)
- Purpose: This file provides instructional context or “memory” directly to the Gemini AI model. It’s a Markdown file where you write guidelines, coding standards, project overviews, specific instructions for components, or any other textual information you want the AI to consider during interactions.
- Scope: Loaded hierarchically from global, project root, and sub-directory locations. The AI combines these contexts to form its understanding for a given task.
The Context (GEMINI.md) refers to the conversational memory or state that the Gemini model maintains during an ongoing interaction.
In the context of the Gemini API and how you’d typically interact with it, especially in a chat-like scenario, “context” is crucial for the model to understand and respond coherently to a sequence of turns in a conversation.
Think of it like a human conversation. If you and I are talking, I don’t forget everything we said 30 seconds ago. That shared memory allows us to have a meaningful discussion. Context (GEMINI.md) is the digital equivalent of that shared memory for the AI.
Provide project-specific instructions to the model using GEMINI.md files.
Use /init to generate a starter file. The CLI loads these files hierarchically, allowing for general and specific contexts. You can see the combined context with /memory show.
Organize your context by importing other Markdown files using @file.md.
Example GEMINI.md:
# Main Project Context: My Awesome App
## General Instructions
- All Python code must be PEP 8 compliant.
## Component-Specific Style Guides
@./src/frontend/react-style-guide.md
@./src/backend/fastapi-style-guide.md
Ignoring Files (.geminiignore)
Create a .geminiignore file in your project’s root to exclude files and directories from Gemini’s tools, similar to .gitignore.
Example .geminiignore:
/backups/
*.log
secret-config.json
🛠️ Working with Tools
Built-in Tools
- File System:
list_directory,glob,read_file,write_file,replace,search_file_content - Shell: Executes shell commands. Use with caution.
- Web:
google_web_search,web_fetch - Memory:
save_memoryto recall information across sessions.
Custom Tools via MCP Servers
Extend the CLI with your own tools by running Model Context Protocol (MCP) servers.
Manage them in settings.json or with gemini mcp commands. This allows for features like OAuth 2.0 support and returning rich content like images.
> @github List my open pull requests
> @slack Send a summary of today's commits to #dev channel
> @database Run a query to find inactive users
See the MCP Server Integration guide for setup instructions.
⚡ Core Commands
Slash Commands (/)
| Command | Description |
|---|---|
/help | Display help information and available commands. |
/clear | Clear the terminal screen and context. |
/copy | Copy the last response to the clipboard. |
/compress | Replace the chat context with a summary to save tokens. |
/stats | Show session token usage. |
/memory show | Show the combined context from GEMINI.md files. |
/memory refresh | Reload all GEMINI.md files. |
/chat save <tag> | Save the current conversation. |
/chat resume <tag> | Resume a saved conversation. |
/chat list | List saved conversations. |
/restore | List or restore a project checkpoint. |
/theme | Change the CLI’s visual theme. |
/settings | Open an editor for your settings.json file. |
/init | Generate a GEMINI.md context file for your project. |
/quit | Exit the Gemini CLI. |
Context Commands (@)
Reference files, directories, and even multimedia in your prompt.
- Include a single file:
> Explain this code to me. @./src/main.js - Include an image:
> Describe this screenshot. @./ux-mockup.png - Include a directory:
> Refactor the code in this directory. @./src/
Shell Commands (!)
- Run a single command:
> !git status - Toggle Shell Mode: Enter
!by itself to switch to a persistent shell mode.
Keyboard Shortcuts
| Shortcut | Description |
|---|---|
Ctrl+L | Clear the screen. |
Ctrl+V | Paste text or an image from the clipboard. |
Ctrl+Y | Toggle YOLO mode (auto-approve tool calls). |
Ctrl+X | Open the current prompt in an external editor. |
General
| Shortcut | Description |
|---|---|
Esc | Close dialogs and suggestions. |
Ctrl+C | Cancel the ongoing request and clear the input. Press twice to exit the application. |
Ctrl+D | Exit the application if the input is empty. Press twice to confirm. |
Ctrl+L | Clear the screen. |
Ctrl+O | Toggle the display of the debug console. |
Ctrl+S | Allows long responses to print fully, disabling truncation. Use your terminal’s scrollback to view the entire output. |
Ctrl+T | Toggle the display of tool descriptions. |
Ctrl+Y | Toggle auto-approval (YOLO mode) for all tool calls. |
Input Prompt
| Shortcut | Description |
|---|---|
! | Toggle shell mode when the input is empty. |
\\\\ (at end of line) + Enter | Insert a newline. |
Down Arrow | Navigate down through the input history. |
Enter | Submit the current prompt. |
Meta+Delete / Ctrl+Delete | Delete the word to the right of the cursor. |
Tab | Autocomplete the current suggestion if one exists. |
Up Arrow | Navigate up through the input history. |
Ctrl+A / Home | Move the cursor to the beginning of the line. |
Ctrl+B / Left Arrow | Move the cursor one character to the left. |
Ctrl+C | Clear the input prompt |
Esc (double press) | Clear the input prompt. |
Ctrl+D / Delete | Delete the character to the right of the cursor. |
Ctrl+E / End | Move the cursor to the end of the line. |
Ctrl+F / Right Arrow | Move the cursor one character to the right. |
Ctrl+H / Backspace | Delete the character to the left of the cursor. |
Ctrl+K | Delete from the cursor to the end of the line. |
Ctrl+Left Arrow / Meta+Left Arrow / Meta+B | Move the cursor one word to the left. |
Ctrl+N | Navigate down through the input history. |
Ctrl+P | Navigate up through the input history. |
Ctrl+Right Arrow / Meta+Right Arrow / Meta+F | Move the cursor one word to the right. |
Ctrl+U | Delete from the cursor to the beginning of the line. |
Ctrl+V | Paste clipboard content. If the clipboard contains an image, it will be saved and a reference to it will be inserted in the prompt. |
Ctrl+W / Meta+Backspace / Ctrl+Backspace | Delete the word to the left of the cursor. |
Ctrl+X / Meta+Enter | Open the current input in an external editor. |
Suggestions
| Shortcut | Description |
|---|---|
Down Arrow | Navigate down through the suggestions. |
Tab / Enter | Accept the selected suggestion. |
Up Arrow | Navigate up through the suggestions. |
Radio Button Select
| Shortcut | Description |
|---|---|
Down Arrow / j | Move selection down. |
Enter | Confirm selection. |
Up Arrow / k | Move selection up. |
1-9 | Select an item by its number. |
| (multi-digit) | For items with numbers greater than 9, press the digits in quick succession to select the corresponding item. |
LEVEL 2: INTERMEDIATE COMMANDS
File management and basic customization
You’ve nailed the basics — awesome job! 🎉
Now let’s move up a level. Here you’ll learn how to manage files, switch models, and even give Gemini a memory. Don’t worry, it’s still a straightforward process.
📂 File Management
Want Gemini to work with your project files? Just point it in the right direction:
/tools
read_folder <directory> # Read an entire folder
@src/my_project/ # Load a whole project directory
@path/to/file.txt # Open a specific file
@My\\ Documents/file.txt # Handle spaces in paths
👉 This makes it super easy to analyze projects without endless copy-pasting.
💬 Conversation Management
Sometimes you’ll want to pause a session and come back later. That’s where these come in:
/chat save <tag> # Save the current conversation
/chat resume <tag> # Resume a saved one
/chat list # See what you’ve saved
/compress # Summarize long chats into a digest
✅ No more losing track — your chats stay organized.
⚡ Model Configuration
Switching brains is as easy as flipping a switch:
--model # Show the current model
--model gemini-1.5-flash # Fastest option (quick replies)
--model gemini-1.5-pro # Most capable
--model gemini-1.5-pro-002 # Latest Pro version
Not sure which to pick? Start with Flash for speed and swap to Pro when you need depth.
🧠 Memory Management
Think of this as Gemini’s personal notebook:
/memory show # Show what Gemini remembers
/memory add <text> # Add custom notes
/memory refresh # Reload GEMINI.md files
👉 Perfect for keeping project rules or reminders right where Gemini can see them.
🔴 LEVEL 3: ADVANCED COMMANDS
Configuration, context, and power features
Ready to push things further? 🚀
This level is about automation, monitoring, and fine-tuning Gemini’s behavior.
🏃 Execution Methods
gemini -p "your prompt here" # Run a quick prompt
gemini -y # Auto-confirm everything (YOLO mode)
gemini --sandbox # Run in a safe sandbox
gemini --checkpointing # Enable checkpoints
⚠️ Use -y carefully — it skips confirmations!
📊 Statistics & Monitoring
Keep an eye on what’s happening under the hood:
/stats # Show session statistics
/stats model # Model usage stats
/stats tools # Tool usage stats
👉 Great for tracking performance or debugging.
🖥️ Shell Integration
Need to run a quick command without leaving Gemini? You can!
!<shell_command> # Run shell command
!ls -la # List files
!git status # Check Git status
! # Toggle shell mode
✅ This makes Gemini feel like part of your terminal workflow.
📂 Context Management
Easily bring files or folders into a prompt:
@<path_to_file> # Add file content
@<directory> # Add whole directory
@README.md # Example: README file
@src/myFile.ts # Example: specific code file
@folder/ # Example: whole folder
👉 Super handy for big projects where context matters.
🟣 LEVEL 4: EXPERT COMMANDS
MCP servers, automation, and integrations
You’re doing great — let’s unlock the pro tools now. These commands expand Gemini with servers, sandboxes, and advanced execution.
🛠 MCP Server Management
/mcp list # List MCP servers
/mcp desc # Show detailed descriptions
/mcp nodesc # Hide descriptions
/mcp schema # Show full JSON schema
✨ And that’s it! You’ve gone from beginner to master of the Gemini CLI. With these commands, you can customize, automate, and extend Gemini to fit almost any workflow.
