{ "@context": "https://schema.org", "@id": "https://aggr.aymericbeaumet.com/items/philschmid-de/2025-07-24-google-gemini-cli-cheatsheet/#webpage", "@type": [ "WebPage", "ArchiveComponent" ], "articleBody": "The [Gemini CLI](https://github.com/google-gemini/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.\n\n![Gemini CLI Architecture](https://www.philschmid.de/static/blog/gemini-cli-cheatsheet/architecture.png)\n\n## 🚀 Getting Started\n\n### Installation\n\n**Install Globally:**\n\nBash\n\n```bash\nnpm install -g @google/gemini-cli\n```\n\n**Run without Installing:**\n\nBash\n\n```bash\nnpx @google/gemini-cli\n```\n\n### Authentication with a Gemini API Key\n\nAuthenticate with an API key before first use. See the [authentication guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/authentication.md) for details.\n\n1. **Get Your Key:** Get an API key from [Google AI Studio](https://aistudio.google.com/app/apikey).\n\n2. **Set Your Key:** Make the key available to the CLI with one of these methods.\n\n **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`).\n\n Bash\n\n ```bash\n export GEMINI_API_KEY=\"YOUR_GEMINI_API_KEY\"\n ```\n\n **Method 2: Environment File** Create a `.env` file in `~/.gemini/` for global use or `./.gemini/` for a specific project. The CLI automatically loads it.\n\n ```plaintext\n # In .gemini/.env\n GEMINI_API_KEY=\"YOUR_GEMINI_API_KEY\"\n ```\n\n### Basic Invocation\n\n**Interactive Mode (REPL):** Start a conversational session.\n\nBash\n\n```bash\ngemini\n```\n\n**Non-Interactive Mode:** Pass a prompt and get a single response.\n\nBash\n\n```bash\ngemini -p \"Summarize the main points of the attached file. @./summary.txt\"\n```\n\n**Piping to the CLI:** Pipe content to the CLI.\n\nBash\n\n```bash\necho \"Count to 10\" | gemini\n```\n\n**Sandbox Mode:** Run tools in a secure sandbox (requires Docker or Podman).\n\nBash\n\n```bash\ngemini --sandbox -p \"your prompt\"\n```\n\n**Other Flags:**\n\n- `-m, --model `: Use a specific model.\n- `-i, --prompt-interactive `: Start an interactive session with an initial prompt.\n- `-d, --debug`: Enable debug output.\n- `--yolo`: Auto-approve all tool calls.\n- `--checkpointing`: Save a project snapshot before file modifications. Use `/restore` to revert changes.\n\n[Full list of flags](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md#command-line-arguments).\n\n## ⚙️ Configuration\n\n### Settings Files (`settings.json`)\n\nCustomize the CLI by creating a `settings.json` file. Settings are applied with the following precedence:\n\n1. **Project:** `.gemini/settings.json` (overrides user).\n2. **User:** `~/.gemini/settings.json`\n3. **System:** `/etc/gemini-cli/settings.json` (applies to all users, has highest precedence).\n\n**Example `settings.json`:**\n\nJSON\n\n```json\n{\n \"theme\": \"GitHub\",\n \"autoAccept\": false,\n \"sandbox\": \"docker\",\n \"vimMode\": true,\n \"checkpointing\": { \"enabled\": true },\n \"fileFiltering\": { \"respectGitIgnore\": true },\n \"usageStatisticsEnabled\": true,\n \"includeDirectories\": [\"../shared-library\", \"~/common-utils\"],\n \"chatCompression\": { \"contextPercentageThreshold\": 0.6 },\n \"customThemes\": {\n \"MyCustomTheme\": {\n \"name\": \"MyCustomTheme\", \"type\": \"custom\",\n \"Background\": \"#181818\", \"Foreground\": \"#F8F8F2\",\n \"LightBlue\": \"#82AAFF\", \"AccentBlue\": \"#61AFEF\", \"AccentPurple\": \"#C678DD\",\n \"AccentCyan\": \"#56B6C2\", \"AccentGreen\": \"#98C379\", \"AccentYellow\": \"#E5C07B\",\n \"AccentRed\": \"#E06C75\", \"Comment\": \"#5C6370\", \"Gray\": \"#ABB2BF\"\n }\n }\n}\n```\n\n- `autoAccept`: Auto-approve safe, read-only tool calls.\n- `sandbox`: Isolate tool execution (e.g., `true`, `\"docker\"`, or `\"podman\"`).\n- `vimMode`: Enable Vim-style editing for the input prompt.\n- `checkpointing`: Enable the `/restore` command to undo file changes.\n- `includeDirectories`: Define a multi-directory workspace.\n- `chatCompression`: Configure automatic chat history compression.\n- `customThemes`: Define your own color themes.\n- `usageStatisticsEnabled`: Set to `false` to disable usage statistics.\n\nAll details in the [configuration guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md).\n\n### Context Files (`GEMINI.md`)\n\nUse `GEMINI.md` files to provide instructions to the model and tailor it to your project. Use `/init` to generate a starting `GEMINI.md` file for your project.\n\n**Hierarchical Loading:** The CLI combines `GEMINI.md` files from multiple locations. More specific files override general ones. The loading order is:\n\n1. **Global Context:** `~/.gemini/GEMINI.md` (for instructions that apply to all your projects).\n2. **Project/Ancestor Context:** The CLI searches from your current directory up to the project root for `GEMINI.md` files.\n3. **Sub-directory Context:** The CLI also scans subdirectories for `GEMINI.md` files, allowing for component-specific instructions.\n\nUse `/memory show` to see the final combined context being sent to the model.\n\n**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.\n\n**Example `GEMINI.md` using imports:**\n\nMarkdown\n\n```markdown\n# Main Project Context: My Awesome App\n \n## General Instructions\n- All Python code must be PEP 8 compliant.\n- Use 2-space indentation for all new files.\n \n## Component-Specific Style Guides\n@./src/frontend/react-style-guide.md\n@./src/backend/fastapi-style-guide.md\n```\n\nMore in the [Full context file guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md#context-files-geminimd).\n\n### Ignoring Files with `.geminiignore`\n\nCreate a `.geminiignore` file in your project root to exclude files and directories from Gemini's tools, similar to `.gitignore`.\n\n```plaintext\n# .geminiignore\n/backups/\n*.log\nsecret-config.json\n```\n\n## 🛠️ Working with Tools\n\n### Some Built-in Tools\n\n- **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\")`\n- **Shell Tool:** Executes shell commands. **Use with caution.** To restrict commands, use `excludeTools` in `settings.json`. For example: `\"excludeTools\": [\"run_shell_command(rm)\"]`\n- **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\")`\n- **Memory Tool:** For saving and recalling information across sessions - `save_memory(fact=\"My preferred CSS framework is Tailwind CSS.\")`\n\n### Custom Tools via MCP Servers\n\nExtend the CLI with your own tools by running Model Context Protocol (MCP) servers. Manage servers via `settings.json` or with the `gemini mcp ` commands.\n\n**Capabilities:**\n\n- **OAuth 2.0 Support:** Securely connect to remote servers.\n- **Rich Content Returns:** Tools can return multi-modal content like text and images.\n- **Prompts as Commands:** Expose predefined prompts from your server as new slash commands in the CLI.\n\n**Example `mcpServers` configuration:**\n\nJSON\n\n```json\n\"mcpServers\": {\n \"myPythonServer\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"my_mcp_server\", \"--port\", \"8080\"],\n \"cwd\": \"./mcp_tools/python\",\n \"env\": {\n \"DATABASE_URL\": \"$DB_URL_FROM_ENV\"\n },\n \"timeout\": 15000,\n \"trust\": false,\n \"includeTools\": [\"safe_tool_1\", \"safe_tool_2\"],\n \"excludeTools\": [\"dangerous_tool\"]\n }\n}\n```\n\n**Transport (choose one):**\n\n- `command`, `args`, `cwd`: Launch a local process via Stdio\n- `url`: SSE endpoint (e.g., `\"http://localhost:8080/sse\"`)\n- `httpUrl`: HTTP streaming endpoint (e.g., `\"http://localhost:8080/mcp\"`)\n\n**Optional:**\n\n- `env`: Environment variables. Use `$VAR_NAME` syntax to reference shell variables.\n- `headers`: Key-value map of HTTP headers for `url`/`httpUrl` transports.\n- `timeout`: Request timeout in milliseconds (default: 10 minutes).\n- `trust`: Bypass all tool confirmations for this server.\n- `includeTools`/`excludeTools`: Whitelist/blacklist specific tools. `excludeTools` takes precedence.\n\nUsing OAuth take a look at [mcp-server.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#oauth-support-for-remote-mcp-servers)\n\n## ⚡ Core Commands\n\n### Helpful Slash Commands (`/`)\n\n| Command | Description |\n| -------------------- | ------------------------------------------------------------------------ |\n| `/compress` | Replace the entire chat context with a summary to save tokens. |\n| `/copy` | Copy the last response to the clipboard. |\n| `/mcp` | List configured MCP servers and their available tools. |\n| `/clear` | Clear the terminal screen and context (`Ctrl+L` also works). |\n| `/tools` | List available tools. |\n| `/extensions` | List active extensions. |\n| `/stats` | Show session token usage and savings. |\n| `/memory show` | Show the combined context from all `GEMINI.md` files. |\n| `/memory refresh` | Reload all `GEMINI.md` files. |\n| `/chat save ` | Save the current conversation with a tag. |\n| `/chat resume ` | Resume a saved conversation. |\n| `/chat list` | List saved conversation tags. |\n| `/restore` | List or restore a project state checkpoint. |\n| `/auth` | Change the current authentication method. |\n| `/bug` | File an issue or bug report about the Gemini CLI. |\n| `/help` | Display help information and available commands. |\n| `/theme` | Change the CLI's visual theme. |\n| `/quit` | Exit the Gemini CLI. |\n| `/ide` | Manage integration with your IDE (e.g., `install`, `enable`). |\n| `/settings` | Open a friendly editor to change your `settings.json` file. |\n| `/vim` | Toggle Vim mode for input editing. |\n| `/init` | Generate a starting `GEMINI.md` context file for your project. |\n| `/directory` | Manage directories in a multi-directory workspace (e.g., `add`, `show`). |\n\n### Context Commands (`@`)\n\nReference files or directories in your prompt. The CLI respects `.gitignore` and `.geminiignore`. You can also reference images, PDFs, audio, and video files.\n\n**Include a single file:**\n\n```plaintext\n> Explain this code to me. @./src/main.js\n```\n\n**Include an image:**\n\n```plaintext\n> Describe what you see in this screenshot. @./ux-mockup.png\n```\n\n**Include a whole directory (recursively):**\n\n```plaintext\n> Refactor the code in this directory to use async/await. @./src/\n```\n\n### Shell Commands (`!`)\n\nRun shell commands directly in the CLI.\n\n**Run a single command:**\n\n```plaintext\n> !git status\n```\n\n**Toggle Shell Mode:** Enter `!` by itself to switch to a persistent shell mode. Type `!` again to exit.\n\n### Keyboard Shortcuts\n\n| Shortcut | Description |\n| -------- | ----------------------------------------------- |\n| `Ctrl+L` | Clear the screen. |\n| `Ctrl+V` | Paste text or an image from the clipboard. |\n| `Ctrl+Y` | Toggle YOLO mode (auto-approve all tool calls). |\n| `Ctrl+X` | Open the current prompt in an external editor. |\n\n## ✨ Advanced Features\n\n### IDE Integration (VS Code)\n\nConnect the CLI to VS Code for a more powerful, context-aware experience.\n\n- **Workspace Context:** Automatically gets your recent files, cursor position, and selected text.\n- **Native Diffing:** View and approve code changes directly in your editor's diff viewer.\n- **Commands:** Use `/ide install` to set up and `/ide enable` to connect.\n\n### Custom Commands\n\nCreate custom commands using TOML files. Store them in `~/.gemini/commands/` (global) or `/.gemini/commands/` (project-specific). See the [custom commands guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/commands.md#custom-commands) for more details.\n\n**Example: `~/.gemini/commands/test/gen.toml`**\n\nToml\n\n```toml\n# Invoked as: /test:gen \"Create a test for the login button\"\ndescription = \"Generates a unit test based on a description.\"\nprompt = \"\"\"\nYou are an expert test engineer. Based on the following requirement, please write a comprehensive unit test using the Jest testing framework.\n \nRequirement: {{args}}\n\"\"\"\n```\n\n### Extensions\n\nCreate extensions to add functionality. Place them in `/.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](https://github.com/google-gemini/gemini-cli/blob/main/docs/extension.md).\n\nFor example:\n\n```plaintext\n/.gemini/extensions/my-extension/gemini-extension.json\n```\n\nJSON\n\n```json\n{\n \"name\": \"my-extension\",\n \"version\": \"1.0.0\",\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"node my-server.js\"\n }\n },\n \"contextFileName\": \"GEMINI.md\",\n \"excludeTools\": [\"run_shell_command\"]\n}\n```\n\n### Checkpointing & Restore\n\nWhen `checkpointing` is on, the CLI saves a project snapshot before tools modify files.\n\n**Enable in `settings.json` or with a flag:**\n\nBash\n\n```bash\ngemini --checkpointing\n```\n\n**Restore to a previous state:**\n\nBash\n\n```bash\n# List available checkpoints\n/restore\n \n# Restore a specific checkpoint\n/restore \n```\n\n* * *\n\nThanks for reading! If you have any questions or feedback, please let me know on [Twitter](https://twitter.com/_philschmid) or [LinkedIn](https://www.linkedin.com/in/philipp-schmid-a6a2bb196/).\n", "authors": [], "captured_at": "2026-09-27T19:29:15.293681927+00:00", "category": "programming", "content_html": "

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.

\n

\"Gemini

\n

🚀 Getting Started

\n

Installation

\n

Install Globally:

\n

Bash

\n
npm install -g @google/gemini-cli\n
\n

Run without Installing:

\n

Bash

\n
npx @google/gemini-cli\n
\n

Authentication with a Gemini API Key

\n

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

\n
    \n
  1. \n

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

    \n
    2. \n
  2. \n

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

    \n

    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).

    \n

    Bash

    \n
    export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"\n
    \n

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

    \n
    # In .gemini/.env\nGEMINI_API_KEY="YOUR_GEMINI_API_KEY"\n
    \n
    3. \n
