Google Gemini CLI (headless)

• Kind: headless coding agent (subprocess)
• Official docs: https://google-gemini.github.io/gemini-cli/ · https://ai.google.dev/gemini-api/docs/models · https://github.com/google-gemini/gemini-cli
• Cyberine adapter: CliAgentAdapter via makeGeminiAdapter (build worker gemini)
• Researched/verified: 2026-06-07 — confidence high.

Cyberine invocation

gemini -p "<prompt>" -o json --approval-mode yolo --skip-trust -m <model>

Default model: gemini-2.5-flash (CYBERINE_GEMINI_MODEL / GEMINI_MODEL). Auth dir allow-listed by the sandbox: ~/.gemini.

Auth (3 methods)

1. OAuth — gemini auth login (browser flow; creds in ~/.gemini/). Not for headless CI.
2. API key — GEMINI_API_KEY (from Google AI Studio). Use this for service/headless.
3. Vertex AI — GOOGLE_APPLICATION_CREDENTIALS + GOOGLE_CLOUD_PROJECT, or ADC, or GOOGLE_API_KEY.

Config: ~/.gemini/settings.json (user), .gemini/settings.json (project), ~/.gemini/.env.

Billing per auth method (researched 2026-09-18, task kryzh)

Source: the gemini-cli repo's own quota-and-pricing page, fetched live from main on 2026-09-18 (https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/quota-and-pricing.md), cross-checked against https://ai.google.dev/gemini-api/docs/pricing (retrieved 2026-09-18).

• OAuth login, personal Google account, Code Assist for individuals — free tier: "1000 maximum model requests / user / day" across the Gemini model family. Zero per-token cost; a request-count quota, not a spend.
• OAuth login, Google AI Pro or Google AI Ultra subscriber — same gemini auth login flow and the same ~/.gemini/oauth_creds.json credential file as the free tier above; the account entitlement (not the file) decides the tier. Pro gets 1,500 requests/day, Ultra 2,000/day, and the docs state plainly: "Quotas and pricing are based on a fixed price subscription." No per-token metering.
• GEMINI_API_KEY (Google AI Studio key), unpaid project — free tier: 250 requests/day, restricted to the Flash model only. Same env var as the paid case below; nothing on disk distinguishes an unpaid key from a paid one.
• GEMINI_API_KEY, billing-enabled project (pay-as-you-go) — "Quota: Varies by pricing tier. Cost: Varies by pricing tier and model/token usage" — real per-token spend, billed to the Google Cloud project backing the key.
• Vertex AI, Express Mode — usable up to 90 days "without the need to enable billing" (no GOOGLE_CLOUD_PROJECT billing account required yet). Effectively free during that window.
• Vertex AI, regular mode (ADC / service account / GOOGLE_API_KEY) — "Cost: Based on model and token usage," governed by a dynamic shared quota or pre-purchased provisioned throughput. Real per-token spend against the GCP billing account.

