← All posts

Guide

Gemini CLI: install, configure, and where it fits next to Claude Code and Codex

Three terminal coding agents get installed at any scale in 2026: Claude Code, Codex CLI, and Google's Gemini CLI. The first two get written about constantly. The third mostly shows up as a row in someone's comparison table, which is odd, because it is the only one of the three you can run seriously without paying anyone.

This is the practical guide: install it, pick the right authentication path, understand what the free tier actually gives you, wire up the project-context file and settings, and then the part that matters most — a concrete account of what Gemini CLI does better than the other two, and where it is plainly behind. No vendor pitch in either direction.

Install it

Gemini CLI is an npm package under the Apache 2.0 licence. Node 20 or newer is a hard requirement — the package declares "engines": { "node": ">=20" } and will refuse to run on anything older.

npm install -g @google/gemini-cli

There are three other supported routes, all documented at the same tag:

• Homebrew (macOS and Linux): brew install gemini-cli.
• MacPorts: sudo port install gemini-cli.
• No install at all: npx @google/gemini-cli, which is the fastest way to try it before deciding.

Then run gemini in a repo. It is pre-installed in Google Cloud Shell and Cloud Workstations, so if you already live in either, you have it.

Two things about releases that will bite you if you do not know them. First, there are three npm tags — latest (stable, cut weekly on Tuesdays), preview (also weekly, explicitly not fully vetted) and nightly (daily, straight off main). Second, general.enableAutoUpdate defaults to true, so the stable channel will quietly move under you between Tuesdays. That is usually what you want on a laptop and never what you want on a build agent. Pin the version in CI, or set that key to false.

Authenticate: three doors, three different deals

This is the decision that matters. All three paths run the same binary; they differ in what you pay, what quota you get, which models you can reach, and whose terms of service apply.

1 — Sign in with Google (the free one)

Run gemini, choose Sign in with Google, complete the browser flow, and the credentials cache locally. No key to manage, no billing account, no card. For a personal Google account this puts you on Gemini Code Assist for individuals.

You need a Google Cloud project on top of this only if one of three things is true: you are signing in with a company, school or Workspace account; you have a Gemini Code Assist licence from the Google Developer Program; or you have a paid Code Assist subscription. In those cases set GOOGLE_CLOUD_PROJECT to the project ID. Everyone else can skip it.

2 — Gemini API key

export GEMINI_API_KEY="…"   # from aistudio.google.com/apikey
gemini

Then pick Use Gemini API key at the prompt. This is the path if you want to name an exact model rather than let the CLI route for you, or if you want usage-based billing with no daily wall.

3 — Vertex AI

For enterprise. Set GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION, then authenticate one of three ways: application default credentials via gcloud auth application-default login, a service account JSON key pointed at by GOOGLE_APPLICATION_CREDENTIALS, or a Google Cloud API key in GOOGLE_API_KEY. If you previously exported GEMINI_API_KEY or GOOGLE_API_KEY you must unset them before ADC will be used — the docs are explicit about that, and it is the most common Vertex setup failure. Vertex also has an Express mode that runs for 90 days before you have to enable billing.

What the free tiers actually give you

Numbers below are quoted from the repository's own quota page at tag v0.53.1, read on August 2, 2026. This is the single fastest-moving fact about Gemini CLI, so the date is doing real work here.

Three honest caveats, in descending order of how much they will annoy you.

• The unit is a model request, not a token and not a turn. One thing you ask for can consume several requests as the agent reads files, calls tools and re-prompts itself. A 1,000-request day is a good day of real work, not 1,000 questions. /stats model shows where you stand mid-session, and a usage summary prints on exit.
• The repo contradicts itself about the API-key free tier. At the same v0.53.1 tag, docs/resources/quota-and-pricing.md says 250 requests a day on Flash only, while the top-level README.md advertises "1000 requests/day with Gemini 3 (mix of flash and pro)". Both files ship in the same release. Believe neither until /stats model tells you which one your account is on.
• Headless runs need an environment variable. Non-interactive mode reuses a cached credential if one exists, but on a fresh machine or a CI runner you must supply GEMINI_API_KEY or Vertex credentials. There is no browser to complete the OAuth flow in.