\n

Basic Invocation

\n

Interactive Mode (REPL): Start a conversational session.

\n

Bash

\n
gemini\n
\n

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

\n

Bash

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

Piping to the CLI: Pipe content to the CLI.

\n

Bash

\n
echo "Count to 10" | gemini\n
\n

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

\n

Bash

\n
gemini --sandbox -p "your prompt"\n
\n

Other Flags:

\n
    \n
  • -m, --model <model>: Use a specific model.
    • \n
  • -i, --prompt-interactive <prompt>: Start an interactive session with an initial prompt.
    • \n
  • -d, --debug: Enable debug output.
    • \n
  • --yolo: Auto-approve all tool calls.
    • \n
  • --checkpointing: Save a project snapshot before file modifications. Use /restore to revert changes.
    • \n
\n

Full list of flags.

\n

⚙️ Configuration

\n

Settings Files (settings.json)

\n

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

\n
    \n
  1. Project: .gemini/settings.json (overrides user).
    2. \n
  2. User: ~/.gemini/settings.json
    3. \n
  3. System: /etc/gemini-cli/settings.json (applies to all users, has highest precedence).
    4. \n
\n

Example settings.json:

\n

JSON

\n
{\n  "theme": "GitHub",\n  "autoAccept": false,\n  "sandbox": "docker",\n  "vimMode": true,\n  "checkpointing": { "enabled": true },\n  "fileFiltering": { "respectGitIgnore": true },\n  "usageStatisticsEnabled": true,\n  "includeDirectories": ["../shared-library", "~/common-utils"],\n  "chatCompression": { "contextPercentageThreshold": 0.6 },\n  "customThemes": {\n    "MyCustomTheme": {\n      "name": "MyCustomTheme", "type": "custom",\n      "Background": "#181818", "Foreground": "#F8F8F2",\n      "LightBlue": "#82AAFF", "AccentBlue": "#61AFEF", "AccentPurple": "#C678DD",\n      "AccentCyan": "#56B6C2", "AccentGreen": "#98C379", "AccentYellow": "#E5C07B",\n      "AccentRed": "#E06C75", "Comment": "#5C6370", "Gray": "#ABB2BF"\n    }\n  }\n}\n
\n
    \n
  • autoAccept: Auto-approve safe, read-only tool calls.
    • \n
  • sandbox: Isolate tool execution (e.g., true, "docker", or "podman").
    • \n
  • vimMode: Enable Vim-style editing for the input prompt.
    • \n
  • checkpointing: Enable the /restore command to undo file changes.
    • \n
  • includeDirectories: Define a multi-directory workspace.
    • \n
  • chatCompression: Configure automatic chat history compression.
    • \n
  • customThemes: Define your own color themes.
    • \n
  • usageStatisticsEnabled: Set to false to disable usage statistics.
    • \n
\n

All details in the configuration guide.

\n

Context Files (GEMINI.md)

\n

Use GEMINI.md files to provide instructions to the model and tailor it to your project. Use /init to generate a starting GEMINI.md file for your project.

\n

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

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

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

\n

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.

\n

Example GEMINI.md using imports:

\n

Markdown

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

More in the Full context file guide.

\n

Ignoring Files with .geminiignore

\n

Create a .geminiignore file in your project root to exclude files and directories from Gemini's tools, similar to .gitignore.

\n
# .geminiignore\n/backups/\n*.log\nsecret-config.json\n
\n

🛠️ Working with Tools

\n

Some Built-in Tools

\n
    \n
  • 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")
    • \n
  • Shell Tool: Executes shell commands. Use with caution. To restrict commands, use excludeTools in settings.json. For example: "excludeTools": ["run_shell_command(rm)"]
    • \n
  • 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")
    • \n
  • Memory Tool: For saving and recalling information across sessions - save_memory(fact="My preferred CSS framework is Tailwind CSS.")
    • \n
\n

Custom Tools via MCP Servers

\n

Extend the CLI with your own tools by running Model Context Protocol (MCP) servers. Manage servers via settings.json or with the gemini mcp <add|list|remove> commands.

\n

Capabilities:

\n
    \n
  • OAuth 2.0 Support: Securely connect to remote servers.
    • \n
  • Rich Content Returns: Tools can return multi-modal content like text and images.
    • \n
  • Prompts as Commands: Expose predefined prompts from your server as new slash commands in the CLI.
    • \n
\n

Example mcpServers configuration:

\n

JSON

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

Transport (choose one):

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

Optional:

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

Using OAuth take a look at mcp-server.md

\n

⚡ Core Commands

\n

Helpful Slash Commands (/)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CommandDescription
/compressReplace the entire chat context with a summary to save tokens.
/copyCopy the last response to the clipboard.
/mcpList configured MCP servers and their available tools.
/clearClear the terminal screen and context (Ctrl+L also works).
/toolsList available tools.
/extensionsList active extensions.
/statsShow session token usage and savings.
/memory showShow the combined context from all GEMINI.md files.
/memory refreshReload all GEMINI.md files.
/chat save <tag>Save the current conversation with a tag.
/chat resume <tag>Resume a saved conversation.
/chat listList saved conversation tags.
/restoreList or restore a project state checkpoint.
/authChange the current authentication method.
/bugFile an issue or bug report about the Gemini CLI.
/helpDisplay help information and available commands.
/themeChange the CLI's visual theme.
/quitExit the Gemini CLI.
/ideManage integration with your IDE (e.g., install, enable).
/settingsOpen a friendly editor to change your settings.json file.
/vimToggle Vim mode for input editing.
/initGenerate a starting GEMINI.md context file for your project.
/directoryManage directories in a multi-directory workspace (e.g., add, show).
\n

