The Cartographer · 11 min mission

Gemini CLI: Install & First Session

Install Gemini CLI, choose a documented authentication route, and handle the unresolved personal-OAuth conflict.

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

Gemini CLI is Google's open-source terminal coding agent. The npm package is @google/gemini-cli; the command is gemini. Current authentication docs list Google sign-in for individual free-tier, Google AI Pro, and Google AI Ultra accounts, alongside API-key, Vertex AI, and organization-managed routes. This guide shows how to install the CLI and choose among those routes.

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 authentication methods: Google sign-in, a Gemini API key, and Vertex AI. Current docs recommend Google sign-in for most local users, including individual free-tier, Google AI Pro, Google AI Ultra, and organization-managed accounts. 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
Google sign-in (OAuth)	Run `gemini`, choose "Sign in with Google". No env vars; credentials cached locally.	Documented for individual free-tier, Google AI Pro/Ultra, and organization-managed accounts. Some organization accounts require a Google Cloud project.
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 documented authentication methods as of 2026-08-22.

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

Keep Google-account and API-key quotas separate. Current docs publish 1,000 requests per day for an individual Google account, 1,500 for Google AI Pro, and 2,000 for Google AI Ultra. The unpaid Gemini API-key route is a different bucket: 250 requests per day and Flash only. Paid API and Vertex AI limits depend on the selected tier. One prompt can consume several model requests through tools, routing, and subagents.

Auth method	Tier	Requests / user / day
Google sign-in	Individual	1,000
Google sign-in	Google AI Pro	1,500
Google sign-in	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

Daily limits from the current Gemini CLI quota-and-pricing documentation.

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.

Choose a route for an individual account

Google sign-in

Current Gemini CLI docs list Sign in with Google for individual free-tier, Google AI Pro, and Google AI Ultra accounts. Because the June transition notice and the open OAuth issue conflict with those docs, update first and verify that your account completes sign-in before relying on this route.

Fallback routes

Use a GEMINI_API_KEY, Vertex AI (GOOGLE_CLOUD_PROJECT + GOOGLE_CLOUD_LOCATION), or Antigravity if personal OAuth fails. Antigravity migration has partial parity: rule files carry over, but commands, skills, and MCP configuration may require conversion.

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.