GeminiDesktop’s chat page (geminidesktop.app/chat) just grew a new small switch: a CLI toggle. Flip it on and every message you send no longer hits the Gemini API — it routes through the gemini CLI you’ve already logged into on your machine. Which means: OAuth sign-in is all you need, you get 60 requests per minute and 1,000 per day of free Gemini 2.5 Pro, and that long AIza... BYOK API key never has to leave your notes app.

TL;DR Quick Reference

Trigger: GeminiDesktop chat page → new “CLI” button in the input toolbar, next to Search / URL / Code
Auth: local ~/.gemini/tokens.json (OAuth). API key never enters the browser
Free tier: personal Google account → 60 req/min, 1,000 req/day of Gemini 2.5 Pro with a 1M token context window
Model picker: the top-right model dropdown still works — selected model is passed to the CLI as --model <id>. A quiet “· via CLI” suffix appears next to the model name when CLI mode is active
Desktop-only: the toggle is grayed out in web browsers (they can’t spawn subprocesses); only the Tauri desktop app gets it
Install: bun add -g @google/gemini-cli, or one-click Install from inside GeminiDesktop if the CLI isn’t detected
Architecture: Headless mode (gemini --output-format stream-json), not ACP — reuses the existing local_agent event pipeline
MVP scope: no attachments, no Computer Use, no Regenerate/Edit yet

A new “CLI” toggle next to the input

Open GeminiDesktop, head to /chat, and you’ll see a new small button in the input toolbar — right next to the existing Search, URL, and Code grounding toggles, a fourth button labeled CLI.

Straightforward logic:

Off (default): messages flow through @ai-sdk/google straight to the Gemini API, using the API key you saved in settings (BYOK)
On: subsequent messages route through your local gemini CLI in headless mode, authenticated by the local OAuth token

Switching is frictionless. No app restart, no re-login, no history wipe. Messages you sent before flipping the toggle stay right where they were; new messages go through the CLI.

The top-right model picker is reused as-is. That familiar “Gemini 3.1 Pro / 3.0 Flash / 2.5 Pro / 2.5 Flash / Flash Lite” dropdown keeps working in CLI mode — whichever model you pick is forwarded to the CLI via --model <id> (Gemini CLI docs confirm this flag). To make it obvious you’re on the CLI path, a subtle gray “· via CLI” suffix appears next to the model name.

Three real reasons to flip the switch

This is the main reason most people will turn this on.

Per the Google announcement, signing into Gemini CLI with a personal Google account automatically grants a free Gemini Code Assist license with access to Gemini 2.5 Pro at:

60 requests per minute
1,000 requests per day
1 million token context window

Compare that to the BYOK route: either register at Google AI Studio and manage an API key carefully, or hunt down the $300 Google Cloud new-customer credit and sweat usage. CLI mode skips all of that. One OAuth browser flow, token lands in ~/.gemini/tokens.json, and when GeminiDesktop calls the CLI, the CLI reads the token itself. Your API key never enters the browser and never touches any GeminiDesktop storage.

2. Local power: Gemini that does things, not just talks

The second value of CLI mode: Gemini can call local tools.

API-only chat limits Gemini to telling you what to do. CLI chat lets Gemini read files, write files, run shell commands. It becomes a genuine local agent.

A few daily scenarios:

