🔵 Gemini CLI: the agent with the free tier that actually works

What Gemini CLI is

Gemini CLI is Google’s open-source terminal agent — Apache 2.0, on GitHub, powered by Gemini models. It does what Claude Code and Codex CLI do: reads the repo, edits files, runs commands, iterates.

The difference is the on-ramp. A personal Google account gets you a free tier — no card, no trial that expires in 14 days. That single fact is why it’s the first cloud agent most people should install.

Step 1 — Install

Node.js 20+ required:

npm install -g @google/gemini-cli

Check:

gemini --version
# 0.67.0

Step 2 — Authenticate (pick one)

cd ~/projects/my-app
gemini

Three paths:

Choose “Login with Google”, finish the browser flow. The free tier is generous enough to learn on: 1,000 requests a day is a lot of agent turns when you’re not looping over a monorepo.

Step 3 — First task

Inside a git repo with a clean working tree:

git status
gemini

> read the repo, then explain how authentication works end to end

Then something with consequences:

> the /health endpoint returns 500 when the database is down — reproduce it and fix it

It will read files, propose edits, and ask before running commands. Same discipline as any agent: read the diff, don’t approve blind. The agent loop, explained →

Step 4 — The four moves that change how you use it

@ pulls a file (or a folder) into the prompt. No copy-paste, no “here is my code:” wall:

> @src/auth/session.ts why does this token never expire?
> @docs/ explain the architecture to a new hire

! runs a shell command without leaving the session. Prefix a line with ! for a single command, or type ! alone to toggle shell mode:

! git log --oneline -15
! npm test -- --run

/memory writes durable facts the agent carries into later sessions:

/memory add This repo uses pnpm, never npm. Tests run with `pnpm test`.

/init scans the repo and proposes a GEMINI.md — the project instruction file, the Gemini equivalent of CLAUDE.md and AGENTS.md.

Step 5 — Commands worth memorizing

Step 6 — Context is a budget

Gemini models have very large context windows, and it’s tempting to dump the whole repo in. Don’t. A 1M-token window still costs money, still gets slower, and long contexts degrade instruction-following — the “lost in the middle” problem is real. Context windows, demystified →

Practical rules:

• @ the three files that matter, not @src/.
• Keep GEMINI.md under ~100 lines.
• /compress when a session drifts, /clear when it’s lost.

Where it fits

The honest recommendation: install Gemini CLI first because it’s free, then add the others when a specific need shows up — a Claude subscription you already pay for, or a local model you want an agent on top of.