# gemini-cli: five install routes, three auth ceilings, three release clocks > Google's open-source terminal coding agent, published as @google/gemini-cli on npm for Node 20 and newer. The install path, the rate limit you get, and the stability you get are all decided by which of five install routes and three sign-in methods you pick. **google-gemini/gemini-cli** — An open-source AI agent that brings the power of Gemini directly into your terminal. - Repository: https://github.com/google-gemini/gemini-cli - Website: https://geminicli.com - Stars: 107,166 · Forks: 14,634 - Language: TypeScript - License: Apache-2.0 - Published: 2026-08-08 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/google-gemini-gemini-cli ## The published binary comes out of a seven-package workspace monorepo The installable name is @google/gemini-cli, and the root package.json is marked "private": true while the code lives under packages. Node 20 is the floor, declared as engines.node >=20.0.0. The root declares workspaces of packages/*, and the Dockerfile copies a package.json for cli, core, vscode-ide-companion, devtools, sdk, test-utils, and a2a-server before running npm ci, then packs only core and cli. Consequence for the reader: you are not installing a lone script, the terminal agent is the cli package sitting on a core library, and a from-source build has to compile that whole tree before anything runs. The Makefile spells the cost out, offering a plain build target and a separate build-all that it describes as building the main project and the sandbox. The same tree ships a vscode-ide-companion package, and the README points at a separate Gemini CLI GitHub Action for pull request reviews, issue triage, and @gemini-cli mentions. For a team that wants the agent inside GitHub rather than in a shell, that action is a different approach: the work runs on pull requests and issues instead of on one person's laptop. ## Five install routes, and only the npm ones carry release tags The README gives five ways in. npx runs the package with no installation at all: ```bash npx @google/gemini-cli ``` A global npm install puts a gemini command on your path: ```bash npm install -g @google/gemini-cli ``` Homebrew and MacPorts cover the same ground through system package managers: ```bash brew install gemini-cli ``` ```bash sudo port install gemini-cli ``` A fifth path creates a conda environment before installing the same npm package inside it. The three release channels are all npm tags, @preview, @latest, and @nightly. Consequence for the reader: the tags only steer an npm install. A Homebrew or MacPorts install is a separate formula or port, and the README documents no command for moving one of those onto a preview or nightly build, so a user on brew tracks whatever the formula happens to ship. npx has the opposite problem, since nothing is installed there is nothing to upgrade either, and every run resolves the package afresh. ## Preview, stable and nightly publish on three different clocks Stability here is a timing question. Preview releases go out weekly at UTC 23:59 on Tuesdays, and the README warns they have not been fully vetted and may contain regressions. Stable releases go out at UTC 20:00 on Tuesdays, described as the full promotion of the previous Tuesday's preview plus bug fixes and validations. Nightly releases publish daily at UTC 00:00 and carry all changes from main as of release time, with pending validations to assume. Consequence for the reader: a preview build you adopt on a Wednesday is running code the maintainers themselves asked you to help test, and promotion to stable waits for the following Tuesday, so a week of your work sits on the untested channel. The release list confirms the pace, with v0.64.0-nightly.20260930, v0.63.0-preview.0, and v0.63.0-nightly.20260929 all landing inside two days. ```bash npm install -g @google/gemini-cli@latest ``` ```bash npm install -g @google/gemini-cli@nightly ``` ## Three sign-in paths, and each one hands you a different ceiling Authentication is a choice between three ceilings rather than three conveniences. Signing in with Google through the browser flow gives a personal-account free tier of 60 requests a minute and 1,000 a day, Gemini 3 models, a 1M token context window, automatic model updates, and no API key to manage. A Gemini API key gives 1,000 requests a day across a mix of flash and pro, lets you choose specific models, and bills on usage past that. Vertex AI is positioned for enterprise and production, with higher limits tied to a billing account. ```bash export GEMINI_API_KEY="YOUR_API_KEY" ``` ```bash export GOOGLE_API_KEY="YOUR_API_KEY" export GOOGLE_GENAI_USE_VERTEXAI=true ``` A paid Gemini Code Assist License from an organization needs GOOGLE_CLOUD_PROJECT set before you start. Consequence for the reader: the free tier numbers are the real limit for an individual, and the README sends you to Google's own quota page for the details rather than restating them, so check that page before you commit a workflow to a per-minute ceiling. ## Non-interactive mode starts with one text example and no output format The scripting path is the -p flag, and the README's only example is a text response: ```bash gemini -p "Explain the architecture of this codebase" ``` For anything past that the README points to a longer scripting section covering how to parse JSON and handle errors, so the single command in the overview is the floor, not the contract. Consequence for the reader: if you are wiring this into CI, the flag shown here returns prose, and a machine-readable result depends on that further scripting documentation rather than on anything in the summary. Two other flags shape a plain interactive session. --include-directories widens the working set past the directory you launched from, and -m pins a specific model rather than taking the default. ```bash gemini --include-directories ../lib,../docs ``` ```bash gemini -m gemini-2.5-flash ``` ## GEMINI.md and checkpoints decide what a session remembers Context for a session comes from files rather than arguments. The README names custom context files, GEMINI.md, as the way to tailor behavior to a project, and the repository root carries its own GEMINI.md next to a .geminiignore and a .gemini directory, so the same files that configure a contributor configure the agent. Session continuity is handled by conversation checkpointing, which the README lists as a way to save and resume complex work. Consequence for the reader: what the agent reads about your project is whatever GEMINI.md and the surrounding dotfiles say, and a stale GEMINI.md steers every later session until you edit it. The README does not describe a versioned or validated format for that file, so nothing warns you that its instructions have drifted out of date. ## The sandbox image tracks a nightly version string package.json pins a sandbox container under config.sandboxImageUri, pointing at us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.64.0-nightly.20260929.gd75234cae, and the matching package version is 0.64.0-nightly.20260929.gd75234cae. The Dockerfile declares a runtime argument named SANDBOX_NAME with a default of gemini-cli-sandbox and sets SANDBOX and CLI_VERSION from build arguments. Consequence for the reader: the container reference is a nightly build tag, so the image your agent runs inside is versioned to a moving main branch rather than to a release you pinned, and the CLI and its sandbox can drift apart. A separate script named deflake re-runs the test suite under a fixed retry count, and the Makefile carries its own sandbox targets, build-sandbox and a docker variant of the integration test, which shows the container is a tested surface rather than an incidental image. ## Conclusion Gemini CLI suits an individual developer who wants a terminal coding agent without managing an API key, and who can live inside a 60 requests per minute personal free tier. It does not suit a team that needs a stable, pinned build on a schedule, because the only release channels are npm tags on moving branches and the Homebrew and MacPorts formulas are not tied to them. Before you adopt it, check two things: that you are on Node 20 or newer, which the package.json engines field requires, and the free tier ceiling on Google's own quota page, which the README defers to rather than restating. A team that needs structured output from -p should read the scripting section first, since the summary example returns text. ## FAQ ### Is Gemini CLI still free? Yes for a personal Google account. Signing in with Google gives a free tier of 60 requests per minute and 1,000 requests per day, with no API key to manage. A Gemini API key also gives a free tier of 1,000 requests a day, and Vertex AI raises limits when tied to a billing account. ### how to install gemini-cli Run it with no install using npx @google/gemini-cli, or install globally with npm install -g @google/gemini-cli, brew install gemini-cli, sudo port install gemini-cli, or inside a conda environment. Node 20 or newer is required. ### What exactly is Gemini CLI? It is Google's open-source AI agent for the terminal, written in TypeScript and released under the Apache 2.0 license as the npm package @google/gemini-cli. It brings Google Search grounding, file operations, shell commands, and web fetching into the command line, and it supports MCP servers for custom integrations. ### how to use gemini-cli Start a session with gemini in the current directory, widen it with gemini --include-directories ../lib,../docs, pin a model with gemini -m gemini-2.5-flash, or run one scripted request with gemini -p "Explain the architecture of this codebase". ### Is Gemini CLI discontinued? No. The repository is not archived, the last push was 2026-09-26, and three releases landed within two days, including v0.63.0-preview.0 and a nightly build. ## Sources - [Official documentation](https://geminicli.com) - [Official README](https://github.com/google-gemini/gemini-cli#readme) - [Project repository](https://github.com/google-gemini/gemini-cli) - [Release notes](https://github.com/google-gemini/gemini-cli/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/google-gemini-gemini-cli