Gemini CLI guide: install, auth, GEMINI.md, MCP and the 2026 changes

Gemini CLI is Google's open-source coding agent for the terminal, but since June 18, 2026 it no longer serves free users or Google AI Pro and Ultra subscribers, who were moved to Antigravity CLI. This guide explains who can still use Gemini CLI, how to install and configure it, how GEMINI.md and MCP work, and when to switch.

What is Gemini CLI, and can you still use it?

Gemini CLI is an open-source AI agent that runs Google's Gemini models in your terminal: it reads your codebase, edits files, runs shell commands and connects to MCP servers. It is published under the Apache 2.0 license in the google-gemini/gemini-cli repository.

The big change in 2026 is who can use it. Google's announcement says that on June 18, 2026, Gemini CLI and the Gemini Code Assist IDE extensions stopped serving requests for Google AI Pro and Ultra, and free use through Gemini Code Assist for individuals ended. The README now says unpaid tier and Google One users were moved to Antigravity CLI, and that Gemini CLI has not been optimized for the newest Gemini models.

So there are two kinds of readers for this guide:

• You have a paid Gemini API key, a Google Cloud setup, or a Gemini Code Assist Standard or Enterprise license. Gemini CLI still works for you, and everything below applies.
• You used Gemini CLI for free or through a Google AI Pro or Ultra subscription. You now need Antigravity CLI. Your GEMINI.md files carry over, and the migration section below shows what changes.

Who can use Gemini CLI after June 2026?

Gemini CLI is now for paid API and enterprise users; everyone else is pointed to Antigravity CLI. This table summarizes the announcement at the time of writing (October 2026).

Google says Antigravity CLI "is available to everyone," and Antigravity's plans page describes baseline rate limits for users without a Google AI plan, with higher limits and the option of purchased AI credits for Pro and Ultra subscribers.

How do I install Gemini CLI?

Install the npm package globally, then run gemini inside a project folder. Gemini CLI needs Node.js 20 or newer.

1. Check your Node version with node --version. Install Node 20+ if needed.

2. Install Gemini CLI globally with npm. On macOS or Linux, brew install gemini-cli also works, and npx @google/gemini-cli runs it without installing:

   npm install -g @google/gemini-cli

3. Move into a project and start it:

   cd ~/code/my-appgemini

4. Pick an authentication method when prompted (next section).

Gemini CLI ships on three release channels: latest (stable, weekly on Tuesdays), preview (weekly, less vetted) and nightly. Stick with latest unless you need a specific fix: npm install -g @google/gemini-cli@latest.

How do I sign in to Gemini CLI?

Use a Gemini API key from Google AI Studio, a Google Cloud setup, or sign in with a Google account that holds a Code Assist license. The authentication docs cover each path.

Gemini API key

Create a key in Google AI Studio, export it, start the CLI and choose Use Gemini API key:

export GEMINI_API_KEY="your-key-here"gemini

With a paid key you are billed per token at Gemini API rates, so check the current prices on Google's pricing page before running long tasks.

Google Cloud (Vertex AI or Agent Platform)

For enterprise projects on Google Cloud:

export GOOGLE_API_KEY="your-cloud-key"export GOOGLE_GENAI_USE_VERTEXAI=truegemini

Sign in with Google and a Code Assist license

If your organization gives you a Gemini Code Assist Standard or Enterprise license, select Sign in with Google. Company, school and Workspace accounts also need a Google Cloud project:

export GOOGLE_CLOUD_PROJECT="your-project-id"gemini

How do you use GEMINI.md files?

GEMINI.md is the instruction file Gemini CLI loads into every prompt: build commands, code style, architecture notes and rules. It plays the same role as CLAUDE.md for Claude Code and AGENTS.md for Codex.

According to the GEMINI.md docs, the CLI combines files from three places:

1. Global: ~/.gemini/GEMINI.md, for preferences that apply to every project.
2. Workspace: GEMINI.md files in your workspace directories and their parents.
3. Just in time: when a tool touches a file or folder, the CLI looks for GEMINI.md in that folder and its ancestors, so component-specific rules load only when needed.

The footer shows how many context files are loaded. Useful commands:

A short, useful GEMINI.md:

