Google Gemini CLI Cheatsheet

The Gemini CLI is an open-source AI agent that brings the power of Gemini directly into your terminal, allowing you to perform a wide range of tasks such as coding, problem-solving, and task management using natural language. This cheatsheet provides a quick reference for installing, configuring, and using the Gemini CLI, with a focus on users authenticating via a Gemini API key.

🚀 Getting Started

Installation

Install Globally:

npm install -g @google/gemini-cli

Run without Installing:

npx @google/gemini-cli

Authentication with a Gemini API Key

Authenticate with an API key before first use. See the authentication guide for details.

1. Get Your Key: Get an API key from Google AI Studio.

2. Set Your Key: Make the key available to the CLI with one of these methods.

   Method 1: Shell Environment Variable Set the GEMINI_API_KEY environment variable. To use it across terminal sessions, add this line to your shell's profile (e.g., ~/.bashrc, ~/.zshrc).

   export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

   Method 2: Environment File Create a .env file in ~/.gemini/ for global use or ./.gemini/ for a specific project. The CLI automatically loads it.

   # In .gemini/.env
   GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
   

Basic Invocation

Interactive Mode (REPL): Start a conversational session.

gemini

Non-Interactive Mode: Pass a prompt and get a single response.

gemini -p "Summarize the main points of the attached file. @./summary.txt"

Piping to the CLI: Pipe content to the CLI.

echo "Count to 10" | gemini

Sandbox Mode: Run tools in a secure sandbox (requires Docker or Podman).

gemini --sandbox -p "your prompt"

Other Flags:

• -m, --model <model>: Use a specific model.
• -d, --debug: Enable debug output.
• --yolo: Auto-approve all tool calls.
• --checkpointing: Save a project snapshot before file modifications. Use /restore to revert changes.

Full list of flags.

⚙️ Configuration

Settings Files (settings.json)

Customize the CLI by creating a settings.json file. Settings are applied with the following precedence:

1. Project: .gemini/settings.json (overrides user and system settings).
2. User: ~/.gemini/settings.json (overrides system settings).
3. System: /etc/gemini-cli/settings.json (applies to all users).

Example settings.json:

{
  "theme": "GitHub",
  "autoAccept": false,
  "sandbox": "docker",
  "checkpointing": {
    "enabled": true
  },
  "fileFiltering": {
    "respectGitIgnore": true
  },
  "usageStatisticsEnabled": true
}

• autoAccept: Auto-approve safe, read-only tool calls.
• sandbox: Isolate tool execution (e.g., true, "docker", or "podman").
• checkpointing: Enable the /restore command to undo file changes.
• usageStatisticsEnabled: Set to false to disable usage statistics.

All details in the configuration guide.

Context Files (GEMINI.md)

Use GEMINI.md files to provide instructions to the model and tailor it to your project.

Hierarchical Loading: The CLI combines GEMINI.md files from multiple locations. More specific files override general ones. The loading order is:

1. Global Context: ~/.gemini/GEMINI.md (for instructions that apply to all your projects).
2. Project/Ancestor Context: The CLI searches from your current directory up to the project root for GEMINI.md files.
3. Sub-directory Context: The CLI also scans subdirectories for GEMINI.md files, allowing for component-specific instructions.

Use /memory show to see the final combined context being sent to the model.

Modularizing Context with Imports: You can organize GEMINI.md files by importing other Markdown files with the @file.md syntax. This only supports .md files.

Example GEMINI.md using imports:

# Main Project Context: My Awesome App
 
## General Instructions
- All Python code must be PEP 8 compliant.
- Use 2-space indentation for all new files.
 
## Component-Specific Style Guides
@./src/frontend/react-style-guide.md
@./src/backend/fastapi-style-guide.md

More in the Full context file guide.

🛠️ Working with Tools

Some Built-in Tools

