Gemini CLI Getting Started: Install, Auth and Free Quotas

Gemini CLI needs Node.js 20 or later, and signing in with a Google account gives 1,000 requests a day for free. Install options, auth choices and GEMINI.md.

Gemini CLI is an open-source tool for using Google’s Gemini models from the terminal. This guide covers requirements and installation, the three ways to authenticate and their free quotas, a first session, GEMINI.md and settings files, and a few facts set side by side with Claude Code. If you are still choosing a tool, start with how to choose a coding agent.

On 2026-10-28 our test environment (macOS, Node.js v26.12.1) checked the package on npm: npm view @google/gemini-cli version engines returned 0.66.0 and { node: '>=20' }. We also ran npx -y @google/[email protected] --version, which printed 0.66.0, and --help, which listed the gemini mcp, gemini extensions, gemini skills and gemini hooks subcommands along with -p / --prompt, --approval-mode (default, auto_edit, yolo, plan) and -r / --resume. We did not log in, set no API key and called no model (not run). Everything else here comes from the docs in the project’s repository, checked the same day.

Requirements and installation

The docs recommend:

• OS: macOS 15+, Windows 11 24H2+, or Ubuntu 20.04+
• RAM: 4GB+ for casual use (short sessions, common edits), 16GB+ for long sessions and large codebases
• Node.js 20.0.0+
• Shell: Bash, Zsh or PowerShell
• A location supported by Gemini Code Assist, and an internet connection

The install options listed are:

# npm
npm install -g @google/gemini-cli

# Homebrew (macOS/Linux)
brew install gemini-cli

# MacPorts (macOS)
sudo port install gemini-cli

# Run without installing
npx @google/gemini-cli

Anaconda is also listed for restricted environments: create a conda environment with nodejs from conda-forge, then run the same npm install -g inside it. Gemini CLI comes pre-installed on Cloud Shell and Cloud Workstations. The command is gemini. There are three release channels: stable (weekly, the latest tag and the default), preview (weekly, @preview) and nightly (@nightly). We copied these commands from the docs and did not run any of them (not run).

Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/installation.mdx (checked 2026-10-28)

For non-interactive runs, the docs list -p / --prompt, and --approval-mode with default, auto_edit, yolo and plan (plan is marked as still under development). -r / --resume resumes a previous session, with latest as the default.

Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md (checked 2026-10-28)

Authentication and free quotas

You can sign in with a Google account, use a Gemini API key, or use Vertex AI. The docs give these daily limits:

The unpaid API key tier sends requests to Flash models only. Vertex AI Express mode gives you 90 days before you need to enable billing. Tiers not in the table, including Google AI Plus, are not supported. Requests are also limited per user per minute. These numbers can change, so check the page before you pay for anything.

Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/quota-and-pricing.md (checked 2026-10-28)

The docs recommend signing in with Google for most users. An API key goes in the GEMINI_API_KEY environment variable. Company, school and Google Workspace accounts need a Google Cloud project, set through GOOGLE_CLOUD_PROJECT or GOOGLE_CLOUD_PROJECT_ID. Headless mode needs an API key or Vertex AI.

Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/authentication.mdx (checked 2026-10-28)

The terms that apply depend on how you authenticate. A Google account falls under the Gemini Code Assist terms and privacy notices, a Gemini API key under the Gemini API terms (separate for unpaid and paid services), and Vertex AI under the Google Cloud terms. The docs also say that accessing the services behind Gemini CLI through third-party software, for example by reusing Gemini CLI’s OAuth sign-in, violates the terms. Usage statistics can be turned off with privacy.usageStatisticsEnabled: false in settings.

Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/tos-privacy.md (checked 2026-10-28)

A first session

Start it in a dummy project. The first run asks you to pick a sign-in method.

cd ~/projects/todo-app
gemini

A safe first prompt is a question that doesn’t touch the code:

Describe how this project is organized and how to run its tests.

This needs a login, so we did not run it (not run). Commands you will use early on:

Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/commands.md (checked 2026-10-28)

GEMINI.md and settings

GEMINI.md holds instructions that are sent to the model with every prompt. The CLI loads them from three places and joins everything it finds:

• ~/.gemini/GEMINI.md, for all projects
• GEMINI.md in the workspace directories and their parent directories
• GEMINI.md files found just in time, when a tool touches a directory, from there up to a trusted root

A line such as @./components/instructions.md imports another file. The context.fileName setting changes the file name and accepts a list, such as ["AGENTS.md", "CONTEXT.md", "GEMINI.md"]. /memory reload re-scans all of them.

Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md (checked 2026-10-28)

Settings live in settings.json: ~/.gemini/settings.json for the user and .gemini/settings.json in the project root. Project settings override user settings, and a system settings file for administrators overrides both.

Source: https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md (checked 2026-10-28)

Compared with Claude Code

We only list facts we could confirm in both sets of docs. This is not a ranking.

Source: https://code.claude.com/docs/en/setup (checked 2026-10-28) Source: https://code.claude.com/docs/en/memory (checked 2026-10-28) Source: https://code.claude.com/docs/en/settings (checked 2026-10-28)

For the other CLIs, see getting started with Claude Code and getting started with Codex CLI. For keeping an instruction file short, see trimming CLAUDE.md.

Summary

• Gemini CLI needs Node.js 20.0.0 or later. Install it with npm install -g @google/gemini-cli, Homebrew or MacPorts, and run gemini. The npm version on 2026-10-28 was 0.66.0.
• A Google account on Gemini Code Assist for individuals allows 1,000 requests a day. The unpaid API key tier allows 250, Flash only.
• The terms and privacy notice that apply change with the auth method.
• Instructions go in GEMINI.md, loaded from ~/.gemini/, the workspace and its parents, and directories tools touch.
• Settings are in ~/.gemini/settings.json and .gemini/settings.json, with the project file taking precedence.
• /stats model shows usage against your quota.