Context Commands (@)

\n

Reference files or directories in your prompt. The CLI respects .gitignore and .geminiignore. You can also reference images, PDFs, audio, and video files.

\n

Include a single file:

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

Include an image:

\n
> Describe what you see in this screenshot. @./ux-mockup.png\n
\n

Include a whole directory (recursively):

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

Shell Commands (!)

\n

Run shell commands directly in the CLI.

\n

Run a single command:

\n
> !git status\n
\n

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

\n

Keyboard Shortcuts

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ShortcutDescription
Ctrl+LClear the screen.
Ctrl+VPaste text or an image from the clipboard.
Ctrl+YToggle YOLO mode (auto-approve all tool calls).
Ctrl+XOpen the current prompt in an external editor.
\n

✨ Advanced Features

\n

IDE Integration (VS Code)

\n

Connect the CLI to VS Code for a more powerful, context-aware experience.

\n
    \n
  • Workspace Context: Automatically gets your recent files, cursor position, and selected text.
    • \n
  • Native Diffing: View and approve code changes directly in your editor's diff viewer.
    • \n
  • Commands: Use /ide install to set up and /ide enable to connect.
    • \n
\n

Custom Commands

\n

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.

\n

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

\n

Toml

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

Extensions

\n

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.

\n

For example:

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

JSON

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

Checkpointing & Restore

\n

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

\n

Enable in settings.json or with a flag:

\n

Bash

\n
gemini --checkpointing\n
\n

Restore to a previous state:

\n

Bash

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

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

