Abstract:

This document set provides comprehensive documentation for the Google Gemini Command Line Interface (CLI), an AI workflow tool designed to interact with Gemini models and integrate with various system capabilities. It details the CLI's architecture, including its user-facing frontend (packages/cli), backend logic and API interaction (packages/core), and an extensible suite of built-in and custom tools (e.g., file system operations, web search, shell execution). The documentation outlines installation methods, advanced features like sandboxing and checkpointing for security, configuration options, authentication procedures with varying privacy implications, and guidelines for contributing to the project.

Summarizing the Gemini CLI Project Documentation:

• Project Overview: The Gemini CLI is a command-line AI workflow tool that connects to Google's Gemini models, enabling users to query and edit large codebases, generate new applications, automate tasks, and interact with system tools. It operates in an interactive Read-Eval-Print Loop (REPL) environment.
• Core Architecture:
  • CLI Package (packages/cli): The user-facing frontend, managing input, output rendering, UI customization, and history.
  • Core Package (packages/core): The backend, handling communication with the Gemini API, prompt construction, tool registration and execution, and session state.
  • Tools: Individual modules (e.g., File System, Shell, Web Fetch/Search) that extend Gemini's capabilities to interact with the local environment, managed and invoked by the core package.
• Installation & Execution:
  • Standard Installation: Recommended for typical users via npm install -g @google/gemini-cli or npx @google/gemini-cli.
  • Sandbox Execution: For security and isolation, the CLI can run within a Docker or Podman container, especially for tools with side effects. MacOS also offers a lightweight Seatbelt sandboxing.
  • From Source: For contributors, enabling development with hot-reloading using npm run start or npm link.
• Authentication Methods & Privacy:
  • Login with Google (Gemini Code Assist): For individuals; prompts, answers, and code may be collected for model improvement.
  • Gemini API Key: Prompts/answers collected for model improvement (unpaid) or solely for policy violation detection (paid).
  • Google Workspace/Licensed Code Assist & Vertex AI: User data (prompts, answers, code) is not used to train models; collection is typically limited to anonymous telemetry.
• Key Features:
  • Checkpointing: Automatically saves a project's state before file modifications by AI tools, allowing instant reverts using the /restore command. Disabled by default.
  • Telemetry: Built on OpenTelemetry, collects anonymized data on performance, health, and usage. Customizable targets (local or Google Cloud) and configurable logging of prompts.
  • Hierarchical Context (GEMINI.md): Markdown files (e.g., GEMINI.md) can provide project-specific instructions, coding styles, or background information, loaded hierarchically from global, project, and sub-directory locations to guide the AI.
  • Token Caching: Automatically optimizes API costs by reusing previous system instructions and context, available for API key and Vertex AI users.
  • Chat History Compression: Automatically summarizes long conversations to stay within token limits.
  • Model Fallback: Switches to a "flash" model if the default "pro" model is rate-limited.
• CLI Commands:
  • Slash Commands (/): Control the CLI (e.g., /help, /clear, /theme, /stats, /mcp for Model Context Protocol server info). /bug for filing issues and /auth for changing authentication.
  • At Commands (@): Inject file or directory content into prompts for context, with Git-aware filtering.
  • Shell Mode (!): Execute system shell commands or toggle an interactive shell mode.
• Built-in Tools: The CLI leverages various tools for enhanced functionality:
  • File System Tools: list_directory, read_file, write_file, glob (FindFiles), search_file_content (SearchText), replace (Edit) for interacting with files and directories. File modification tools typically require user confirmation.
  • Execution Tools: run_shell_command executes arbitrary shell commands (requires sandboxing and user confirmation).
  • Web Tools: web_fetch retrieves content from URLs and google_web_search performs web searches.
  • Memory Tools: save_memory stores "facts" in a user's ~/.gemini/GEMINI.md for recall in future sessions.
  • MCP Servers: Allow connecting to external services or custom scripts, exposing their capabilities to the Gemini model.
• Contribution Guidelines: Detailed instructions for contributing, including signing a CLA, linking PRs to issues, keeping PRs small, running preflight checks (npm run preflight), updating documentation, and adhering to specific coding conventions (e.g., preferring plain objects over classes, ES module syntax for encapsulation, avoiding any types).