One more gotcha worth internalising: Gemini reads a .gemini/.env file, searching upward from the current directory and then falling back to ~/.gemini/.env. Variables load from the first file found, not merged. A stray project-level .env therefore silently masks your home one rather than adding to it.

GEMINI.md, and how it relates to AGENTS.md and CLAUDE.md

Gemini's project-instruction file is GEMINI.md. Same job as its two rivals: build and test commands, conventions, directories to leave alone. The loading model is more interesting than either of theirs, and one default is a trap.

Context comes from three levels, concatenated:

• Global: ~/.gemini/GEMINI.md, applied to every project.
• Workspace: GEMINI.md in your workspace directories and their parents.
• Just-in-time: when a tool touches a file or directory, the CLI scans that directory and its ancestors for GEMINI.md up to a trusted root, and loads what it finds — at that moment, not up front.

That third tier is the genuinely good idea. In a monorepo, per-package instructions cost nothing until the agent actually opens that package. Claude Code and Codex both support nested instruction files, but the nested content is discovered by convention rather than pulled in lazily on tool access. The CLI footer shows how many context files are currently loaded, and /memory show prints the exact concatenation being sent to the model — run it once, because it is usually longer than you think.

You can split a large file with @path imports, the same syntax Claude Code uses:

# GEMINI.md

@./docs/conventions.md
@../shared/style-guide.md

Now the trap. Gemini CLI does not read AGENTS.md out of the box. In the 0.53.1 source, DEFAULT_CONTEXT_FILENAME is the literal string 'GEMINI.md', and the context.fileName setting that would change it defaults to undefined. Point Gemini at a repo that carries a carefully maintained AGENTS.md and no GEMINI.md, and it starts with no project context at all — silently, because nothing is missing from its point of view.

The one-line fix, in .gemini/settings.json:

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

With that in place the cross-tool file is your source of truth and GEMINI.md becomes the thin Gemini-specific layer — exactly the arrangement we recommend for CLAUDE.md vs AGENTS.md, now covering a third agent. If you run more than one CLI in the same repo, set this before you write a single line of GEMINI.md. Otherwise you will end up maintaining three files that drift.

settings.json: where it lives, what it looks like

Configuration is JSON, and there are four possible files layered in a fixed order — system defaults (lowest), user, project, system overrides (highest), with environment variables and command-line flags on top of all of it. In practice you will touch two:

• User: ~/.gemini/settings.json
• Project: <repo>/.gemini/settings.json — overrides the user file

The other two, system-defaults.json and settings.json under /etc/gemini-cli on Linux (C:\ProgramData\gemini-cli on Windows, /Library/Application Support/GeminiCli on macOS), exist so an administrator can set a floor and a ceiling around whatever developers do. That is a more complete enterprise story than either rival ships.

The shape is nested by category, not a flat bag of keys — general, ui, model, tools, security, context, mcp, hooksConfig, skills, experimental. A reasonable starting point:

{
  "general": {
    "defaultApprovalMode": "default",
    "enableAutoUpdate": false,
    "enableNotifications": true
  },
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  },
  "tools": {
    "useRipgrep": true
  },
  "security": {
    "folderTrust": { "enabled": true },
    "blockGitExtensions": true
  }
}

You do not have to hand-edit it: /settings opens a dialog over the same file. Values can reference environment variables with $VAR, ${VAR} or ${VAR:-fallback} syntax, which is how you keep a token out of a file you commit.

Four defaults worth knowing before you are surprised by them:

• general.defaultApprovalMode is "default" — it asks before each tool call. "auto_edit" auto-approves edits; "plan" is read-only. YOLO (approve everything) is deliberately not settable from the file at all: it exists only as --yolo or --approval-mode=yolo on the command line, and security.disableYoloMode can block even that.
• general.enableNotifications is false. Out of the box Gemini will not tell you it has finished or that it is waiting on you.
• model.compressionThreshold is 0.5 — context gets compressed at half the window, earlier than people expect.
• general.plan.modelRouting is true: Pro plans, Flash implements. Good for quota, occasionally surprising when the implementation feels dumber than the plan.

MCP servers

MCP support is complete and, in one respect, ahead of the field. All three transports are supported — stdio (a subprocess), SSE, and streamable HTTP. Declare servers under a top-level mcpServers object:

{
  "mcpServers": {
    "github": {
      "httpUrl": "https://api.example.com/mcp/",
      "headers": { "Authorization": "Bearer $GH_MCP_TOKEN" },
      "includeTools": ["list_issues", "read_issue"]
    },
    "local-db": {
      "command": "/usr/local/bin/db-mcp",
      "args": ["--readonly"],
      "trust": false
    }
  }
}

Or skip the JSON and use the shell, which is what most people end up doing:

gemini mcp add local-db /usr/local/bin/db-mcp --readonly
gemini mcp add --transport http github https://api.example.com/mcp/
gemini mcp list
gemini mcp disable github

The per-server keys that matter are trust (bypasses every confirmation for that server — use sparingly), and includeTools / excludeTools, an allowlist and a denylist over the tools a server exposes, with exclude winning ties. Above those, mcp.allowed and mcp.excluded gate which servers connect at all, which is the setting an administrator wants. OAuth flows are handled in-CLI and tokens are stored in ~/.gemini/mcp-oauth-tokens.json.

The part the others do not match: MCP resources, not just tools. Gemini discovers each server's resources/list, shows them under /mcp alongside tools and prompts, and lets you pull one into the conversation with the same @ syntax you use for files — @server://resource/path, with completion. If you have only ever used MCP for tool calls, that is a different and often better way to hand an agent a document. For the concepts underneath, our MCP guide applies unchanged; only the config file differs.

Extensions: the thing neither rival has

An extension is a single installable bundle containing any of: prompts, MCP servers, custom commands, themes, hooks, subagents and agent skills. One command, from a GitHub URL:

gemini extensions install https://github.com/gemini-cli-extensions/workspace
gemini extensions list

Google runs a public gallery of them. This is a genuine structural difference: Claude Code and Codex both let you install MCP servers, and Claude Code has skills and subagents, but neither has a first-party package format that ships all of those together with one command and a catalogue to find them in. If your team's conventions amount to "these four MCP servers, these six slash commands and this hook", Gemini is the only one of the three where that is one artefact.

Which is also the security problem, and Google clearly knows it: security.blockGitExtensions blocks installing or loading extensions from Git outright, and security.allowedExtensions takes a list of regex patterns that, when non-empty, becomes a strict allowlist overriding that block. On a work machine, set one of the two before anyone discovers the gallery.

Where Gemini CLI is genuinely ahead

• The free tier is real. A thousand model requests a day, no card, no API key, no subscription — just a Google account you already have. Claude Code needs a Claude subscription or API billing; Codex needs a ChatGPT plan. For a student, a hobbyist, or anyone evaluating whether terminal agents are worth it at all, this is not a small difference. It is the whole difference.
• Hooks reach the model, not just the tools. Eleven events, including BeforeModel and AfterModel (swap models, mock a response, redact output before it is shown) and BeforeToolSelection (filter which tools the model is even offered for this turn). Claude Code's hooks are excellent but they bracket tool calls and lifecycle moments; they do not sit between the agent and the model. If you want to enforce that no response containing a customer identifier ever renders, Gemini is the only one of the three where that is a supported interception point rather than a wrapper you write yourself.
• Lazy, per-directory context. The just-in-time GEMINI.md scan loads instructions when a tool actually reaches that part of the tree.
• Extensions as a distribution format, with a gallery. Covered above.
• Open source, Apache 2.0. Same category as Codex; Claude Code is distributed but not developed in the open. Every claim in this article was checked by reading the tagged source, which is a thing you can only do for two of the three.
• Administrative depth. Four-layer settings with a system override that beats the user, a folder-trust model, a regex allowlist for extensions, and a switch that disables YOLO mode even when someone passes the flag.

