Gemini CLI: Google's Open-Source AI Agent for the Terminal

What Gemini CLI is

Gemini CLI is Google's open-source AI agent for the terminal. It runs as a Node.js command-line app (gemini) that talks to Gemini models and can read your project, edit files, run shell commands and call external tools, with permission prompts before actions that change things. The code is Apache-2.0 licensed and developed in the open on GitHub.

The README describes it as giving developers the most direct path from a prompt to the model, and lists three broad jobs: understanding and generating code in large codebases, building apps from PDFs, images or sketches using multimodal input, and automating operational work such as querying pull requests or handling complex rebases. It also runs non-interactively, which makes it usable in scripts and CI.

One important caveat sits at the top of the README. Google states that for unpaid-tier and Google One users, Gemini CLI was replaced by Antigravity CLI on 18 June 2026, and that Gemini CLI is not optimized for the latest Gemini models, including Gemini 4 Argon, for which it recommends Antigravity. The repository remains active, with weekly releases, but anyone evaluating it today should read that notice first.

How it works

Gemini CLI is an agent loop around a model plus a set of built-in tools: file system operations, shell commands, and web fetch and search. You start it in a directory and it works on that workspace; extra directories can be added with --include-directories. Several mechanisms shape what the agent knows and can do:

• GEMINI.md context files: instructions loaded hierarchically from ~/.gemini/GEMINI.md, from workspace directories and their parents, and just-in-time from directories a tool touches. Files can import others with @file.md, and the file name is configurable, for example to also read AGENTS.md.
• MCP servers: configured in ~/.gemini/settings.json to add tools such as GitHub, Slack or database access.
• Extensions: packages that bundle prompts, MCP servers, custom commands, themes, hooks, sub-agents and agent skills, installed from a GitHub URL with gemini extensions install.
• Settings: user and workspace settings.json files, environment variables and CLI flags.

Authentication goes through one of three routes: signing in with a Google account (Gemini Code Assist), a Gemini API key, or Vertex AI. Each maps to different terms of service and privacy notices, which the docs tabulate.

Key features

• Headless mode: -p runs a single prompt; --output-format json returns structured output and --output-format stream-json emits newline-delimited events for long-running jobs.
• Sandboxing: shell commands and file edits can run inside macOS Seatbelt profiles or a Docker or Podman container that mounts the project at the same absolute path. Other options listed include runsc and lxc.
• Trusted Folders: an opt-in feature that asks before loading project-specific configuration. Untrusted folders run in a safe mode that ignores workspace settings and .env files, disables MCP connections and custom commands, and always prompts before tools run.
• Checkpointing and session management: save and resume conversations, and rewind changes.
• Custom commands, hooks and skills: reusable slash commands defined in TOML, hooks that intercept CLI behavior, and agent skills.
• IDE integration: a VS Code companion, which also works when the CLI runs in a sandbox.
• OpenTelemetry observability: logs, metrics and traces exportable to Google Cloud or any OTLP backend. This is off by default.

Getting started

Gemini CLI needs Node.js 20 or newer; the docs recommend macOS 15+, Windows 11 24H2+ or Ubuntu 20.04+, and an internet connection. Try it without installing:

npx @google/gemini-cli

Or install it globally with npm or Homebrew:

npm install -g @google/gemini-cli
brew install gemini-cli

Run gemini and choose an authentication method. With an API key from Google AI Studio:

export GEMINI_API_KEY="YOUR_API_KEY"
gemini

For scripting, pass a prompt directly and ask for JSON:

gemini -p "Explain the architecture of this codebase" --output-format json

To run with sandboxing enabled:

gemini -s -p "analyze the code structure"

Release channels are published on npm: preview builds weekly on Tuesdays at 23:59 UTC, latest stable builds weekly on Tuesdays at 20:00 UTC, and nightly builds daily.

Use cases

• Codebase exploration: ask for an explanation of an unfamiliar repository, or a summary of recent changes, with the agent reading source files after asking for permission.
• Scaffolding: start an empty directory and describe the app you want, including from an image or PDF.
• CI and automation: run headless with JSON output in pipelines, combined with --skip-trust where the trusted-folder dialog cannot be shown.
• Tool-connected workflows: use MCP servers to list pull requests, post summaries to chat, or query databases from the same session.
• File and data chores: the getting-started guide shows renaming photos by their content and merging spreadsheets.

How it compares

Gemini CLI belongs to the terminal coding-agent category alongside tools such as Claude Code, OpenAI Codex CLI and open-source agents like OpenCode. Its distinguishing traits are the Apache-2.0 codebase, first-party access to Gemini models through Google accounts, API keys or Vertex AI, and a broad extension and MCP story. The flip side is that it is tied to Google's model services, and by Google's own notice it is no longer the recommended client for the newest Gemini models; Antigravity CLI is.

Things to know before adopting

• Antigravity transition: unpaid-tier and Google One users were moved to Antigravity CLI on 18 June 2026. Check which account type and model you plan to use before standardising on Gemini CLI.
• Terms of service vary by auth method: Google account, unpaid API key, paid API key and Vertex AI each fall under different terms and privacy notices. The docs also state that using Gemini CLI's OAuth credentials from third-party tools to reach the backing services violates the terms and can lead to account suspension.
• Usage statistics: the docs say Gemini CLI usage statistics are handled under Google's Privacy Policy. Separate OpenTelemetry telemetry is disabled by default, but when enabled its logPrompts setting defaults to true.
• Trusted Folders is opt-in: it is disabled by default, so project-level settings, MCP servers and commands load automatically unless you enable it.
• Location and organisation limits: availability follows Gemini Code Assist supported locations, and managed Google Workspace accounts may need an administrator's permission or a Google Cloud project.
• Fast release cadence: weekly stable releases mean behaviour changes often; pin versions in CI. Preview builds are explicitly described as not fully vetted and may contain regressions, and nightly builds should be assumed to have pending validations.
• Hardware for long sessions: the docs suggest 4GB+ RAM for casual use and 16GB+ for long sessions on large codebases with deep context.

Project activity

As of October 2026 the repository has about 108,400 stars and roughly 14,800 forks. It was created in April 2025, is written in TypeScript and is licensed under Apache-2.0. The latest release at the time of writing is v0.65.0, published on 20 October 2026, and the main branch is updated daily. Code is at github.com/google-gemini/gemini-cli, the npm package is @google/gemini-cli, and documentation is at geminicli.com/docs.

[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/gemini-cli?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)