## Commands- Install: npm ci- Test: npm test (run before saying a task is done)- Lint: npm run lint## Conventions- TypeScript strict mode, no `any`- API handlers live in src/api/, one file per route- Never edit files in dist/ or generated/

You can split a long file with imports (@./docs/style-guide.md), and you can change the file name. If your team already keeps instructions in AGENTS.md, add this to settings.json so Gemini CLI reads it too:

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

The same principles that make a good CLAUDE.md apply here; our guide to CLAUDE.md best practices covers what to include and what to leave out.

How do I add MCP servers to Gemini CLI?

Declare servers under mcpServers in settings.json, or add them with gemini mcp add. MCP servers give the agent tools such as GitHub, databases or browsers.

The MCP docs show the format. A GitHub server in your user settings:

{  "mcpServers": {    "github": {      "command": "npx",      "args": ["-y", "@github/github-mcp-server"],      "env": {        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PERSONAL_ACCESS_TOKEN"      }    }  }}

Or from the command line, for a local or remote server:

gemini mcp add -e API_KEY=123 my-server /path/to/servergemini mcp add --transport http my-http-server https://api.example.com/mcp/

gemini mcp add writes to project settings by default; pass -s user to add it for all projects. Inside a session, /mcp lists servers and their tools, and you can address a server's tools in a prompt with @github List my open pull requests. Each server config also has a trust property; leave it false so the CLI asks before running that server's tools. New to MCP? Start with what MCP is and how it works.

How do you keep Gemini CLI safe?

Pick an approval mode that matches the task, turn on the sandbox for anything unattended, and only trust folders you know. Gemini CLI runs real shell commands on your machine.

• Approval modes: default asks before actions, auto_edit auto-approves file edits, and plan is read-only. You can set these in settings or with --approval-mode. YOLO mode, which approves everything, can only be turned on from the command line (--yolo or --approval-mode=yolo), and admins can block it with security.disableYoloMode.
• Plan mode: /plan switches to a read-only mode and shows the current plan, so you can review the approach before any edit.
• Sandbox: the sandboxing docs list three ways to enable it: the -s or --sandbox flag, the GEMINI_SANDBOX environment variable (true, docker, podman, sandbox-exec and others), or "sandbox": true under tools in settings.
• Trusted folders: /permissions trust manages which directories the CLI treats as trusted.

For scripts and CI, headless mode prints a single answer, optionally as JSON:

gemini -p "Summarize what changed in the last 10 commits" --output-format json

Headless runs pair well with a machine that stays on. If you want coding agents to keep working after you close your laptop, a hosted box such as Orkio runs Claude Code and Codex 24/7 on an isolated server you steer from your phone.

Should you switch to Antigravity CLI?

If you lost Gemini CLI access in June, yes: Antigravity CLI is Google's replacement, and most of your setup carries over. If you are on a paid key or Code Assist license, you can stay on Gemini CLI, but new Gemini models are optimized for Antigravity.

Install the agy binary with Google's installer, per the Antigravity getting started docs:

curl -fsSL https://antigravity.google/cli/install.sh | bashagy

On first launch in an environment with Gemini CLI config, agy detects it and offers a checklist of what to migrate. The migration guide lists what changes:

Google's announcement says skills, hooks, subagents and extensions carry over, but warns there will not be one-to-one feature parity at first.

How does Gemini CLI compare with Claude Code and Codex?

All three are terminal agents with an instruction file, MCP support and approval modes; they differ mostly in model family, account model and ecosystem.

If you are choosing a primary agent today, the guides for Claude Code and Codex CLI walk through the same setup steps for those tools, and our roundup of AI in the terminal compares the wider field.

Your Gemini CLI setup checklist

Use this list to get from zero to a safe, useful setup in under an hour.

• Confirm your account type: paid API key or Code Assist license means Gemini CLI; free or Google AI Pro or Ultra means Antigravity CLI.
• Install Node.js 20+ and @google/gemini-cli@latest, or install agy.
• Authenticate and keep the key out of your repository.
• Run /init, then trim the generated GEMINI.md to commands, conventions and no-go zones.
• Add one MCP server you will actually use, with trust left off.
• Start with default approval mode and /plan for anything bigger than a small fix.
• Turn on the sandbox before running unattended or headless jobs.

Frequently asked questions