“Organize the titles of every PDF in my Downloads folder into a table” — CLI-mode Gemini runs ls ~/Downloads/*.pdf, reads metadata, returns a clean list
“What’s the TypeScript error in this project?” — no log-pasting; Gemini cds into the directory, runs tsc --noEmit, reads the output, pinpoints the issue
“Turn this meeting recording into Markdown” — Gemini reads your local file, invokes the right system tool, writes the result

For safety, the default permissionMode is default, not --yolo. CLI won’t silently edit files; every sensitive operation (file write, shell command) prompts for approval at the CLI layer. Users who want full autonomy can later switch to YOLO in settings, but the default stays conservative.

3. Streaming that looks identical to the API path

You might worry: the CLI is a separate process — will its output dump raw text into the chat bubbles?

It won’t. Under the hood we reuse GeminiDesktop’s mature local_agent event pipeline. The CLI’s stream-json output is parsed Rust-side into a unified message format, streamed to the frontend in real time via a Tauri event, and mapped back into message parts by a frontend adapter. It renders through the same chat bubble components the API path uses.

The UI is identical in both modes. Tool calls (read_file, run_shell) render as collapsible cards you can expand to see input JSON and output text. Thinking is a pale-toned separate bubble. Streaming text types out character by character, just like API mode. The only visible difference: that quiet “· via CLI” suffix on the top-right model name.

Three steps to start

Step 1: Install gemini CLI

Two ways, pick one:

# Option A: run the command yourself
bun add -g @google/gemini-cli
# or: npm install -g @google/gemini-cli

Or install one-click from inside GeminiDesktop: the first time you flip the CLI toggle, if we detect the CLI isn’t installed, a toast pops with an “Install” button that runs the command for you.

In your terminal:

gemini

A browser window opens automatically with the Google sign-in page. Authorize with your personal Google account. The token writes to ~/.gemini/tokens.json — from then on, GeminiDesktop’s calls into the CLI read this token automatically.

Step 3: Flip the “CLI” toggle

Head to geminidesktop.app/chat, click the “CLI” button in the input toolbar. Highlighted blue = on. Send a message as usual — you’ll see “Gemini 3.x Pro · via CLI” in the top-right, confirming the CLI took over.

MVP boundaries (the honest version)

✅ Supported:

Text chat (all Gemini models selectable)
Model switching (top-right picker → CLI --model)
Streaming tool calls (read_file / run_shell / code_execution, etc.)
Stop button aborts the CLI process anytime
Multi-turn context (prompt-prefix concatenation — see next section)

❌ Not yet supported:

Attachments: the CLI needs file paths, but browser-side images and PDFs are blobs. We haven’t written the glue layer that writes blobs to a temp directory yet, so attachments get blocked with a toast while CLI mode is on. Coming in a follow-up
Computer Use: often conflated — Gemini Computer Use is a Gemini 3.1 Pro API capability (model takes screenshots and drives the desktop), not a CLI capability. Gemini CLI itself doesn’t expose a Computer Use tool. We’ll ship Computer Use later as a separate feature on the API path with a dedicated executor, parallel to the CLI toggle
Regenerate / Edit messages: CLI-sourced assistant messages can’t be regenerated or re-run after edit yet. Those buttons are grayed out on CLI bubbles. Coming later

🔮 What’s next: if Gemini CLI ships a documented headless --resume <id> flag or a proper ACP integration, we’ll switch to native session state management. The current prompt-prefix concat is a pragmatic stand-in.

Why Headless, not ACP — a quick architecture note

For the technically curious.

Two ways to embed Gemini CLI into a chat UI:

Headless mode (gemini --output-format stream-json): spawn a fresh CLI subprocess per message, parse stream-json events from stdout, end the turn when the process exits. Multi-turn context comes from manually concatenating history — prepend prior user/assistant messages to each new prompt.

ACP mode (Agent Client Protocol): run a long-lived JSON-RPC subprocess, talk to it via initialize / newSession / prompt / cancel methods. Native multi-turn state, loadSession recovery, MCP tool broadcasting — more complete, more implementation work.

We picked Headless. Honest reasons:

Reuse a mature pipeline: GeminiDesktop’s underlying local_agent module has used Headless for nearly a year to run Claude Code, OpenCode, Codex, Cursor, and others. Event bridge, message protocol, error handling, Stop button — all already there. Adding Gemini CLI just meant extending an executor
Time cost delta: ~1 week to ship Headless vs. ~1 month to ship ACP (JSON-RPC client, subprocess lifecycle, MCP server broadcasting — because ACP expects the host to proxy file I/O)
Headless is good enough: ~150-300ms spawn cost per turn, tolerable for chat UX. Prompt-prefix multi-turn does resend history each time, but Gemini 2.5 Pro’s 1M token window doesn’t care about that overhead

Verdict: ship Headless now so people can use it; keep ACP as a future upgrade, to revisit if spawn latency or cancellation semantics actually start hurting.

Compared to Claude Desktop / ChatGPT

GeminiDesktop’s underlying local_agent module actually supports Claude Code, OpenCode, Codex, Cursor, and other CLIs too. Core differences:

Gemini CLI (this release): free with a personal Google account (1,000 req/day), OAuth login only; strong long-context advantage (1M tokens)
Claude Code: needs an Anthropic API subscription or a Pro plan — paid path. Top-tier reasoning quality

How to choose: daily chat / long-context tasks / “I just want free” → Gemini CLI. Heavy code editing / already in the Claude ecosystem → Claude Code. Both can coexist in one GeminiDesktop install; toggle the default agent in settings.

If you’ve been on Claude Desktop or ChatGPT desktop until now, check out the full guide to migrating from Claude Desktop to Gemini for Mac — combined with GeminiDesktop’s CLI mode, you can skip Claude’s paid tier entirely.

FAQ

Q1: Where does my chat content go in CLI mode?

Same as direct API mode — content flows through the gemini CLI to Google’s Gemini servers. The differences:

Auth: via your local OAuth token, no API key in the browser
Data path: GeminiDesktop → local CLI process → Google Gemini API (no third-party backend in between)
Chat history: stored in local IndexedDB, not uploaded to any server

Q2: Can I use CLI mode and API mode together?

Yes. The toggle flips freely, and both modes’ messages coexist naturally in the same session. A common mixed pattern: API mode + Flash Lite for cheap, fast everyday chat; flip to CLI mode + 2.5 Pro when you need Gemini to touch local files, run code, or burn through a long reasoning task.

Q3: Nothing happens when I flip the toggle, or I see an error?

Three likely causes:

CLI not installed: the toggle surfaces an Install toast — click “Install,” or run bun add -g @google/gemini-cli manually
CLI not authenticated: you’ll see a “Gemini CLI not authenticated” toast. Run gemini in your terminal and finish the OAuth flow
You’re on the web version, not the desktop app: the toggle is disabled in browsers. Download GeminiDesktop for the full experience

Q4: Does CLI mode replace Gemini Canvas or NotebookLM?

No, they’re complementary. Canvas focuses on web pages / infographics / quizzes / flashcards creation templates — see Gemini Canvas on Desktop. NotebookLM is a RAG-style knowledge-base tool for cross-source Q&A. CLI mode is best for “let Gemini do things in my local filesystem” — file organization, code debugging, shell execution, long-context reasoning.

Q5: Does it work on Windows?

Yes. GeminiDesktop supports both macOS and Windows (Tauri-packaged), and CLI mode works the same on both. If you’re still evaluating Gemini on Windows, take a look at why Google still hasn’t made a native Gemini Windows app for context on the Windows landscape.

Summary

A small toggle that does one big thing: it brings Google’s free tier into GeminiDesktop’s chat experience. No paid API key, no terminal gymnastics, no re-implementing a model picker. For anyone who wants Gemini 2.5 Pro without dealing with API key management, this is the lowest-friction path.

MVP first; attachments, Computer Use, and ACP-mode upgrades ship as follow-on features. Try it now: geminidesktop.app/chat.