The Cartographer · 11 min mission
Gemini CLI: Models & Context Windows
Master the Gemini model lineup, auto-routing, the 1M-token window, and which auth path unlocks which models and quotas.
Gemini CLI runs in auto mode by default: it classifies each prompt as simple or complex and routes it to a Flash or Pro model on its own. This guide covers the model lineup you can reach, how to pin or switch models, how auto-routing decides, and how your auth method sets your daily quota. After it you can select a specific model, read which one actually ran, and budget your requests.
| Alias | Resolves to | Use it for |
|---|---|---|
auto | Best available Pro or Flash model | Default. Route each prompt by complexity and availability |
pro | Most capable available Pro model | Complex reasoning; verify the concrete ID with /model |
flash | Available Flash model | Fast, balanced model for everyday tasks |
flash-lite | Available Flash-Lite model | Fastest, lightest model for simple tasks |
auto is the documented default; the concrete model behind an alias can change with release, account, and availability.| Model ID | Input tokens | Output tokens | Knowledge cutoff |
|---|---|---|---|
gemini-3.1-pro-preview | 1,048,576 | 65,536 | January 2025 |
gemini-3-flash-preview | 1,048,576 | 65,536 | January 2025 |
gemini-2.5-pro | 1,048,576 | 65,536 | — |
gemini-2.5-flash | 1,048,576 | 65,536 | — |
gemini-2.5-flash-lite | 1,048,576 | 65,536 | — |
The coding models in this table share an approximately 1M-token input window, so model choice is about speed, cost, and reasoning depth, not how much of your repo fits. Current Google model pages publish 1,048,576 input / 65,536 output for Gemini 3.1 Pro Preview and the 2.5 family. The literal input limit appears in errors: an oversized prompt fails with input token count … exceeds the maximum number of tokens allowed (1048576).
Select or pin a model
Pin one model for a session
Pass
-m/--modelat launch — it always wins:gemini -m gemini-2.5-flash. Accepts an alias or a concrete ID.Set a default via environment
Export
GEMINI_MODEL(used only when no-mflag is given):export GEMINI_MODEL=gemini-2.5-pro.Set a persistent default in settings
Add
model.nameto~/.gemini/settings.json(used only when neither-mnorGEMINI_MODELis set):{ "model": { "name": "gemini-2.5-flash" } }.Switch mid-session
Run
/modelto open the Auto/Manual dialog; the change applies to all subsequent interactions in that session.
| Option | Behaviour | Models in play |
|---|---|---|
| Auto (Gemini 3) | System picks the best Gemini 3 model for the prompt | Available Gemini 3 Pro / Flash models; inspect Manual for live IDs |
| Auto (Gemini 2.5) | System picks the best Gemini 2.5 model for the prompt | gemini-2.5-pro, gemini-2.5-flash |
| Manual | You pick one specific model and it stays put | Any available model |
/model dialog: three top-level options. Concrete availability changes by account and release.Auto is the default selection. Availability routing is managed by the ModelAvailabilityService, which can offer a fallback when the selected model fails or reaches quota. Picking Pro in /model biases toward the most capable model your account can currently use; picking Auto lets the CLI choose. Internal utility calls can use different models without changing the configured chat model, so confirm actual usage in the session report instead of assuming an alias maps forever to one ID.
| Trigger | CLI offers |
|---|---|
| Gemini 3 Pro daily limit reached | Switch to Gemini 2.5 Pro / upgrade / stop |
| Gemini 2.5 Pro daily limit reached | Fall back to Gemini 2.5 Flash |
| Gemini 3 Pro temporarily overloaded | "Keep trying" (exponential backoff) or fall back to 2.5 Pro |
docs/cli/model-routing.md, docs/get-started/gemini-3.md).Pick a model and see what routing selects
Which Claude model?
Three quick questions about your task, your tolerance for latency, and your budget — and you'll get a single model to reach for, with the reasoning behind it. All four current models are in the legend below.
All four models
The most capable widely released model — built for the hardest reasoning and long-horizon agentic work.
The current Opus-tier model for complex reasoning and agentic coding.
The best combination of speed and intelligence — the everyday workhorse.
The fastest model with near-frontier intelligence — for snappy, high-volume work.
These IDs are the current Anthropic API mappings. The opus and sonnet aliases can resolve to older versions on Bedrock, Google Agent Platform, or Foundry.
/model → Auto (Gemini 3) / Manual, the -m flag, GEMINI_MODEL, and model.name in ~/.gemini/settings.json.| Auth method | Tier | Requests / user / day | Notes |
|---|---|---|---|
| Google account | Individual | 1,000 | Current docs list personal Google sign-in |
| Google account | Google AI Pro | 1,500 | Fixed-cost subscription tier |
| Google account | Google AI Ultra | 2,000 | Fixed-cost subscription tier |
| Gemini API key | Free (unpaid) | 250 | Flash model only; per-minute limit is account-specific |
| Gemini API key | Pay-as-you-go | Varies by pricing tier | Billed per token/call; check live account limits |
| Vertex AI | Express mode (free) | Account-specific | Free for 90 days, then billing required |
| Vertex AI | Pay-as-you-go | Dynamic shared or provisioned quota | Billed on usage; capacity depends on quota mode |
| Organization Google account | Code Assist Standard | 1,500 | Paid license seat |
| Organization Google account | Code Assist Enterprise | 2,000 | Paid license seat |
docs/resources/quota-and-pricing.md; corroborated on developers.google.com/gemini-code-assist/resources/quotas). Daily limits are aggregated across the model family unless a tier is restricted to Flash.Your authentication route, not the model menu, is the biggest lever on what you can run. Current docs list Google sign-in for individual free-tier, Google AI Pro, Google AI Ultra, and organization-managed accounts. Gemini CLI also supports a Gemini API key (export GEMINI_API_KEY="...") and Vertex AI, which needs GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, one credential method, and explicit Vertex selection. The unpaid API-key path is a separate Flash-only bucket capped at 250 requests/day; paid API and Vertex limits depend on the selected tier.
Enable Gemini 3 in the CLI
Update the CLI to a supported version
Gemini 3 requires Gemini CLI 0.21.1 or later. Upgrade with
npm install -g @google/gemini-cli@latest(stable was v0.53.1 on 2026-08-01).Switch routing to Gemini 3
Launch
gemini, run/model, choose Auto (Gemini 3), then inspect Manual or the session report for the concrete model actually available to your account. Do not pin the retiredgemini-3-pro-previewID.On Code Assist Standard / Enterprise, flip the preview switches
Managed accounts need more: an admin sets the release channel to Preview (Admin for Gemini → Settings), then you set Preview Features =
truevia/settingsand restart. Gemini 3 will not appear from upgrading alone on a managed account.
Personal Google sign-in and the API-key free tier are separate
Individual Google AI account
Current docs publish 1,000 requests/day for an individual account, 1,500 for Google AI Pro, and 2,000 for Google AI Ultra. The June transition notice says otherwise, and an open v0.54.0 issue reports Pro OAuth fallback, so verify sign-in on the latest stable release before depending on this route.
Gemini API key (free)
250 requests/day, Flash only; check the live account-specific per-minute limit.
No Pro access. Useful for scripting against a key you already have — not a way to get the best model for free.
Knowledge check
You authenticate Gemini CLI with an unpaid `GEMINI_API_KEY` and force `gemini-3.1-pro-preview`. What happens?
Reach the end and this star joins your charted sky.