Gemini CLI - Google's AI CLI That Doesn't Completely Suck

Google took their Gemini 2.5 Pro model and stuck it behind a free CLI tool that doesn't require a credit card. No obvious catch yet, but this is Google - they'll fuck it up somehow.

The 1M Token Context Actually Works

Most AI tools claim massive context windows but choke when you paste more than a few files. Gemini CLI's 1M token limit actually lets you feed it your entire React app without losing track of what you're discussing. The context is legit but responses get slower with large codebases - fed it a 180-file Next.js monorepo and it took 15 seconds per response vs the usual 3-4 seconds.

The ReAct system means it doesn't just chat, it can:

• Run shell commands (with annoying but necessary confirmations)
• Search Google for current info (actually helpful for debugging)
• Create and modify files across your entire project
• Connect to external tools via MCP servers (most have 3 commits and were last updated in 2024)

Free Tier That's Too Good to Last

The free tier gives you 60 requests/minute and 1K requests/day. That's more generous than GitHub Copilot's paid tier. Most development sessions hit maybe 200-300 requests, so the daily limit is actually realistic unlike Claude Code's bullshit hourly limits.

Authentication options:

• OAuth with Google - easiest setup, best free limits
• API key from AI Studio - if you want to pay for more usage
• Vertex AI - for enterprise deployments that need compliance theater

Where It Actually Helps (And Where It Sucks)

Good for:

• Understanding large codebases without getting lost in the mess
• Generating boilerplate that follows your existing patterns
• Debugging with real-time Google search for error messages
• Creating docs that don't sound like legal wrote them

Frustrating when:

• Authentication randomly breaks and you waste 20 minutes restarting everything
• It gets overconfident and suggests changes that break your tests
• Safety confirmations slow down simple file operations
• Context is legit but starts forgetting edge cases around the 800K token mark

The Node.js 20+ requirement meant updating my entire dev environment, but the OAuth flow is smoother than most Google products (shocking, I know). Works great until Google inevitably kills it like everything else they make.

Installation works fine until you hit Windows WSL weirdness. You need Node.js 20+ - Node 18.17+ breaks the auth flow with a cryptic ECONNRESET error that cost me 2 hours to debug because Google's error messages are useless.

Installation That Actually Works

Try Before Installing

npx https://github.com/google-gemini/gemini-cli

Always run with --verbose or you'll get mystery failures with zero helpful output. Sometimes npx caches a broken version and you'll get MODULE_NOT_FOUND errors that make no sense - clear the cache with npm cache clean --force and try again. WSL2 users: prepare for weird permission errors when npm tries to create global symlinks.

Global Install (Recommended)

npm install -g @google/gemini-cli

Standard npm global install. When (not if) you get permission errors on Linux/Mac, fix your npm setup instead of throwing sudo at everything.

Homebrew (If You're Into That)

brew install gemini-cli

Works fine but updates are slower than npm because Homebrew maintainers take their sweet time.

Release Channels (Choose Your Pain Level)

Google maintains three release channels with different levels of broken:

• @latest - Weekly Tuesday releases, supposedly stable
• @preview - Preview builds with new bugs
• @nightly - Daily builds that will definitely break something

Authentication Setup (The 5-Minute Journey That Takes 30)

First run shows you auth options:

OAuth (Best Free Limits)

gemini

Opens browser, sign in with Google. The OAuth flow hangs sometimes - Ctrl+C and try again. OAuth flow takes 2-3 minutes when it works, times out after 5 if it doesn't.

API Key (When You Want to Pay)

export GEMINI_API_KEY=\"your-key-from-aistudio\"
gemini

Get your key from AI Studio. The free tier gives you 100 requests/day vs 1000 with OAuth.

Enterprise Vertex AI

export GOOGLE_API_KEY=\"your-cloud-key\"
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=\"your-project-id\"
gemini

For when you need compliance theater and someone else pays the bill.

Daily Usage Patterns

Start in Your Project

cd my-messy-codebase/
gemini
> Why does my React app randomly crash on mobile?

It automatically scans your files and respects .gitignore. Smart enough to skip node_modules.

Include Multiple Directories

gemini --include-directories ../backend,../shared,../docs

Useful for monorepos or when your project is scattered across folders like a crime scene.

Script Mode (For CI/CD)

gemini -p \"Find all TODO comments and create GitHub issues\" > todos.json

Non-interactive mode works great for automation. Just don't expect it to understand complex project contexts without setup.

Configuration Reality

Three places for settings (because one wasn't enough):

• ~/.gemini/settings.json - Global config
• <project>/.gemini/settings.json - Project overrides
• GEMINI.md - Context file for project-specific instructions

The tool reads your .gitignore and lets you add .geminiignore for AI-specific exclusions. Pro tip: exclude your .env files or you'll accidentally feed secrets to Google. Config files in WSL don't always sync with Windows host, leading to auth mysteriously breaking.

What Works Out of the Box

• Context loading that actually works (unlike some tools)
• Web search that helps with debugging current issues
• File operations with safety confirmations (annoying but necessary)
• Multi-modal support - paste screenshots and it'll understand them

The setup is genuinely straightforward compared to most developer tools. Sometimes it forgets your project structure mid-conversation, but that beats waiting 3 hours for Claude Code to reset your message limit. The hardest part is remembering not to get too attached since Google will probably kill this like everything else they make.