Working with Google’s Gemini CLI

Gemini CLI is Google’s open-source AI agent for the terminal: describe a task, and it reads your project, edits files, runs shell commands, and can ground its answers in live Google Search results.

Its standout feature isn’t a capability, it’s the price. Log in with a personal Google account and you get a generous free tier on Gemini’s top models, no API key or credit card required. That makes it the easiest way to put a real coding agent in your terminal for free.

What is it?

Gemini CLI (google-gemini/gemini-cli on GitHub, Apache 2.0 licensed) is the same category of tool as Claude Code and the OpenAI Codex CLI: an agent that operates on your working directory rather than a chat window you paste code into. It ships with built-in tools for file operations, shell execution, web fetch, and Google Search grounding, that last one being something the other CLIs don’t have natively, and genuinely useful when a task depends on current documentation.

Install

Requires Node.js 20+. Install globally through npm:

npm install -g @google/gemini-cli

Homebrew works too (brew install gemini-cli), or run it without installing anything:

npx @google/gemini-cli

Then start it inside a project:

cd ~/Sites/your-project
gemini

Authentication: Free Tier First

On first launch, pick Login with Google. A personal Google account gets you a free Gemini Code Assist license, access to the Pro-tier model with its 1M token context window, with rate limits that were 60 requests/minute and 1,000 requests/day when the free tier launched. Limits shift over time, so check the repo for current numbers, but I haven’t hit them in normal daily use.

Two other auth routes when you outgrow that:

  • Gemini API key from Google AI Studio, exported as GEMINI_API_KEY, pay-as-you-go, and the free API tier works here too
  • Vertex AI, for teams already on Google Cloud with billing and governance requirements

GEMINI.md: Project Context

Like Claude Code’s CLAUDE.md, Gemini CLI reads a GEMINI.md file from your project root into every session. Use it for architecture notes, build commands, and conventions, the things you’d tell a new developer on day one. A global ~/.gemini/GEMINI.md adds your personal preferences across all projects. If you maintain both CLIs, keep the two files in sync; the content is the same job.

Inside a session, /memory show displays what context is loaded and /memory refresh reloads it after edits.

Approval Modes

By default the agent asks before running tools, and you approve each action. The --approval-mode flag sets the posture explicitly:

  • default, prompt for everything
  • auto_edit, auto-approve file edits, still ask for shell commands
  • plan, read-only mode, useful for safe codebase exploration
  • yolo, auto-approve everything (the -y flag; the name is the warning)

There’s also a -s sandbox flag that executes tools in an isolated environment, worth using with the looser approval modes.

Headless Mode for Scripts

The -p flag runs non-interactively and prints the result, and it reads stdin, so it pipes like any Unix tool:

gemini -p "Summarize the uncommitted changes in this repo"
git diff | gemini -p "Review this diff for security issues"

Add -o json for structured output when a script consumes the result. There’s also -i, which runs a prompt and then drops into interactive mode, a nice way to start a session with the task already framed.

Day-to-Day Commands Worth Knowing

  • gemini -r latest, resume your most recent session
  • /tools, list the built-in tools the agent can use
  • /stats, session token usage and remaining quota
  • gemini mcp, manage MCP servers to connect external tools and services
  • gemini extensions and gemini skills, the CLI has grown its own extension and skill system; both are worth exploring once the basics stick

Where It Fits

My daily driver is Claude Code, but Gemini CLI has earned a permanent spot for three things: it’s free to keep installed and use casually, the 1M context window swallows entire codebases in one gulp, and Search grounding answers “what’s the current way to do X” questions the others guess at. If you’re evaluating terminal agents for the first time and don’t want to commit to a subscription, start here, the free tier is the whole pitch. I also build Gemini API integrations into WordPress for clients, including the AI-generated content on parts of this site, and the CLI is a convenient scratchpad for testing prompts against the same models.