Gemini CLI

Gemini CLI is Google's open-source terminal coding agent, licensed Apache-2.0. Since 18 June 2026 it is meant for organizations with Gemini Code Assist Standard or Enterprise on Google Cloud. Individuals and Google AI Pro or Ultra subscribers were moved to Antigravity CLI. Checked 31 October 2026.

At a glance

The status change you need to know first

Most older guides and videos still describe Gemini CLI as a free agent with a generous individual tier. That is out of date. The README now opens with a warning box, and its main points are:

• Enterprise Code Assist only. The tool is designed for Gemini Code Assist Standard or Enterprise licenses and Code Assist for GitHub on Google Cloud. Access for those customers is unchanged.
• No free tier or Google AI plans. Free individual access and Google AI Pro and Ultra moved to Antigravity CLI on 18 June 2026.
• Not tuned for Gemini 4 and later. The README says it is not optimized for the Gemini 4 series or later generations.
• Not for benchmarks. The README says not to use it to benchmark Gemini models because its harness "produces unrepresentative scores."

The Google developers blog post on the transition adds that Gemini CLI also remains available through paid Gemini and Gemini Enterprise Agent Platform API keys, and that Antigravity CLI keeps Agent Skills, hooks, subagents and extensions, which are now called Antigravity plugins. It warns that feature parity is not one-to-one at launch.

So the first decision is not "Gemini CLI or Claude Code". It is "which of Google's tools do I belong to".

Which Google CLI do you need?

The README has its own table. In our words:

Install

The README lists four ways to install, plus the option to run without installing.

# Run with no install
npx @google/gemini-cli

# npm, global
npm install -g @google/gemini-cli

# Homebrew (macOS and Linux)
brew install gemini-cli

# MacPorts (macOS)
sudo port install gemini-cli

For locked-down machines the README suggests Anaconda: create a conda environment with nodejs from conda-forge, activate it, and run the npm install inside it.

Release channels

Gemini CLI ships on a fixed weekly rhythm, which is useful if you manage it for a team:

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

Pin a version in CI instead of floating on latest, and let a small group run preview a week ahead.

Authentication

There are three options in the README.

1. Sign in with Google. Run gemini and follow the browser flow. With a paid Code Assist license from your organization, set the Cloud project first:

`bash

export GOOGLECLOUDPROJECT="YOURPROJECTID"

gemini

`

1. Gemini API key. Get a key from Google AI Studio and export GEMINI_API_KEY. This lets you choose specific models and gives usage-based billing.
2. Vertex AI. Export GOOGLE_API_KEY and GOOGLE_GENAI_USE_VERTEXAI=true. The README positions this for enterprise teams, with higher rate limits on a billing account.

Google Workspace accounts and other methods are covered in the authentication guide.

Everyday use

gemini                                          # start in the current directory
gemini --include-directories ../lib,../docs     # add more folders
gemini -m gemini-2.5-flash                      # pick a model
gemini -p "Explain the architecture of this codebase"
gemini -p "Run tests and deploy" --output-format stream-json

-p runs once without the interactive screen. --output-format json returns structured output for scripts, and stream-json streams newline-delimited events, which suits long jobs.

The documented feature set:

• querying and editing large codebases
• building apps from PDFs, images or sketches, using multimodal input
• debugging in natural language
• automating tasks such as querying pull requests or handling a complex rebase
• checkpointing, to save and resume conversations
• token caching
• trusted folders, which control execution policy per folder
• sandboxing for safer command execution
• a VS Code companion
• telemetry and an enterprise guide for rollout

Models

You choose a model with -m or through the API key route. The README's own example uses gemini-2.5-flash. Because the CLI is not tuned for Gemini 4 and later, the practical answer for newer Gemini models is to use Antigravity instead.

MCP, extensions and custom commands

MCP servers are set in ~/.gemini/settings.json, and then you call them by name in the prompt, as in the README's examples (@github List my open pull requests). Beyond MCP:

• Custom commands are reusable prompts you define yourself.
• Context files (GEMINI.md) hold standing instructions for a project.
• Extensions bundle commands and tools to share.

The best MCP servers are the same ones you would add to any agent. Start with GitHub MCP and Context7, then browse the MCP server list.

Context files, in detail

The GEMINI.md file is the most useful thing you can set up, and the docs describe it as a hierarchy, not a single file. The CLI loads several and joins them before each prompt.

The footer shows how many context files are loaded, which is a quick check that your file was found. Two commands help while you write them. /memory show prints the full combined context the model receives, so you can see exactly what it is told. /memory reload rescans after you edit a file. Run /memory show the first time, because a surprise in that output, such as a stale global file contradicting your project file, explains many odd results.

Large files can be split into modules. The docs describe an @file.md import syntax, with relative or absolute paths, so a short top-level file can pull in @docs/testing.md and @docs/style.md. That keeps each piece small and reviewable.

If your team already writes an AGENTS.md for other tools, point Gemini CLI at it instead of duplicating. The setting lives in ~/.gemini/settings.json or the project's settings:

{
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

With that list, the CLI looks for both names. Keep the shared rules in AGENTS.md and Gemini-specific notes in GEMINI.md. The same idea works the other way, but check the other tool's documentation for its setting.

What the API-key route costs

Organizations on Code Assist pay through their licence, so the per-token maths matters for the API-key and Vertex routes. Google's published rate for Gemini 3.8 Flash is $0.75 per million input tokens and $3.75 per million output tokens until 31 December 2026, then $1.50 and $7.50, according to the Gemini API pricing page our pricing writer checked. The token volumes below are assumptions to show the arithmetic.

Agent loops resend context on each step, so real input counts run far higher than the size of the files you open. The CLI's token caching helps, and the README lists it as a feature, but the discount for cached input depends on the model. Read the usage numbers from your own account after a week and adjust. See Gemini API pricing for the full table and the rate changes.

Scripting and CI use

The -p flag makes the CLI usable in scripts, and --output-format json gives something a script can parse. A few rules keep a pipeline safe:

1. Pin the version. Use npm install -g @google/gemini-cli@VERSION in CI, so a Tuesday release cannot change behaviour overnight.
2. Keep it read-only where you can. A job that summarizes a diff or drafts release notes needs no write access. Give a write job its own branch and a token with the narrowest scope.
3. Handle failure. Check the exit code and the JSON for errors, and fail the job on malformed output. Do not retry blindly, since each retry costs tokens.
4. Cap the input. Pass the diff and the files that matter, not the whole repository.
5. Never put secrets in the prompt. Environment variables for the CLI itself are fine. Text sent to the model is not.
6. Review the output. A model-written change goes through the same review as a human one.

A typical safe job: on each pull request, run gemini -p "Summarize this diff for a reviewer and list any files that lack tests" --output-format json, post the summary as a comment, and stop there. It adds value with almost no risk, which is the right place to start. Move to code-changing jobs only after a month of clean summaries.

Limits, privacy and data handling

Prompts and the files the agent reads go to Google's models, so the privacy answer depends on how you sign in: a Code Assist license, an API key or Vertex each fall under different Google Cloud terms.

What the README does document is control on your side: trusted folders, sandboxing and telemetry settings. The enterprise guide covers corporate deployment.

Other limits:

• No free individual tier any more.
• Not tuned for Gemini 4 and later.
• Google says to expect differences if you migrate to Antigravity CLI, so confirm your hooks and skills still work.

Who it suits

• Teams already paying for Gemini Code Assist Standard or Enterprise.
• Organizations that want an open-source agent they can audit and pin by release.
• Developers on legacy paid API or Vertex keys who do not want to switch tools yet.

It does not suit a solo developer looking for a free agent. That person should start at Antigravity or look at the free AI agents list.

Moving to or from Gemini CLI

From Gemini CLI to Antigravity CLI. Install with curl -fsSL https://antigravity.google/cli/install.sh | bash on macOS or Linux, then follow the migration guide at antigravity.google/docs/gcli-migration. Skills, hooks, subagents and extensions carry over under the name plugins, but not one to one.

From Gemini CLI to Claude Code. Copy the contents of GEMINI.md into a CLAUDE.md, re-add each MCP server with claude mcp add, and recreate custom commands as skills. See Claude Code.

From Claude Code to Gemini CLI. Do the reverse, and keep AGENTS.md if your team uses it, since several agents read that name.

A first session, step by step

The README's own examples give a good first hour.

1. Make a scratch folder and start the agent: cd new-project/ then gemini.
2. Ask for something small and checkable, such as the README's "Write me a Discord bot that answers questions using a FAQ.md file I will provide".
3. Switch to an existing repository: clone one, run gemini inside it, and ask "Give me a summary of all of the changes that went in yesterday". Reading history is a low-risk way to judge how well it understands a codebase.
4. Add a second folder with --include-directories when the task spans a library and its docs.
5. Run the same question once with -p so you see what the scripted version returns.

None of those steps edits anything risky. Only after that is it worth giving the agent write access to a branch you care about.

Rolling it out to a team

Because the tool targets organizations, the rollout questions matter more than the install line.

Write the answers into a short internal page, and put the shared rules in a GEMINI.md committed to each repository so every developer starts from the same context.

Common questions

Can I still install it as an individual? The package installs, but the README says free individual access moved to Antigravity CLI, so you should expect it not to serve you. Check the transition post before you spend time on it.

Does it read `AGENTS.md`? Not by default. The docs say GEMINI.md is the default filename, and that you can change it with the context.fileName setting, which accepts a list such as AGENTS.md, CONTEXT.md and GEMINI.md.

Can it run in CI? Yes, with -p and --output-format json. The headless mode page in the docs covers errors and parsing.

What do I do about Gemini 4? Use Antigravity. The README says Gemini CLI is not tuned for that series.

Is the project active? Judging from the repository, yes. The last push we saw was on 30 October 2026, the release schedule is weekly, and the README links a public roadmap. Activity is not the same as a good fit, but it means a bug you report has a place to land.

Alternatives and duos

Our take

This is a reading of the README and Google's own announcement. We have not tested Gemini CLI for this page.

The honest summary is that Gemini CLI is no longer the default answer for Google's models. It is open source and still maintained on a weekly cadence, with about 108,600 stars and a push on 30 October 2026, but Google itself says to use Antigravity for newer models and for individual accounts. If you are a paying Code Assist customer, it is a sensible, auditable tool. If you are not, you will spend your time on a tool that is not meant for you.

The part worth admiring is the release discipline: three channels, fixed times, and pinning by tag. If you manage agents across a team, that is the model other tools should copy.

Checklist

• Confirm which Google license you hold before you install
• Set GOOGLE_CLOUD_PROJECT for Code Assist logins
• Pin the version in CI and choose a release channel
• Put project rules in GEMINI.md
• Add one MCP server in ~/.gemini/settings.json
• If you are an individual, test Antigravity CLI instead