Gemini CLI: Google's Terminal Agent, Installed and Judged

The gap Gemini CLI fills, and for whom

Most coding assistants live inside an editor or a browser tab. Gemini CLI takes the opposite position: the README describes it as an open-source AI agent that brings Gemini into your terminal, with what it calls the most direct path from your prompt to the model. That framing matters, because the tool is not a chat window with syntax highlighting. It reads files, runs shell commands, fetches web pages and grounds answers with Google Search, all from a prompt you type in a shell.

The audience is narrow and specific. Developers who already live in a terminal and want an agent that can touch the working directory. People who need scripted, non-interactive runs, since the README shows a -p flag for one-shot prompts. Teams that want an agent inside GitHub workflows through the separate run-gemini-cli Action. If your daily work happens in a GUI and you never open a shell, the value proposition shrinks to almost nothing.

One design choice stands out. The README lists a free tier of 60 requests per minute and 1,000 requests per day with a personal Google account, no API key management, and access to Gemini 3 models with a 1M token context window. That is generous for individual use, and it is the main reason people try the tool at all. The catch is that quota terms are external to the repository and can change without a version bump.

How the agent loop is put together

The repository is a TypeScript monorepo. The root package.json declares workspaces under packages/*, and the Dockerfile copies package manifests for packages/cli, packages/core, packages/vscode-ide-companion, packages/devtools, packages/sdk, packages/test-utils and packages/a2a-server. So the CLI is a thin front end over a core library, with an SDK and an A2A server shipped alongside it. That split is visible in the build too: the Dockerfile runs npm pack for packages/core and packages/cli separately, producing two artifacts.

The Dockerfile builds in two stages. Stage one is node:20-slim, installs git because generate-git-commit-info.js needs it, copies package manifests first for layer caching, runs npm ci --ignore-scripts with HUSKY=0, then copies source and builds. Stage two is another node:20-slim with a minimal package set. The build arg GIT_COMMIT is passed in rather than copying the whole .git directory, which keeps the image smaller. A sandbox image URI is pinned in package.json under config.sandboxImageUri, so sandboxed execution is a first-class path rather than an afterthought.

On the agent side, the README names the built-in tools: Google Search grounding, file operations, shell commands, web fetching. MCP support extends that set with external servers, and the README points at a Vertex AI creative studio experiment as an example of media generation through MCP. Behaviour is steered by GEMINI.md context files, and sessions can be checkpointed and resumed. The repository also carries .geminiignore alongside .gitignore, which suggests file-tool traversal respects an ignore list. The README does not spell out the matching rules for .geminiignore, so treat that as undocumented until you read the source.

Installing Gemini CLI and running a first prompt

The README offers four install paths plus a no-install path. The fastest check is npx, which downloads and runs the published package without a global install. Expect a first-run authentication prompt rather than an answer.

npx @google/gemini-cli

For a permanent install on Node, the package is @google/gemini-cli on npm. The root package.json sets engines.node to >=20.0.0, so check your Node version before installing.

npm install -g @google/gemini-cli

macOS and Linux users can use Homebrew instead, and macOS alone has a MacPorts formula. Both install the same published package.

brew install gemini-cli

If you are in a restricted environment without system Node, the README gives a conda route that creates an environment with nodejs from conda-forge and then installs the CLI inside it.

conda create -y -n gemini_env -c conda-forge nodejs
conda activate gemini_env
npm install -g @google/gemini-cli

Authentication comes next, and the choice is not cosmetic. Sign in with Google uses OAuth and the free tier of 60 requests per minute and 1,000 per day. A Gemini API key suits people who want to pick a specific model or pay for higher limits. Vertex AI is aimed at enterprise workloads with a billing account.

export GEMINI_API_KEY="YOUR_API_KEY"
gemini

With auth done, start the interactive session in your project directory. The README shows --include-directories for pulling in sibling folders and -m for model selection, which is useful when you want flash instead of the default.

gemini --include-directories ../lib,../docs
gemini -m gemini-2.5-flash

For scripting, -p returns a plain text response and exits. The README notes that more advanced scripting, including JSON parsing and error handling, is documented elsewhere; the truncated README does not show those flags, so check the docs before wiring it into CI.

gemini -p "Explain the architecture of this codebase"

Release channels are the real operational risk

Gemini CLI publishes on three npm tags, and the README is unusually blunt about what each one means. Nightly ships every day at UTC 00:00 from main and, in the README's words, should be assumed to have pending validations and issues. Preview ships weekly at UTC 23:59 on Tuesdays and, again quoting the README, will not have been fully vetted and may contain regressions. Stable ships weekly at UTC 20:00 on Tuesdays and is the previous preview plus bug fixes and validations.

That is a fast cadence. If your team pins dependencies and reviews changelogs before upgrading, a weekly stable promotion means you are reviewing a moving target roughly fifty times a year. The repository's own recent releases are all v0.59.0-nightly builds, which tells you where most of the published volume sits. The package.json version is a nightly string as well.

The wrong tool case is straightforward. If you need a frozen agent version that will not shift under a compliance review, or if you cannot absorb a regression introduced by a weekly promotion, this is not the project for you yet. Nothing in the README describes a long-term support tag or a slow channel. The other failure mode is quota. The free tier is documented as 60 requests per minute and 1,000 per day, and agentic loops burn requests faster than chat because a single task can trigger many model calls. The README does not document what happens when you hit the ceiling mid-session, so plan around it rather than through it.

Claude Code is the comparison people actually make

The search data around this project is full of Gemini CLI versus Claude Code, and the difference is not just the model. Claude Code is Anthropic's terminal agent and is distributed as its own product with its own authentication and billing; Gemini CLI is Apache-2.0 source you can read, fork, build from the Makefile, and ship in a Docker image you control. That licensing difference is the one that matters for anyone who needs to inspect or modify the agent loop.

The second difference is the extension surface. Gemini CLI documents MCP support for custom integrations and ships an SDK package plus an A2A server in the same monorepo. If you want to embed the agent in another system rather than run it interactively, those packages are the entry point. The README does not describe an equivalent embedding story for the alternative.

The third difference is the auth model. Gemini CLI offers three documented paths: Google OAuth with a free tier, a Gemini API key, and Vertex AI for enterprise workloads. That last one is the reason a Google Cloud shop might pick this over anything else, since it reuses existing billing and infrastructure. The trade-off is that you inherit Google's quota and terms, which are external to the repository and not versioned with it.

Licence, upgrade cost and what the repository does not say

The licence is Apache-2.0, stated in the README and present as a LICENSE file at the repository root. For most teams that is the permissive end of the spectrum: you can read, modify and redistribute, with the usual notice and patent terms attached. This is not legal advice, and the third_party directory in the repository suggests bundled dependencies with their own notices that a legal review should read directly.

Upgrade cost is the interesting part. Because stable promotes weekly, the practical cost is not the install command but the verification loop. The repository ships a Makefile with make install, make build, make test, make lint, make format and make preflight, so anyone building from source has a one-command gate. For consumers, the equivalent gate is running the published package against your own repository before promoting it across a team.

What the README does not cover is rollback. It documents how to install preview, latest and nightly tags but says nothing about pinning a version or reverting after a bad promotion. If you install with a floating tag, you have no documented way back except specifying an explicit version yourself. That is a real gap for anyone running this in CI.

Editorial conclusion

Adopt Gemini CLI if you already work in a terminal and want Gemini models with built-in file, shell and Google Search tools under a permissive licence. Skip it if you need a vetted, slow-moving release, since the published channels are nightly, preview and weekly stable. Before rolling it out to a team, verify the current quota terms for the OAuth free tier and confirm whether your Google Cloud project must be set for a Code Assist licence.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes