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-climodelscontext-windowquotasmodel-routingauthenticationFact-checked 2026-06-15

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.

AliasResolves toUse it for
autoBest available Pro or Flash modelDefault. Route each prompt by complexity and availability
proMost capable available Pro modelComplex reasoning; verify the concrete ID with /model
flashAvailable Flash modelFast, balanced model for everyday tasks
flash-liteAvailable Flash-Lite modelFastest, lightest model for simple tasks
The four model aliases and their intent. `auto` is the documented default; the concrete model behind an alias can change with release, account, and availability.
Model IDInput tokensOutput tokensKnowledge cutoff
gemini-3.1-pro-preview1,048,57665,536January 2025
gemini-3-flash-preview1,048,57665,536January 2025
gemini-2.5-pro1,048,57665,536—
gemini-2.5-flash1,048,57665,536—
gemini-2.5-flash-lite1,048,57665,536—
Context windows by model. Current Google model pages publish the exact 2^20 limits for Gemini 3.1 Pro Preview and the 2.5 series.

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

  1. Pin one model for a session

    Pass -m / --model at launch — it always wins: gemini -m gemini-2.5-flash. Accepts an alias or a concrete ID.

  2. Set a default via environment

    Export GEMINI_MODEL (used only when no -m flag is given): export GEMINI_MODEL=gemini-2.5-pro.

  3. Set a persistent default in settings

    Add model.name to ~/.gemini/settings.json (used only when neither -m nor GEMINI_MODEL is set): { "model": { "name": "gemini-2.5-flash" } }.

  4. Switch mid-session

    Run /model to open the Auto/Manual dialog; the change applies to all subsequent interactions in that session.

OptionBehaviourModels in play
Auto (Gemini 3)System picks the best Gemini 3 model for the promptAvailable Gemini 3 Pro / Flash models; inspect Manual for live IDs
Auto (Gemini 2.5)System picks the best Gemini 2.5 model for the promptgemini-2.5-pro, gemini-2.5-flash
ManualYou pick one specific model and it stays putAny available model
The `/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.

TriggerCLI offers
Gemini 3 Pro daily limit reachedSwitch to Gemini 2.5 Pro / upgrade / stop
Gemini 2.5 Pro daily limit reachedFall back to Gemini 2.5 Flash
Gemini 3 Pro temporarily overloaded"Keep trying" (exponential backoff) or fall back to 2.5 Pro
Routing fallback prompts when a limit or capacity issue is hit (`docs/cli/model-routing.md`, `docs/get-started/gemini-3.md`).
auto routing picks the model for you
… scroll to run this session
Two prompts, one session. The router sends the trivial question to Flash and the architecture task to the most capable Pro model available — without switching anything.

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.

0/3
Question 1 of 3

How hard is the task?

All four models

Claude Fable 5$10 / $50 per MTok

The most capable widely released model — built for the hardest reasoning and long-horizon agentic work.

Claude Opus 4.8$5 / $25 per MTok

The most capable Opus-tier model for complex reasoning and agentic coding.

Claude Sonnet 4.6$3 / $15 per MTok

The best combination of speed and intelligence — the everyday workhorse.

Claude Haiku 4.5$1 / $5 per MTok

The fastest model with near-frontier intelligence — for snappy, high-volume work.

Compare the model tiers and routing outcomes. In Gemini CLI the equivalent controls are `/model` → Auto (Gemini 3) / Manual, the `-m` flag, `GEMINI_MODEL`, and `model.name` in `~/.gemini/settings.json`.
Auth methodTierRequests / user / dayNotes
Gemini API keyFree (unpaid)250Flash model only; per-minute limit is account-specific
Gemini API keyPay-as-you-goVaries by pricing tierBilled per token/call; check live account limits
Vertex AIExpress mode (free)Account-specificFree for 90 days, then billing required
Vertex AIPay-as-you-goDynamic shared or provisioned quotaBilled on usage; capacity depends on quota mode
Organization Google accountCode Assist Standard1,500Paid license seat
Organization Google accountCode Assist Enterprise2,000Paid license seat
Supported Gemini CLI quotas by auth method and tier (`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. Organization-managed Code Assist users can sign in with Google; Google AI Pro, Ultra, and free-tier individual accounts now use Antigravity CLI. 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 Flash-only at 250 requests/day; paid API and Vertex limits depend on the selected tier.

Enable Gemini 3 in the CLI

  1. 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).

  2. 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 retired gemini-3-pro-preview ID.

  3. 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 = true via /settings and restart. Gemini 3 will not appear from upgrading alone on a managed account.

Individual OAuth moved; the API-key free tier remains

Individual Google AI account

Gemini CLI no longer serves Google AI Pro, Ultra, or free-tier individual accounts. Install Antigravity CLI for this route.

Organization-managed Code Assist sign-in remains a separate supported path.

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.