Where the other two are ahead

• Codex has an OS-enforced sandbox, on by default. This is the biggest gap. Gemini has sandboxing — macOS Seatbelt, Docker, Podman, gVisor, LXC — but it is opt-in, via -s or GEMINI_SANDBOX. Out of the box your protection is an approval prompt, which is a policy the agent process enforces on itself. Codex starts sandboxed and the kernel does the enforcing; see Codex CLI sandbox modes for what that buys you. Gemini's --approval-mode=plan is the closest equivalent and a good one — a documented, explicit allowlist of read-only tools, with writes confined to plan files under ~/.gemini/tmp/ — but it is still policy inside the process, not a wall outside it.
• The quota unit is opaque, and you cannot fully control it. "Model requests" is not something you can estimate before you spend it. Worse, the docs state plainly that the /model command and --model flag do not govern the models subagents use, so a session where you selected Flash can still bill Pro requests you did not choose. Codex and Claude Code meter differently, and neither hides which model ran.
• Ecosystem gravity is elsewhere. Most published hook scripts, subagent definitions, review workflows and blog-post recipes target Claude Code's event names and JSON contract. Gemini's events are its own (BeforeTool, not PreToolUse), so nothing ports without a rewrite. The capability is there; the community output is not, yet.
• Documentation quality is behind. The README and the quota page in the same release disagree about the free tier by a factor of four. That is a small thing that tells you a true thing about how fast this project is moving relative to how carefully it is being described.
• Model preference is a real factor and this article will not resolve it for you. Everything above is verifiable from source. Which model writes better code on your codebase is not, benchmark tables move monthly, and anyone telling you they have settled it is selling something. Run the same task through two of them for a week; that answer is worth more than any leaderboard. See Claude Code vs Codex CLI for the equivalent comparison between the other two.

So where does it fit?

Two clear cases, and one that is not.

If you pay for nothing yet, install Gemini CLI first. It is the only credible terminal agent with a free path that does not expire, and a thousand requests a day is genuinely a working day. Set context.fileName, write a short instruction file, and use it.

If you already pay for Claude Code or Codex, install Gemini as the second opinion. Not the replacement — the second opinion. The value of a second agent is almost entirely in it being a different vendor's model, because two models from the same lab tend to be wrong about the same things. Gemini is the cheapest way to add a decorrelated one, and gemini -p "…" with --output-format json makes it scriptable when you want that opinion without a second terminal.

What it is not: a drop-in for a Claude Code setup you have invested in. If you have a repo full of hooks, subagents and slash commands, none of it ports. Budget a day, or run both and let the instruction file be the only shared artefact.

Where Backgrind fits

Backgrind is a bring-your-own-CLI overlay: it wraps the agent you already run — Gemini CLI included — in an always-on-top window that floats over whatever else is on screen, and pings you when the agent finishes or needs a decision. That last part is worth something specific here, because Gemini ships with general.enableNotifications set to false, and even switched on it notifies through the terminal it is running in. If the terminal is behind a browser, or behind a game, that is a notification you will not see. Run Gemini in one of several agent tabs and the pings find you instead.

One honest limitation, since this article has been picky about defaults: our Fusion council — which puts one hard question to several of your CLIs at once and has a chairman judge the answers — does not currently offer a Gemini seat. Council members read your repo, so we only seat a CLI whose read-only mode is a flag we have pinned and verified; today that is Claude Code and Codex. --approval-mode=plan is the obvious candidate, and it is exactly the kind of thing this article exists to check. Until then, Gemini runs in the overlay like any other agent — it just does not sit on the panel.

New to the others? Install Claude Code or set up Codex CLI, then come back and run all three. See the overlay in the live demo.

Frequently asked questions