Gemini CLI: agentic coding in your terminal

# Gemini CLI: agentic coding in your terminal

Gemini CLI is Google's open-source agentic coding tool that lives in your terminal: it reads your project, edits files, and runs commands on your behalf, all from a conversational prompt. You stay where you already work (the shell), and the agent does the file-walking, editing, and test-running loop for you.

This lesson takes you through a real "fix this bug and run the tests" session, including install. By the end you will know how to point it at a repo, let it propose changes, approve them, and verify with a test run.

What Gemini CLI actually is

It is a command-line agent. You type a request in natural language, and it plans, reads files, proposes edits, and executes shell commands inside your working directory. It is the same agentic capability that powers Gemini Code Assist in the IDE, but unbundled into a terminal tool you can script and pipepipeAll active sales opportunities across the stages of the sales process, together with their combined potential value and probability of closing.View full definition →.

Three things make it worth your attention as an advanced user:

• Large context handling. Gemini's long context means the agent can pull in many files at once instead of guessing from a single snippet. For big refactors it reads broadly before it acts.
• Built-in tools. It can grep your codebase, read and write files, run shell commands, and ground answers with Google Search when it needs current information.
• It is open source and extensible. You can inspect it, configure it per project, and extend it with the Model Context Protocol (MCP), the open standard for connecting agents to external tools and data.

The official repo and docs live at github.com/google-gemini/gemini-cli.

Install it

You need Node.js installed (a recent LTS version). Then install the CLI globally with npm:

npm install -g @google/gemini-cli
gemini

The first time you run gemini, it walks you through authentication. The simplest path for individuals is signing in with your personal Google account, which grants a generous free tier for the CLI. If you need higher limits or want to bill against a project, you can instead set a GEMINI_API_KEY from Google AI Studio or authenticate against Vertex AI for enterprise use.

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

Pick one auth method and stick with it per environment. Mixing a personal login and an APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → key in the same shell is the most common source of "why is it using the wrong quota" confusion.

The agent loop: how a turn works

Before the walkthrough, understand the loop, because approving steps intelligently is the whole skill here.

1. You prompt. Plain language: "the date parser fails on ISO strings, fix it and make the tests pass."

2. It gathers context. The agent reads relevant files, often grepping for symbols and opening neighbors.

3. It proposes an action. A file edit (shown as a diff) or a shell command (shown before it runs).

4. You approve or reject. Nothing touches disk or runs without your yes, unless you opt into auto-approval.

5. It observes the result. Test output, error traces, command exit codes feed back in.

6. It iterates until the goal is met or it asks you for direction.

That observe-and-iterate behavior is what separates this from autocomplete. A failed test is not a dead end; it is the next input.

Walkthrough: fix a bug and run the tests

Here is a concrete session. Imagine a small Python project with a failing test in a date utility.

Start the CLI from your project root so it has the right working directory:

cd ~/projects/invoice-tool
gemini

Now give it the task. Be specific about the symptom and the success condition:

> The function parse_due_date in billing/dates.py raises ValueError on
  ISO 8601 strings with a timezone offset. Find the bug, fix it, then
  run the test suite and confirm it passes.

What you will see, in order:

It reads the code. The agent opens billing/dates.py and the related test file. Because it has real context, it does not invent function signatures; it works against what is actually there.

It proposes an edit as a diff. For example, it might find that the code uses datetime.strptime with a fixed format and switch to datetime.fromisoformat, which handles offsets. The diff is shown for your review:

- return datetime.strptime(raw, "%Y-%m-%d")
+ return datetime.fromisoformat(raw)

You read the diff, then type y to apply it. This is the moment to actually look. The agent is good, not infallible. A diff that touches files you did not expect is a signal to reject and ask why.

It proposes a command. Next it suggests running the tests. It shows the exact command before executing:

pytest -q

Approve it. The agent runs pytest, captures the output, and reads it.

It iterates if needed. Say two tests now pass but a third still fails because of a naive-vs-aware datetime comparison. The agent sees the traceback, proposes a follow-up edit (normalizing timezone handling), shows the diff, and reruns the suite. When everything is green, it summarizes what it changed and why.

The key move on your side: you supplied the success condition ("tests pass"), so the agent had an objective measure to iterate against. Vague goals produce vague work. Testable goals produce verifiable work.

Controlling what the agent can do

Approving every step is safe but slow. For trusted, repetitive work you can change the approval mode. Within a session you can switch to an auto-approve mode for the current turn, and for fully unattended runs there is a YOLO-style mode that approves actions automatically. Use that only in throwaway environments or sandboxes, never against a repo with uncommitted work you care about.

A safer habit: commit before you start. A clean git state means any agent change is a git diff away from review and git checkout away from undo.

Project memory with GEMINI.md

You can give the agent persistent, project-specific instructions by adding a GEMINI.md file at your repo root. The CLI reads it automatically and treats it as standing context for every session. This is where you encode conventions so you do not retype them.

# Project conventions
- Python 3.12. Use `uv` for env management, not pip directly.
- Run tests with `pytest -q`. Lint with `ruff check .`.
- Prefer `datetime.fromisoformat` over manual format strings.
- Never edit files under `migrations/` without asking first.

Now "run the tests" reliably means pytest -q, and the agent knows the no-go zones. Think of GEMINI.md as the project's onboarding doc for the agent.

Extending the CLI with tools and MCP

Out of the box the agent reads files, runs commands, and grounds with Google Search. The real power for advanced workflows is connecting it to your own systems through MCP servers.

An MCP server exposes tools (functions) and data to the agent over a standard protocol. Connect one for your issue tracker, your database, or an internal APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition →, and the agent can act on those systems too: "look up the failing ticket in our tracker, reproduce it, fix it."

You configure servers in a settings file, typically .gemini/settings.json in your project. A minimal example wiring up a local MCP server:

{
  "mcpServers": {
    "tickets": {
      "command": "node",
      "args": ["./tools/ticket-mcp-server.js"]
    }
  }
}

Once registered, the agent can discover and call the tools that server exposes during a session. This is how you move from "fix the code in front of me" to "fix the thing described in our systems." For building richer multi-step agents beyond the CLI, Google's Agent Development Kit (ADK) is the framework to graduate into; the CLI is the fast, interactive entry point.