\n", "content_markdown": "The [Gemini CLI](https://github.com/google-gemini/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.\n\n![Gemini CLI Architecture](https://www.philschmid.de/static/blog/gemini-cli-cheatsheet/architecture.png)\n\n## 🚀 Getting Started\n\n### Installation\n\n**Install Globally:**\n\nBash\n\n```bash\nnpm install -g @google/gemini-cli\n```\n\n**Run without Installing:**\n\nBash\n\n```bash\nnpx @google/gemini-cli\n```\n\n### Authentication with a Gemini API Key\n\nAuthenticate with an API key before first use. See the [authentication guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/authentication.md) for details.\n\n1. **Get Your Key:** Get an API key from [Google AI Studio](https://aistudio.google.com/app/apikey).\n\n2. **Set Your Key:** Make the key available to the CLI with one of these methods.\n\n **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`).\n\n Bash\n\n ```bash\n export GEMINI_API_KEY=\"YOUR_GEMINI_API_KEY\"\n ```\n\n **Method 2: Environment File** Create a `.env` file in `~/.gemini/` for global use or `./.gemini/` for a specific project. The CLI automatically loads it.\n\n ```plaintext\n # In .gemini/.env\n GEMINI_API_KEY=\"YOUR_GEMINI_API_KEY\"\n ```\n\n### Basic Invocation\n\n**Interactive Mode (REPL):** Start a conversational session.\n\nBash\n\n```bash\ngemini\n```\n\n**Non-Interactive Mode:** Pass a prompt and get a single response.\n\nBash\n\n```bash\ngemini -p \"Summarize the main points of the attached file. @./summary.txt\"\n```\n\n**Piping to the CLI:** Pipe content to the CLI.\n\nBash\n\n```bash\necho \"Count to 10\" | gemini\n```\n\n**Sandbox Mode:** Run tools in a secure sandbox (requires Docker or Podman).\n\nBash\n\n```bash\ngemini --sandbox -p \"your prompt\"\n```\n\n**Other Flags:**\n\n- `-m, --model `: Use a specific model.\n- `-i, --prompt-interactive `: Start an interactive session with an initial prompt.\n- `-d, --debug`: Enable debug output.\n- `--yolo`: Auto-approve all tool calls.\n- `--checkpointing`: Save a project snapshot before file modifications. Use `/restore` to revert changes.\n\n[Full list of flags](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md#command-line-arguments).\n\n## ⚙️ Configuration\n\n### Settings Files (`settings.json`)\n\nCustomize the CLI by creating a `settings.json` file. Settings are applied with the following precedence:\n\n1. **Project:** `.gemini/settings.json` (overrides user).\n2. **User:** `~/.gemini/settings.json`\n3. **System:** `/etc/gemini-cli/settings.json` (applies to all users, has highest precedence).\n\n**Example `settings.json`:**\n\nJSON\n\n```json\n{\n \"theme\": \"GitHub\",\n \"autoAccept\": false,\n \"sandbox\": \"docker\",\n \"vimMode\": true,\n \"checkpointing\": { \"enabled\": true },\n \"fileFiltering\": { \"respectGitIgnore\": true },\n \"usageStatisticsEnabled\": true,\n \"includeDirectories\": [\"../shared-library\", \"~/common-utils\"],\n \"chatCompression\": { \"contextPercentageThreshold\": 0.6 },\n \"customThemes\": {\n \"MyCustomTheme\": {\n \"name\": \"MyCustomTheme\", \"type\": \"custom\",\n \"Background\": \"#181818\", \"Foreground\": \"#F8F8F2\",\n \"LightBlue\": \"#82AAFF\", \"AccentBlue\": \"#61AFEF\", \"AccentPurple\": \"#C678DD\",\n \"AccentCyan\": \"#56B6C2\", \"AccentGreen\": \"#98C379\", \"AccentYellow\": \"#E5C07B\",\n \"AccentRed\": \"#E06C75\", \"Comment\": \"#5C6370\", \"Gray\": \"#ABB2BF\"\n }\n }\n}\n```\n\n- `autoAccept`: Auto-approve safe, read-only tool calls.\n- `sandbox`: Isolate tool execution (e.g., `true`, `\"docker\"`, or `\"podman\"`).\n- `vimMode`: Enable Vim-style editing for the input prompt.\n- `checkpointing`: Enable the `/restore` command to undo file changes.\n- `includeDirectories`: Define a multi-directory workspace.\n- `chatCompression`: Configure automatic chat history compression.\n- `customThemes`: Define your own color themes.\n- `usageStatisticsEnabled`: Set to `false` to disable usage statistics.\n\nAll details in the [configuration guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md).\n\n### Context Files (`GEMINI.md`)\n\nUse `GEMINI.md` files to provide instructions to the model and tailor it to your project. Use `/init` to generate a starting `GEMINI.md` file for your project.\n\n**Hierarchical Loading:** The CLI combines `GEMINI.md` files from multiple locations. More specific files override general ones. The loading order is:\n\n1. **Global Context:** `~/.gemini/GEMINI.md` (for instructions that apply to all your projects).\n2. **Project/Ancestor Context:** The CLI searches from your current directory up to the project root for `GEMINI.md` files.\n3. **Sub-directory Context:** The CLI also scans subdirectories for `GEMINI.md` files, allowing for component-specific instructions.\n\nUse `/memory show` to see the final combined context being sent to the model.\n\n**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.\n\n**Example `GEMINI.md` using imports:**\n\nMarkdown\n\n```markdown\n# Main Project Context: My Awesome App\n \n## General Instructions\n- All Python code must be PEP 8 compliant.\n- Use 2-space indentation for all new files.\n \n## Component-Specific Style Guides\n@./src/frontend/react-style-guide.md\n@./src/backend/fastapi-style-guide.md\n```\n\nMore in the [Full context file guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/configuration.md#context-files-geminimd).\n\n### Ignoring Files with `.geminiignore`\n\nCreate a `.geminiignore` file in your project root to exclude files and directories from Gemini's tools, similar to `.gitignore`.\n\n```plaintext\n# .geminiignore\n/backups/\n*.log\nsecret-config.json\n```\n\n## 🛠️ Working with Tools\n\n### Some Built-in Tools\n\n- **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\")`\n- **Shell Tool:** Executes shell commands. **Use with caution.** To restrict commands, use `excludeTools` in `settings.json`. For example: `\"excludeTools\": [\"run_shell_command(rm)\"]`\n- **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\")`\n- **Memory Tool:** For saving and recalling information across sessions - `save_memory(fact=\"My preferred CSS framework is Tailwind CSS.\")`\n\n### Custom Tools via MCP Servers\n\nExtend the CLI with your own tools by running Model Context Protocol (MCP) servers. Manage servers via `settings.json` or with the `gemini mcp ` commands.\n\n**Capabilities:**\n\n- **OAuth 2.0 Support:** Securely connect to remote servers.\n- **Rich Content Returns:** Tools can return multi-modal content like text and images.\n- **Prompts as Commands:** Expose predefined prompts from your server as new slash commands in the CLI.\n\n**Example `mcpServers` configuration:**\n\nJSON\n\n```json\n\"mcpServers\": {\n \"myPythonServer\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"my_mcp_server\", \"--port\", \"8080\"],\n \"cwd\": \"./mcp_tools/python\",\n \"env\": {\n \"DATABASE_URL\": \"$DB_URL_FROM_ENV\"\n },\n \"timeout\": 15000,\n \"trust\": false,\n \"includeTools\": [\"safe_tool_1\", \"safe_tool_2\"],\n \"excludeTools\": [\"dangerous_tool\"]\n }\n}\n```\n\n**Transport (choose one):**\n\n- `command`, `args`, `cwd`: Launch a local process via Stdio\n- `url`: SSE endpoint (e.g., `\"http://localhost:8080/sse\"`)\n- `httpUrl`: HTTP streaming endpoint (e.g., `\"http://localhost:8080/mcp\"`)\n\n**Optional:**\n\n- `env`: Environment variables. Use `$VAR_NAME` syntax to reference shell variables.\n- `headers`: Key-value map of HTTP headers for `url`/`httpUrl` transports.\n- `timeout`: Request timeout in milliseconds (default: 10 minutes).\n- `trust`: Bypass all tool confirmations for this server.\n- `includeTools`/`excludeTools`: Whitelist/blacklist specific tools. `excludeTools` takes precedence.\n\nUsing OAuth take a look at [mcp-server.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#oauth-support-for-remote-mcp-servers)\n\n## ⚡ Core Commands\n\n### Helpful Slash Commands (`/`)\n\n| Command | Description |\n| -------------------- | ------------------------------------------------------------------------ |\n| `/compress` | Replace the entire chat context with a summary to save tokens. |\n| `/copy` | Copy the last response to the clipboard. |\n| `/mcp` | List configured MCP servers and their available tools. |\n| `/clear` | Clear the terminal screen and context (`Ctrl+L` also works). |\n| `/tools` | List available tools. |\n| `/extensions` | List active extensions. |\n| `/stats` | Show session token usage and savings. |\n| `/memory show` | Show the combined context from all `GEMINI.md` files. |\n| `/memory refresh` | Reload all `GEMINI.md` files. |\n| `/chat save ` | Save the current conversation with a tag. |\n| `/chat resume ` | Resume a saved conversation. |\n| `/chat list` | List saved conversation tags. |\n| `/restore` | List or restore a project state checkpoint. |\n| `/auth` | Change the current authentication method. |\n| `/bug` | File an issue or bug report about the Gemini CLI. |\n| `/help` | Display help information and available commands. |\n| `/theme` | Change the CLI's visual theme. |\n| `/quit` | Exit the Gemini CLI. |\n| `/ide` | Manage integration with your IDE (e.g., `install`, `enable`). |\n| `/settings` | Open a friendly editor to change your `settings.json` file. |\n| `/vim` | Toggle Vim mode for input editing. |\n| `/init` | Generate a starting `GEMINI.md` context file for your project. |\n| `/directory` | Manage directories in a multi-directory workspace (e.g., `add`, `show`). |\n\n### Context Commands (`@`)\n\nReference files or directories in your prompt. The CLI respects `.gitignore` and `.geminiignore`. You can also reference images, PDFs, audio, and video files.\n\n**Include a single file:**\n\n```plaintext\n> Explain this code to me. @./src/main.js\n```\n\n**Include an image:**\n\n```plaintext\n> Describe what you see in this screenshot. @./ux-mockup.png\n```\n\n**Include a whole directory (recursively):**\n\n```plaintext\n> Refactor the code in this directory to use async/await. @./src/\n```\n\n### Shell Commands (`!`)\n\nRun shell commands directly in the CLI.\n\n**Run a single command:**\n\n```plaintext\n> !git status\n```\n\n**Toggle Shell Mode:** Enter `!` by itself to switch to a persistent shell mode. Type `!` again to exit.\n\n### Keyboard Shortcuts\n\n| Shortcut | Description |\n| -------- | ----------------------------------------------- |\n| `Ctrl+L` | Clear the screen. |\n| `Ctrl+V` | Paste text or an image from the clipboard. |\n| `Ctrl+Y` | Toggle YOLO mode (auto-approve all tool calls). |\n| `Ctrl+X` | Open the current prompt in an external editor. |\n\n## ✨ Advanced Features\n\n### IDE Integration (VS Code)\n\nConnect the CLI to VS Code for a more powerful, context-aware experience.\n\n- **Workspace Context:** Automatically gets your recent files, cursor position, and selected text.\n- **Native Diffing:** View and approve code changes directly in your editor's diff viewer.\n- **Commands:** Use `/ide install` to set up and `/ide enable` to connect.\n\n### Custom Commands\n\nCreate custom commands using TOML files. Store them in `~/.gemini/commands/` (global) or `/.gemini/commands/` (project-specific). See the [custom commands guide](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/commands.md#custom-commands) for more details.\n\n**Example: `~/.gemini/commands/test/gen.toml`**\n\nToml\n\n```toml\n# Invoked as: /test:gen \"Create a test for the login button\"\ndescription = \"Generates a unit test based on a description.\"\nprompt = \"\"\"\nYou are an expert test engineer. Based on the following requirement, please write a comprehensive unit test using the Jest testing framework.\n \nRequirement: {{args}}\n\"\"\"\n```\n\n### Extensions\n\nCreate extensions to add functionality. Place them in `/.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](https://github.com/google-gemini/gemini-cli/blob/main/docs/extension.md).\n\nFor example:\n\n```plaintext\n/.gemini/extensions/my-extension/gemini-extension.json\n```\n\nJSON\n\n```json\n{\n \"name\": \"my-extension\",\n \"version\": \"1.0.0\",\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"node my-server.js\"\n }\n },\n \"contextFileName\": \"GEMINI.md\",\n \"excludeTools\": [\"run_shell_command\"]\n}\n```\n\n### Checkpointing & Restore\n\nWhen `checkpointing` is on, the CLI saves a project snapshot before tools modify files.\n\n**Enable in `settings.json` or with a flag:**\n\nBash\n\n```bash\ngemini --checkpointing\n```\n\n**Restore to a previous state:**\n\nBash\n\n```bash\n# List available checkpoints\n/restore\n \n# Restore a specific checkpoint\n/restore \n```\n\n* * *\n\nThanks for reading! If you have any questions or feedback, please let me know on [Twitter](https://twitter.com/_philschmid) or [LinkedIn](https://www.linkedin.com/in/philipp-schmid-a6a2bb196/).\n", "dateCreated": "2026-09-27T19:29:15.293681927+00:00", "date_created": "2025-07-24T00:00:00+00:00", "date_modified": "2025-07-24T00:00:00+00:00", "date_published": "2025-07-24T00:00:00+00:00", "description": "A comprehensive cheatsheet on using Google's Gemini CLI, covering installation, authentication, configuration, and core commands.", "external_url": "https://www.philschmid.de/gemini-cli-cheatsheet", "git": { "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e", "path": "items/philschmid-de/2025/07/2025-07-24-google-gemini-cli-cheatsheet.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/philschmid-de/2025/07/2025-07-24-google-gemini-cli-cheatsheet.md" }, "id": "urn:aggr:item:19de8e64f561acd5c88b7afc035dd113fbdbc3a9", "isBasedOn": { "@id": "https://www.philschmid.de/gemini-cli-cheatsheet" }, "mainEntity": { "@id": "https://www.philschmid.de/gemini-cli-cheatsheet", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/philschmid-de/2025-07-24-google-gemini-cli-cheatsheet/#webpage" }, "dateModified": "2025-07-24T00:00:00+00:00", "datePublished": "2025-07-24T00:00:00+00:00", "headline": "Google Gemini CLI Cheatsheet", "timeRequired": "PT7M", "url": "https://www.philschmid.de/gemini-cli-cheatsheet", "wordCount": 1549 }, "name": "Archived snapshot: Google Gemini CLI Cheatsheet", "preview": null, "reading_minutes": 7, "replicated_at": null, "source": "philschmid-de", "source_name": "philschmid.de - RSS feed", "summary": "A comprehensive cheatsheet on using Google's Gemini CLI, covering installation, authentication, configuration, and core commands.", "tags": [], "temporalCoverage": "2026-09-27T19:29:15.293681927+00:00", "title": "Google Gemini CLI Cheatsheet", "url": "https://aggr.aymericbeaumet.com/items/philschmid-de/2025-07-24-google-gemini-cli-cheatsheet/", "word_count": 1549 }