- Is Gemini CLI Still Free in 2026?
- Gemini CLI Requirements
- Step 1: Install Gemini CLI
- Step 2: Sign In (Authentication)
- Step 3: Give Gemini CLI Project Context with GEMINI.md
- Step 4: Configure settings.json
- Step 5: Everyday Commands
- Step 6: Connect MCP Servers
- Step 7: Stay in Control: Approval Modes, Checkpoints and Sandboxing
- Step 8: Use Gemini CLI in Scripts and CI (Headless Mode)
- Extensions
- Moving from Gemini CLI to Antigravity CLI
- Gemini CLI Troubleshooting
- Gemini CLI vs Claude Code vs Codex CLI
- Related Guides
- Frequently Asked Questions
- Conclusion
Gemini CLI is Google's open-source AI agent for the terminal. You type gemini in a project folder, describe a task in plain English, and it reads your code, edits files, runs commands and connects to tools through MCP.
But most Gemini CLI setup guides you'll find are out of date. On 18 June 2026, Google moved free accounts and Google AI Pro and Ultra subscribers from Gemini CLI to the new Antigravity CLI (agy). Gemini CLI is still released every week, but it is now aimed at companies with Gemini Code Assist licences and at people using paid API or Vertex AI keys.
This guide covers both sides: how to install and configure Gemini CLI today (authentication, GEMINI.md, settings, MCP, sandboxing and headless mode), and what to use instead if you're an individual developer. Every command and limit here comes from the official Gemini CLI documentation, the gemini-cli GitHub repository and Google's Antigravity migration guide, checked on 16 November 2026. The latest stable release at that point was v0.68.0.
Is Gemini CLI Still Free in 2026?
No, not for individuals. The gemini-cli README now says it plainly: "Free individual access and Google AI Pro / Ultra (Google One) moved to Antigravity CLI on June 18, 2026."
So the question to ask is which tool fits your account:
| You have… | Use | Why |
|---|---|---|
| A free Google account | Antigravity CLI (agy) | Free individual access moved there |
| Google AI Pro or Ultra | Antigravity CLI (agy) | Google One plans moved there too |
| Gemini Code Assist Standard or Enterprise | Gemini CLI (gemini) | Gemini CLI is now built for these licences |
| Code Assist for GitHub on Google Cloud | Gemini CLI | Access is unchanged |
| A paid Gemini API key or Vertex AI | Gemini CLI or Antigravity CLI | Gemini CLI still works with paid keys |
The repository describes Gemini CLI as "an open-source terminal agent maintained for enterprise Gemini Code Assist workflows on Google Cloud." The same README notes it is "not optimized for Gemini 4+" models; for those, Google points to Antigravity CLI.
If you're an individual developer, skip to Moving to Antigravity CLI. If you're on a team with Code Assist, or you pay for API usage, read on.
Gemini CLI Requirements
From the official installation page:
- Operating system: macOS 15+, Windows 11 24H2+ or Ubuntu 20.04+
- Runtime: Node.js 20.0.0 or newer
- Shell: Bash, Zsh or PowerShell
- Memory: 4 GB+ for casual use, 16 GB+ for heavy use
- An internet connection
Check your Node.js version first:
node --versionStep 1: Install Gemini CLI
Pick one method:
# npm (all platforms)
npm install -g @google/gemini-cli
# Homebrew (macOS and Linux)
brew install gemini-cli
# MacPorts (macOS)
sudo port install gemini-cli
# Try it without installing
npx @google/gemini-cliThen start it in your project folder:
cd my-project
geminiGemini CLI ships on three release channels. Stable is the right choice for most people:
npm install -g @google/gemini-cli@latest # stable, weekly
npm install -g @google/gemini-cli@preview # preview, weekly
npm install -g @google/gemini-cli@nightly # nightly, dailyOn Google Cloud Shell and Cloud Workstations, Gemini CLI is already installed.
Security tip: install only from the official @google/gemini-cli package, and check the spelling. Fake packages with similar names are a common way attackers get into developer machines. My npm supply chain security guide explains how to protect yourself.
Step 2: Sign In (Authentication)
Gemini CLI supports three ways to authenticate. Run gemini and choose one, or switch later with the /auth command.
Option 1: Sign in with Google (Code Assist licences)
Choose Sign in with Google and complete the browser login. Your credentials are cached for later sessions. If your access comes from an organisation, Google Workspace or a Code Assist licence, set your Google Cloud project first:
export GOOGLE_CLOUD_PROJECT="your-project-id"In PowerShell:
$env:GOOGLE_CLOUD_PROJECT="your-project-id"Option 2: Gemini API key
Create a key in Google AI Studio, then set it before starting Gemini CLI:
export GEMINI_API_KEY="your-api-key"
gemini$env:GEMINI_API_KEY="your-api-key"
geminiChoose Use Gemini API key when asked. The quota page lists the unpaid API-key tier at 250 requests per user per day, Flash model only, so for real work you'll want a paid key.
Option 3: Vertex AI
For Google Cloud projects, set your project and region, then authenticate with Application Default Credentials:
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
gcloud auth application-default login
geminiChoose Vertex AI. A service account key (GOOGLE_APPLICATION_CREDENTIALS) or a Google Cloud API key (GOOGLE_API_KEY) also work. If you use ADC, unset GEMINI_API_KEY and GOOGLE_API_KEY first so they don't take priority.
Keep keys out of your shell history
Instead of exporting keys each time, put them in an env file that Gemini CLI loads automatically:
# ~/.gemini/.env (or .gemini/.env in a project)
GEMINI_API_KEY=your-api-keyOnly the first .env file found is loaded; files are not merged. Add .gemini/.env to .gitignore so a key never ends up in your repository.
Limits
Daily request limits depend on how you sign in. The official quota page lists, per user per day: 1,500 for Code Assist Standard and 2,000 for Code Assist Enterprise, while Vertex AI uses a shared quota or provisioned throughput. Requests are also limited per minute. Check your own usage at any time with:
/stats modelStep 3: Give Gemini CLI Project Context with GEMINI.md
GEMINI.md is a Markdown file of instructions that Gemini CLI sends to the model with every prompt: your stack, commands and rules. It is the single biggest improvement you can make to the results.
The fastest start is the built-in generator. Inside a session, run:
/initIt analyses your project and writes a GEMINI.md you can edit. A good one looks like this:
# Project: Store API
## Stack
- Laravel 12, PHP 8.2, MySQL
- Tests: php artisan test (must pass before you finish)
## Rules
- Validate input with Form Requests, never in controllers
- Never edit migrations that have already run in production
- Keep changes small and explain them in plain EnglishGemini CLI loads context files from three levels and combines them:
- Global:
~/.gemini/GEMINI.mdfor personal preferences across all projects - Project:
GEMINI.mdin your project root and parent folders - Subfolders: files in a folder are picked up when Gemini CLI works with files there
You can split long instructions into separate files with imports, such as @./docs/coding-style.md.
Useful memory commands:
/memory show: see the full combined context/memory list: see which files are loaded/memory refresh: reload after editing (some docs pages call it/memory reload)
Use AGENTS.md instead
If your project already has an AGENTS.md for other agents such as Codex or Claude Code, tell Gemini CLI to read it too in settings.json:
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}Step 4: Configure settings.json
Gemini CLI reads settings from JSON files at several levels:
- User:
~/.gemini/settings.json - Project:
.gemini/settings.jsonin your project root - System:
/etc/gemini-cli/settings.jsonon Linux,C:\ProgramData\gemini-cli\settings.jsonon Windows
Project settings override user settings. Command-line flags and environment variables override both.
A practical starting point:
{
"general": {
"defaultApprovalMode": "default",
"checkpointing": { "enabled": true }
},
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}general.defaultApprovalMode:defaultasks before each action,auto_editapproves file edits automatically, andplanis read-only.general.checkpointing.enabled: saves a snapshot before changes so you can undo them with/restore(restart after changing it).model.name: pins a model; you can also switch inside a session with/model.
Settings files support environment variables such as $MY_TOKEN, so secrets can stay out of the file itself.
Step 5: Everyday Commands
Three kinds of input do most of the work:
@src/routes/api.php Explain how authentication works here.
!git status
/stats session@adds files or folders to the prompt. Git-ignored files are left out by default.!runs a shell command directly. On Windows it runs through PowerShell. A lone!switches shell mode on and off./runs a built-in command.
The slash commands worth learning first:
| Command | What it does |
|---|---|
/init | Generate a GEMINI.md for the project |
/auth | Change how you sign in |
/model | Choose the model |
/memory | Show, list or reload context files |
/mcp | List MCP servers and their tools |
/chat | Save and resume conversations |
/restore | Undo file changes from a tool call (needs checkpointing) |
/compress | Replace a long conversation with a summary |
/clear | Start a fresh session |
/stats | Show usage for the session or model |
You can also add custom commands as .toml files in ~/.gemini/commands/ or .gemini/commands/ in a project, for prompts you repeat often.
Step 6: Connect MCP Servers
MCP (Model Context Protocol) lets Gemini CLI use outside tools, such as a database, GitHub or your own API. Add servers under mcpServers in settings.json.
A local server that runs as a command (here, your own Node.js MCP server):
{
"mcpServers": {
"my-tools": {
"command": "node",
"args": ["./mcp/server.js"],
"env": { "API_TOKEN": "$MY_API_TOKEN" },
"timeout": 30000
}
}
}A remote server over HTTP:
{
"mcpServers": {
"my-api": {
"httpUrl": "https://example.com/mcp",
"headers": { "Authorization": "Bearer $MY_API_TOKEN" }
}
}
}Then check the connection inside Gemini CLI:
/mcpEach server shows as connected, connecting or disconnected, with its tools. Two safety notes:
- Leave
trustoff (the default), so Gemini CLI asks before calling a server's tools. - Use
includeToolsorexcludeToolsto limit what a server can do.
Step 7: Stay in Control: Approval Modes, Checkpoints and Sandboxing
By default, Gemini CLI asks before it edits files or runs commands. You can change that per session:
gemini --approval-mode=auto_edit # approve file edits, still ask for commands
gemini --approval-mode=plan # read-only: plan without changing anything
gemini --yolo # approve everything (use only in a sandbox)YOLO mode can only be turned on from the command line, not from settings, which is a sensible guard.
Sandboxing runs tools in an isolated environment:
gemini --sandboxOn macOS it uses Seatbelt; with Docker or Podman it uses a container image; on Windows there's a native sandbox. Note that the Windows sandbox changes the folder's integrity level, and that change stays after the session. The docs give this command to reset it:
icacls "C:\path\to\project" /setintegritylevel MediumWith checkpointing on (Step 4), /restore puts files back the way they were before a tool changed them, and pressing Esc twice (/rewind) rewinds the conversation.
Step 8: Use Gemini CLI in Scripts and CI (Headless Mode)
Pass a prompt with -p and Gemini CLI runs once and exits, which is ideal for scripts:
gemini -p "Summarise the changes in the last 5 commits"For automation, ask for structured output:
gemini -p "List the TODO comments in src/" --output-format jsonjsonreturns one object withresponse,statsand an optionalerror.stream-jsonemits events as they happen (init,message,tool_use,tool_result,error,result).
Exit codes make failures easy to detect: 0 for success, 1 for a general or API error, 42 for an input error and 53 when the turn limit is exceeded.
To set up GitHub Actions that triage issues and review pull requests with Gemini, run /setup-github inside Gemini CLI.
Extensions
Extensions bundle MCP servers, commands and context into one install:
gemini extensions install https://github.com/gemini-cli-extensions/workspace
gemini extensions listBrowse the official gallery at geminicli.com/extensions. If you move to Antigravity CLI later, extensions convert into Antigravity plugins (see below).
Moving from Gemini CLI to Antigravity CLI
If you're an individual developer, Antigravity CLI is now Google's terminal agent for you. Google's migration guide says it "preserves backward compatibility with the core developer-experience constructs popularized by Gemini CLI."
1. Install agy. On macOS and Linux:
curl -fsSL https://antigravity.google/cli/install.sh | bashOn Windows (PowerShell):
irm https://antigravity.google/cli/install.ps1 | iex2. Run agy in your project. On the first run, if you have Gemini CLI configuration, it shows a checklist to convert your extensions and global settings, and moves your session tokens into your operating system's keyring.
3. Import extensions explicitly if you skipped that step:
agy plugin import geminiWhat carries over, and what needs your attention:
| Gemini CLI | Antigravity CLI |
|---|---|
GEMINI.md, AGENTS.md, ~/.gemini/GEMINI.md | Read as before, no changes needed |
| Extensions | Converted to plugins with agy plugin import gemini |
MCP servers in settings.json | Move to ~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (project) |
Remote MCP url / httpUrl | Rename the key to serverUrl |
Project skills in .gemini/skills/ | Move them to .agents/skills/ by hand |
| Custom themes and visual tweaks | May not be supported |
For the full Antigravity setup, including the IDE and Agent Manager, see my Google Antigravity setup guide.
Gemini CLI Troubleshooting
- "Sign in with Google" no longer works on a personal account. Expected since 18 June 2026: free and Google One access moved to Antigravity CLI. Use
agy, or a paid API key. - Quota errors. Check
/stats model. The unpaid API-key tier allows only 250 Flash requests a day. - An API key or Vertex settings are ignored. Another auth variable may be taking priority. Unset the ones you don't use, and remember only the first
.envfile is loaded. geminiis not recognised. Make sure Node.js 20+ is installed and npm's global folder is on your PATH, or usenpx @google/gemini-cli.- A folder became read-only after using the Windows sandbox. Reset it with the
icacls … /setintegritylevel Mediumcommand from Step 7. - The agent ignores your rules. Run
/memory listto confirm your GEMINI.md is loaded, then/memory refreshafter editing it.
Gemini CLI vs Claude Code vs Codex CLI
All three are terminal coding agents that read your project, edit files and run commands. The differences are mostly about the account you have and the models you want:
- Gemini CLI: best if your company has Gemini Code Assist or runs on Google Cloud with Vertex AI.
- Antigravity CLI: Google's choice for individuals, with the newest Gemini models.
- Claude Code: Anthropic's agent, in the terminal and VS Code. See my Claude Code setup guide.
- Codex CLI: OpenAI's agent, which can also hand tasks to the cloud. See my Codex CLI setup guide.
All of them read project instructions from a Markdown file (GEMINI.md, CLAUDE.md or AGENTS.md), so one well-written AGENTS.md keeps your rules consistent whichever agent you use. For a direct comparison of two of them, read Claude Code vs Codex.
Related Guides
- Google Antigravity Setup Guide →The IDE, Agent Manager and agy CLI.
- Claude Code Setup Guide →Install and configure Claude Code in VS Code and the terminal.
- OpenAI Codex CLI Setup Guide →Codex in the terminal, with cloud tasks.
- Google Jules Is Shutting Down →Another part of Google's move to Antigravity.
- AI tools directory →Compare coding agents, plans and prices.
Frequently Asked Questions
How do I install Gemini CLI?
Install Node.js 20 or newer, then run npm install -g @google/gemini-cli (or brew install gemini-cli on macOS and Linux). Start it with gemini in your project folder and choose how to sign in.
Is Gemini CLI free?
Not for individuals since 18 June 2026. Free accounts and Google AI Pro and Ultra subscribers moved to Antigravity CLI. Gemini CLI now serves Gemini Code Assist Standard and Enterprise licences and paid Gemini API or Vertex AI keys. An unpaid API key is limited to 250 Flash requests a day.
What replaced Gemini CLI for individual users?
Antigravity CLI, run with the agy command. It reads the same GEMINI.md and AGENTS.md files, and agy plugin import gemini converts Gemini CLI extensions into Antigravity plugins.
Where does GEMINI.md go?
Put a global file at ~/.gemini/GEMINI.md and a project file at your project root. Gemini CLI also reads GEMINI.md files from parent folders and from subfolders it works in, and combines them. Run /init to generate one.
Can Gemini CLI read AGENTS.md?
Yes, if you configure it. Set "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } in settings.json.
How do I add an MCP server to Gemini CLI?
Add it under mcpServers in ~/.gemini/settings.json or .gemini/settings.json, with a command and args for local servers or an httpUrl for remote ones. Then run /mcp to check that it's connected.
How do I use Gemini CLI in a script?
Use headless mode: gemini -p "your prompt". Add --output-format json for machine-readable output, and check the exit code (0 means success).
How do I update Gemini CLI?
Run npm install -g @google/gemini-cli@latest for the stable channel, or brew upgrade gemini-cli if you installed it with Homebrew.
Conclusion
Gemini CLI is still a capable, open-source terminal agent, but in 2026 it's a tool for teams with Gemini Code Assist and for paid API or Vertex AI users. If that's you, install it, sign in the way your licence expects, write a good GEMINI.md, and add MCP servers, checkpointing and a sandbox as you need them. If you're an individual developer, go straight to Antigravity CLI: your GEMINI.md comes with you, and one import command brings your extensions across.
