The Cartographer · 11 min mission

Gemini CLI: Install & First Session

Install Gemini CLI, pick the right auth before the June 18 cutoff, and run your first session.

gemini-cliinstallationauthenticationquotasgetting-startedFact-checked 2026-06-15

Gemini CLI is Google's open-source terminal coding agent. The npm package is @google/gemini-cli; the command is gemini. This guide installs it, picks an auth route, and runs a first interactive session that reads files and proposes an edit. By the end you can launch gemini in a repo and drive the agent loop.

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 an auth route

Gemini CLI offers three auth routes. They differ in setup, daily request limit, and whether they survive June 18. Run gemini once and the first-run flow walks you through picking one; switch later in-session with /auth. Note that GEMINI_API_KEY and GOOGLE_API_KEY are different variables: GEMINI_API_KEY is the AI Studio / Gemini API route, while GOOGLE_API_KEY (with a project and location) is a Vertex AI route. Mixing them is the most common auth failure.

Auth route	How you set it up	Survives June 18?
Personal Google login (OAuth)	Run `gemini`, choose "Sign in with Google". No env vars; credentials cached locally.	No — free individual tier migrates to Antigravity CLI.
Gemini API key (AI Studio)	Set `GEMINI_API_KEY`, run `gemini`, pick "Use Gemini API key".	Paid keys: yes. Free tier: unconfirmed — do not rely on it.
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, their setup, and whether they keep working after June 18, 2026.

Set the env vars for each auth route

# Gemini API key (AI Studio) — paid key survives the cutoff
export GEMINI_API_KEY="ya29...your-key"
 
# Vertex AI — project + location are always required
export GOOGLE_CLOUD_PROJECT="my-gcp-project"
export GOOGLE_CLOUD_LOCATION="us-central1"
# then pick ONE credential method:
gcloud auth application-default login                       # (a) ADC
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"   # (b) service account
export GOOGLE_API_KEY="AIza...vertex-key"                   # (c) API key
 
# Personal Google login needs NO env var — just: gemini

Request limits

The two free tiers are far apart in size. Free personal Google login gives 1,000 model requests / user / day across the Gemini family (until June 18). A free Gemini API key gives only 250 requests / day, Flash model only — a 4× gap. On per-minute limits: the repo README states 60 RPM for the free personal-Google tier, but the official quota doc commits only to the daily number and says requests are "limited per user per minute and are subject to the availability of the service." Treat 60 RPM as a README figure, not a guaranteed rate; treat 1,000/day as the firm documented limit.

Auth method	Tier	Requests / user / day
Google account	Code Assist (Individual) — free	1,000
Google account	Google AI Pro	1,500
Google account	Google AI Ultra	2,000
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
Workspace	Workspace AI Ultra	2,000

Free/tier daily request limits from the official quota-and-pricing doc. Paid tiers vary with usage.

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 (full ID required — no short aliases)
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 auth to pick today

Exploring this week

Use Sign in with Google: zero setup, 1,000 requests/day, no keys.

It stops serving requests in Gemini CLI on June 18, 2026 — after that, free personal usage lives in Antigravity CLI.

Must keep working

Set a paid GEMINI_API_KEY or Vertex AI (GOOGLE_CLOUD_PROJECT + GOOGLE_CLOUD_LOCATION) now.

These continue in Gemini CLI past the cutoff. Vertex Express Mode buys a 90-day free evaluation window.

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.