The Cartographer · 11 min mission

Gemini CLI: Install & First Session

Choose Gemini CLI or Antigravity for your account, then install and authenticate the supported path.

gemini-cliinstallationauthenticationquotasgetting-startedFact-checked 2026-08-01

Gemini CLI is Google's open-source terminal coding agent for enterprise and API-key workflows. The npm package is @google/gemini-cli; the command is gemini. Individual Google AI Pro, Ultra, and free-tier users should install Antigravity CLI instead. This guide shows which path is currently supported before you configure authentication.

Method	Command	When to use it
npm (global)	`npm install -g @google/gemini-cli`	Puts `gemini` on PATH; run from any directory.
npx (no install)	`npx @google/gemini-cli`	Run once, or always run latest without a global install.
Homebrew (macOS/Linux)	`brew install gemini-cli`	Manage via Homebrew; upgrade with `brew upgrade`.
MacPorts (macOS)	`sudo port install gemini-cli`	MacPorts users on macOS.
Anaconda (restricted)	`conda create -y -n gemini_env -c conda-forge nodejs`	Then `conda activate gemini_env` and `npm install -g @google/gemini-cli`.
Docker / Podman	`us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:<tag>`	Run inside the published sandbox container image.
From source	`npm link packages/cli`	Hacking on the CLI itself; or `npm run start` / `npm run start:prod`.

Install paths from the official installation docs. All require Node.js 20+.

Channel	Install command	Cadence
Stable	`npm install -g @google/gemini-cli@latest`	Weekly (Tuesdays ~20:00 UTC)
Preview	`npm install -g @google/gemini-cli@preview`	Weekly (Tuesdays ~23:59 UTC)
Nightly	`npm install -g @google/gemini-cli@nightly`	Daily (00:00 UTC, off `main`)

Release channels. Select with the npm tag; verify with `gemini --version`.

Choose a currently supported auth route

Gemini CLI has three auth routes, but personal Google login is no longer served for individual tiers. Enterprise users can still use organization-provided sign-in; API-key and Vertex AI routes remain available. Run gemini once and the first-run flow shows the options your account can use; switch later with /auth. GEMINI_API_KEY is the AI Studio / Gemini API route, while GOOGLE_API_KEY with project settings is a Vertex AI route.

Auth route	How you set it up	Current availability
Organization-managed Google sign-in (Code Assist OAuth)	Run `gemini`, choose "Sign in with Google". No env vars; credentials cached locally.	Organization-managed Code Assist tiers only; individuals use Antigravity CLI.
Gemini API key (AI Studio)	Set `GEMINI_API_KEY`, run `gemini`, pick "Use Gemini API key".	Yes — unpaid tier is Flash-only, capped at 250 requests/day; paid usage follows the selected API tier.
Vertex AI / Google Cloud	Set `GOOGLE_CLOUD_PROJECT` + `GOOGLE_CLOUD_LOCATION`, then authenticate (ADC, service account, or `GOOGLE_API_KEY`).	Yes — paid-platform path continues.

The three auth routes and their current availability as of 2026-08-01.

Gemini API key (AI Studio)

unset GOOGLE_API_KEY GOOGLE_APPLICATION_CREDENTIALS
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
gemini # select "Use Gemini API key"

Vertex AI with Application Default Credentials

unset GEMINI_API_KEY GOOGLE_API_KEY GOOGLE_APPLICATION_CREDENTIALS
export GOOGLE_CLOUD_PROJECT="my-gcp-project"
export GOOGLE_CLOUD_LOCATION="us-central1"
gcloud auth application-default login
gemini # select "Vertex AI"

Vertex AI with a service account

unset GEMINI_API_KEY GOOGLE_API_KEY
export GOOGLE_CLOUD_PROJECT="my-gcp-project"
export GOOGLE_CLOUD_LOCATION="us-central1"
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
gemini # select "Vertex AI"

Vertex AI with an API key

unset GEMINI_API_KEY GOOGLE_APPLICATION_CREDENTIALS
export GOOGLE_CLOUD_PROJECT="my-gcp-project"
export GOOGLE_CLOUD_LOCATION="us-central1"
export GOOGLE_API_KEY="AIza...vertex-key"
gemini # select "Vertex AI"

Request limits

Do not use the retired individual OAuth limits for capacity planning. For supported Gemini CLI routes, the official quota page remains the authority: the free Gemini API-key tier is Flash-only and capped at 250 requests per day, while paid API, Vertex AI, and organization-managed Code Assist limits depend on the selected tier. One prompt can consume several model requests through tools, routing, and subagents.

Auth method	Tier	Requests / user / day
Gemini API key	Free (unpaid)	250 (Flash only)
Gemini API key	Pay-as-you-go	Varies
Vertex AI	Express mode (free)	Varies (90-day window)
Workspace	Code Assist Standard	1,500
Workspace	Code Assist Enterprise	2,000

Daily limits for supported Gemini CLI routes from the official quota-and-pricing doc.

First session, start to finish

Launch in a project
cd into a repo and run gemini. The interactive TUI opens. On first run, pick a theme (Dark / Light / Auto), then an auth method from the table above.
Ask before you act
Start with a read-only prompt — @README.md summarize this. The @path syntax injects a file or directory into the prompt; !command runs a shell command from inside the CLI. Reads never change files.
Let it propose an edit
Ask for a concrete change. Gemini proposes the edit and waits for approval by default. To change that, pass --approval-mode with one of default, auto_edit, yolo, or plan. Do not use --yolo / -y — it is deprecated in favor of --approval-mode=yolo.
Use the slash commands
Type /help for the full list. Day-one set: /auth (switch auth), /theme (restyle), /clear (reset screen, also Ctrl+L), /chat (browse/resume sessions), /memory (manage GEMINI.md context), /tools (list tools; /tools desc for detail), /stats (token/usage), /mcp (manage MCP servers), /quit to exit.

Non-interactive invocations

# One-off prompt, print and exit
gemini -p "summarize README.md"
 
# Interactive TUI seeded with an opening prompt
gemini -i "What is the purpose of this project?"
 
# Force a specific model (an alias or concrete model ID)
gemini -m gemini-3.1-pro-preview
 
# Add extra directories to the context (comma-separated or repeated)
gemini --include-directories ../shared,../proto

a first interactive session

… scroll to run this session

Install, launch, ask a read-only question, then approve an edit. Edits wait for approval unless --approval-mode is set.

Which terminal to pick today

Individual account

Install Antigravity CLI. Gemini CLI no longer serves Google AI Pro, Ultra, or free-tier individual accounts. The migration imports your skills, MCP servers, agents, and GEMINI.md files.

Enterprise or API-key workflow

Continue with Gemini CLI using Code Assist Standard/Enterprise, a supported GEMINI_API_KEY, or Vertex AI (GOOGLE_CLOUD_PROJECT + GOOGLE_CLOUD_LOCATION).

Knowledge check

You set only `GEMINI_API_KEY` (free, unpaid), run `gemini`, and pick "Use Gemini API key". You then run `gemini -m gemini-3.1-pro-preview` and the request is rejected. Why?

Reach the end and this star joins your charted sky.