• File System Tools: For interacting with files and directories - list_directory(path="/src"), glob(pattern="src/**/*.ts"), read_file(path="/path/to/file.txt"), write_file(file_path="/path/to/new_file.js", content="console.log('hello');"), replace(file_path="...", old_string="...", new_string="..."), search_file_content(pattern="myFunction", include="*.js")
• Shell Tool: Executes shell commands. Use with caution. To restrict commands, use excludeTools in settings.json. For example: "excludeTools": ["run_shell_command(rm)"]
• Web Tools: For retrieving content and searching online - google_web_search(query="Gemini API rate limits"), web_fetch(prompt="Summarize https://my-blog.com/article")
• Memory Tool: For saving and recalling information across sessions - save_memory(fact="My preferred CSS framework is Tailwind CSS.")

Custom Tools via MCP Servers

Extend the CLI with your own tools by running Model Context Protocol (MCP) servers and configuring them in any settings.json.

Example mcpServers configuration:

"mcpServers": {
  "myPythonServer": {
    "command": "python",
    "args": ["-m", "my_mcp_server", "--port", "8080"],
    "cwd": "./mcp_tools/python",
    "env": {
      "DATABASE_URL": "$DB_URL_FROM_ENV"
    },
    "timeout": 15000,
    "trust": false,
    "includeTools": ["safe_tool_1", "safe_tool_2"],
    "excludeTools": ["dangerous_tool"]
  }
}

Transport (choose one):

• command, args, cwd: Launch a local process via Stdio
• url: SSE endpoint (e.g., "http://localhost:8080/sse")
• httpUrl: HTTP streaming endpoint (e.g., "http://localhost:8080/mcp")

Optional:

• env: Environment variables. Use $VAR_NAME syntax to reference shell variables.
• headers: Key-value map of HTTP headers for url/httpUrl transports.
• timeout: Request timeout in milliseconds (default: 10 minutes).
• trust: Bypass all tool confirmations for this server.
• includeTools/excludeTools: Whitelist/blacklist specific tools. excludeTools takes precedence.

Using OAuth take a look at mcp-server.md

⚡ Core Commands

Helpful Slash Commands (/)

Context Commands (@)

Reference files or directories in your prompt. The CLI respects .gitignore by default.

Include a single file:

> Explain this code to me. @./src/main.js

Include a whole directory (recursively):

> Refactor the code in this directory to use async/await. @./src/

Shell Commands (!)

Run commands shell commands directly in the CLI.

Run a single command:

> !git status

Toggle Shell Mode: Enter ! by itself to switch to a persistent shell mode. Type ! again to exit.

✨ Advanced Features

Custom Commands

Create custom commands using TOML files. Store them in ~/.gemini/commands/ (global) or <project>/.gemini/commands/ (project-specific). See the custom commands guide for more details.

Example: ~/.gemini/commands/test/gen.toml

# Invoked as: /test:gen "Create a test for the login button"
description = "Generates a unit test based on a description."
prompt = """
You are an expert test engineer. Based on the following requirement, please write a comprehensive unit test using the Jest testing framework.
 
Requirement: {{args}}
"""

Extensions

Create extensions to add functionality. Place them in <workspace>/.gemini/extensions/ or ~/.gemini/extensions/. Each extension is a directory with a gemini-extension.json file that can configure MCP servers, tools, and context files. For more details, see the extensions guide.

For example:

<workspace>/.gemini/extensions/my-extension/gemini-extension.json

{
  "name": "my-extension",
  "version": "1.0.0",
  "mcpServers": {
    "my-server": {
      "command": "node my-server.js"
    }
  },
  "contextFileName": "GEMINI.md",
  "excludeTools": ["run_shell_command"]
}

Checkpointing & Restore

When checkpointing is on, the CLI saves a project snapshot before tools modify files.

Enable in settings.json or with a flag:

gemini --checkpointing

Restore to a previous state:

# List available checkpoints
/restore
 
# Restore a specific checkpoint
/restore <checkpoint_file_name>

Thanks for reading! If you have any questions or feedback, please let me know on Twitter or LinkedIn.