Gemini CLI Tutorial: Long Context, Multimodal & Workspace

Why Gemini CLI deserves its own guide

The three dominant AI coding CLIs each have a clear identity. Claude Code is known for deep code comprehension. Codex leans on GPT-5.5's reasoning for complex tasks. Gemini CLI isn't competing on either of those axes — its real differentiation is a 2-million-token context window, native multimodal input, and tight Google Workspace integration.

Two million tokens translates to roughly 1.5 million Chinese characters, 5,000 pages of A4 text, or an entire medium-sized codebase. In practice, that means you can feed in a full repository, a technical handbook, or six months of meeting notes in a single session — no chunking, no batch processing, no external index to maintain. For tasks that require a genuine global view — contract review, large-scale refactoring, cross-document synthesis — this isn't a benchmark number. It's a workflow difference.

This tutorial focuses on three concrete use cases, with commands you can copy and adapt today.

---

Installation and setup

Gemini CLI installs as a global npm package. You need Node.js 18.0 or higher.

npm install -g @google/gemini-cli
gemini auth login                        # opens a browser for Google account authorization
gemini config set model gemini-3-pro     # set your default model

After authentication, credentials are stored in ~/.config/gemini/config.json. If you're on a Google Workspace account in an enterprise environment, use --workspace to go through a separate auth flow — you'll need those permissions later for Drive and Docs integration.

Verify everything is working:

gemini --version
gemini chat "In one sentence, what does a 2M token context window mean for a developer?"

First-response latency is typically 2–4 seconds. After that, the session maintains state until you exit — context accumulates throughout the conversation.

---

Long-document processing: what 2M tokens actually unlocks

This is where Gemini CLI pulls away from Claude Code and Codex most clearly. Claude Opus 4.8 supports around 200K tokens; GPT-5.4 is around 320K. Gemini's ceiling is 10x higher, and the following workflows take direct advantage of that.

Full-repo code review

gemini chat --attach ./src --attach ./tests \
  "Find all potential SQL injection vulnerabilities, list them by file, and suggest fixes"

--attach accepts directories or individual files and recursively reads everything inside. A 300K-line Python project typically uses 400K–600K tokens — comfortably within the 2M limit in a single pass.

PDF contract analysis

gemini chat --attach ./contract_bundle.pdf \
  "Extract every clause that specifies a penalty amount, group by contract ID, and output as a markdown table"

PDFs are parsed automatically, including OCR on charts and images. No preprocessing pipeline needed. Compared to extracting text with a script and then calling an API separately, this alone saves significant setup work.

Multi-file cross-document comparison

gemini chat \
  --attach ./spec_v1.md \
  --attach ./spec_v2.md \
  --attach ./implementation.py \
  "Compare the two spec versions, then identify which parts of the implementation haven't caught up with the v2 changes"

This kind of task usually requires multiple rounds in Claude Code or Codex, because three non-trivial files frequently exceed their context limits. With Gemini CLI, it's one command.

---

Multimodal input: beyond "describe this image"

Gemini 3 supports images, video frames, and audio clips as native CLI inputs. This opens up some genuinely useful workflows that other CLIs don't support out of the box.

Design mockup to code

gemini chat --image ./mockup.png \
  "Generate a React + Tailwind component in TypeScript based on this design. Match the colors and spacing exactly."

Output quality scales with image resolution — a 1080p screenshot produces noticeably better results than a low-res export.

Architecture diagram review

gemini chat --image ./system_architecture.png \
  "Analyze this architecture diagram, identify single points of failure, and suggest how to harden each one"

Screen recording to documentation

gemini chat --video ./demo_recording.mp4 \
  "Generate a user manual from this screen recording. Describe each step, and include timestamps for the key actions."

Video input is capped at 1 hour and 2GB — enough for most demo recordings or meeting clips. Claude Code's CLI doesn't currently support video input natively. Codex handles images but requires API calls rather than CLI-native video support. On this dimension, Gemini CLI has a real practical edge, not just a feature-list advantage.

---

Google Workspace integration: Drive and Docs as context

This is Gemini CLI's most unique capability. No other major AI CLI has an official integration path here.

Once you've completed Workspace auth, you can reference Google Drive file URLs directly:

gemini chat \
  --gdrive "https://docs.google.com/document/d/1aBcDe.../edit" \
  "Summarize the core features in this requirements doc and output a prioritized list"

You can also point at an entire Drive folder:

gemini chat \
  --gdrive-folder "https://drive.google.com/drive/folders/1xYzAb..." \
  "Go through all the meeting notes in this folder and surface recurring issues that haven't been resolved"

And pull in Sheets data for analysis:

gemini chat \
  --gsheet "https://docs.google.com/spreadsheets/d/1Fg..." \
  "Analyze Q1–Q2 sales trends, identify the three fastest-growing categories, and hypothesize why"

For teams that live in Google Workspace, this closes the loop entirely — no manual exports, no file uploads, no context-switching. For enterprise use, the --workspace-domain parameter lets you scope data access to your org's domain, which helps with compliance requirements.

---

How the three CLIs compare

	Gemini CLI	Claude Code	Codex
Context window	2M tokens	200K tokens	320K tokens
Native multimodal (CLI)	Image + video + audio	Image	Image
Workspace integration	Native	None	None
Code reasoning depth	Good	Excellent	Excellent
First-token latency	2–4s	1–3s	1–3s
Offline / self-hosted	No	No	No

The selection logic is straightforward. If your task centers on long-context document work or Google Workspace data, Gemini CLI is the right tool. If you need deep code reasoning and refactoring, Claude Code and Codex are still stronger. In practice, these tools aren't mutually exclusive — many teams route tasks to whichever CLI fits best.

---

If you're mixing Gemini CLI with Claude Code and Codex and don't want to juggle multiple accounts and billing dashboards, I'd point you toward XycAi. It's a single OpenAI-compatible API that covers 200+ models — Gemini, Claude, GPT, and more — with one-command setup for all three CLIs. GPT and Claude official models are available at around 14% of list price, which adds up fast when you're running long-context jobs regularly.