Both the OAuth-login path (free-tier individual vs Pro/Ultra subscriber) and the API-key path (unpaid vs billing-enabled project) hinge on account-side entitlement that no local file or env var reveals — the credential MECHANISM is all Cyberine can observe. resolveBillingClass (src/core/billingClass.ts) therefore classifies by mechanism, matching the same priority checkGemini() (src/core/cliAvailability.ts) already uses to decide whether the worker can dispatch at all: GEMINI_API_KEY present resolves to credits (it is always a per-call/per-token bill against some Google Cloud identity, paid or the 250/day unpaid allotment); an OAuth cache present with no key resolves to subscription (the login path's steady-state outcome is a fixed-price plan — Google AI Pro/Ultra or a Code Assist Standard/Enterprise seat — rather than metered spend). This does not distinguish an individual free-tier login from a Pro/Ultra login, and per the Gotchas section above, a live dispatch through this exact path has been measured failing outright for individual accounts (IneligibleTierError, 2026-08-22) — the credential file can be present and valid while the account itself is no longer eligible to dispatch at all. Neither is provable locally; the class is a best-mechanism-match, not a verified account tier, and the case with no credential of either kind still falls back to credits with a warning as before.

MCP servers (client config, added kskdf, verified 2026-09-18)

Gemini CLI is also an MCP client: ~/.gemini/settings.json (user scope) or .gemini/settings.json (project scope) takes an mcpServers object keyed by server name, each entry command (stdio) or url/httpUrl (remote), plus optional args, env, cwd, timeout, trust. Live-verified against the installed gemini-cli 0.46.0: gemini mcp --help lists add|remove|list|enable|disable, and gemini mcp add [-s user|project] [-t stdio|sse|http] [-e KEY=VALUE...] <name> <commandOrUrl> [args...] writes exactly that mcpServers entry (-s/--scope defaults to project, matching the installed binary's own help text). Source: https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html, retrieved 2026-09-18.

cyberine mcp install --target gemini writes this entry directly into ~/.gemini/settings.json (user scope only; project scope for this target is deferred — see Known limitations in USAGE.md), never shelling out to gemini mcp add, so it works even without gemini on PATH. It merges into any existing settings.json (parses and rewrites the JSON, preserving every other key), is idempotent (a mcpServers.cyberine key already present is a no-op), and backs the file up once to settings.json.bak-cyberine before its first write. --print shows the entry without touching the file.

Key flags

Models (Jun 2026; Stable/GA additions re-verified 2026-08-27, T651b)

Gemini 3.x ids are confirmed on ai.google.dev but newer than the Cyberine default — verify before switching. Underlying API: Google Gemini (ai.google.dev).

T651b re-verify (2026-08-27, doc-only — no GEMINI_API_KEY on this machine, cannot live-probe): re-fetched ai.google.dev/gemini-api/docs/models raw HTML (not just the WebFetch summary, cross-checked against the page's own <h3 data-text="Stable">/"Preview" section anchors — a prior pass on this exact page produced inconsistent results) plus /docs/pricing (last-modified 2026-08-26). Confirmed Stable/GA and added: gemini-3.7-flash, gemini-3.6-flash, gemini-3.5-flash-lite. Confirmed Preview (declined, NOT added): gemini-3-flash-preview, gemini-3.5-live-translate-preview, gemini-3.1-flash-live-preview, gemini-3.1-flash-tts-preview, gemini-omni-flash. Confirmed GA but out-of-modality for this catalog (declined): gemini-3.5-transcribe(-live) (speech-to-text), gemini-3.1-flash-image / gemini-3.1-flash-lite-image / gemini-3-pro-image ("Nano Banana" image generation family).

Output parsing

Cyberine parses the single JSON object, trying fields response → text → output in order; on parse failure returns raw stdout. (No usage extracted in this mode.)

Gotchas

• The free tier's OAuth login no longer works from this CLI at all (measured 2026-08-22, gemini-cli 0.46.0). A real dispatch exits 1 with Error authenticating: IneligibleTierError, reasonCode: 'UNSUPPORTED_CLIENT', tierId: 'free-tier' — "This client is no longer supported for Gemini Code Assist for individuals. To continue using Gemini, please migrate to the Antigravity suite of products". The stored credential is still VALID, so nothing returns 401/403 and no local check can see it: ~/.gemini/oauth_creds.json still holds a good refresh token, and Cyberine's own checkGemini() (src/core/cliAvailability.ts) reported the worker as logged in. Only running it reveals the revocation. Two consequences, both now handled: classifyQuotaError treats a tier/eligibility revocation as an auth-failure so the first failed dispatch cools the worker down instead of it being retried forever (selftest:tier-revocation), and cyberine doctor prints [FAIL] gemini: logged in, but LAST DISPATCH FAILED (auth-failure) with the cause rather than a green installed, logged in. To actually use the worker you need an eligible tier — a GEMINI_API_KEY (paid API) or a Code Assist Standard/Enterprise seat — not a re-login. Evidence: run 737f8b1d-64f9-4e06-947b-0ed3b234bb15, and the gemini row in worker-profile coverage.
• --approval-mode yolo required headless — else it stalls on permission prompts that never arrive.
• --skip-trust required headless in non-trusted dirs — else it stalls at the folder-trust prompt.
• -y/--yolo deprecated → use --approval-mode yolo.
• JSON response field isn't guaranteed response — hence Cyberine's response/text/output fallback chain.
• Gemini 2.0 Flash / Flash-Lite shut down 2026-06-01; gemini-2.5-flash-preview-09-2025 also gone → use stable gemini-2.5-flash.
• OAuth needs a browser → use GEMINI_API_KEY for headless.
• GEMINI_MODEL env and model.name in settings both set the default; -m overrides both.

Pricing

gemini-2.5-flash $0.30/$2.50; -flash-lite $0.10/$0.40; -pro $1.25–2.50/$10–15; gemini-3.5-flash $1.50/$9.00; gemini-3.5-flash-lite $0.30/$2.50; gemini-3.6-flash / gemini-3.7-flash $0.75/$3.75 through 2026-12-31 (then $1.50/$7.50 from 2027-01-01 — re-check before that date). Free tier (rate-limited, content used for improvement). Batch = 50% off. https://ai.google.dev/gemini-api/docs/pricing

Cyberine integration notes

• gemini build worker gated on install + headless login; sandbox makes ~/.gemini writable.
• Cyberine passes -m <model> always (default gemini-2.5-flash); no usage data is captured from the JSON-object output.

Sources

• https://google-gemini.github.io/gemini-cli/docs/cli/headless.html
• https://google-gemini.github.io/gemini-cli/docs/get-started/authentication.html
• https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html (MCP client config, retrieved 2026-09-18)
• https://ai.google.dev/gemini-api/docs/models
• https://ai.google.dev/gemini-api/docs/pricing (retrieved 2026-09-18 for the Billing section)
• https://github.com/google-gemini/gemini-cli/blob/main/docs/resources/quota-and-pricing.md (retrieved 2026-09-18 for the Billing section)
• https://github.com/google-gemini/gemini-cli