Gemini CLI: agentic coding in your terminal

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:

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.

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:

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

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:

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:

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.

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.

Scripting it (non-interactive mode)

Because it is a CLI, you can run it non-interactively 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 → its output. This makes it usable in scripts and CI-adjacent tooling. Pass a prompt directly and let it run headless:

gemini -p "Summarize the changes in the last commit and flag any
  function that lost test coverage." > review-notes.md

Combine that with git hooks or a manual pre-PR step to get an automated reviewer's first pass. Keep these prompts narrow and read-only when running unattended; reserve file-editing runs for interactive, approved sessions.

When to reachreachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → for the CLI vs code assist

Both share the same agentic engine, so the choice is about where you live.

• Gemini CLI when you are in the terminal: quick fixes, scripted runs, server boxes without an IDE, or piping output into other tools.
• Gemini Code Assist when you are in your editor (VS Code, JetBrains, etc.) and want inline diffs, chat alongside your code, and tight IDE integration.

Many developers use both in the same day. The CLI is the Swiss Army knife; Code Assist is the workbench. The next lesson covers Code Assist in depth.

Key Takeaways

• Install with npm install -g @google/gemini-cli, run gemini from your project root, and pick a single auth method (personal login, 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 from AI Studio, or Vertex AI) per environment.
• Always give the agent a testable success condition ("make the tests pass"), so it can observe results and iterate instead of guessing.
• Commit before you start and review every diff and command before approving; reserve auto-approve modes for sandboxes only.
• Use a GEMINI.md file to encode project conventions and no-go zones once, so the agent stops needing reminders.
• Extend the CLI with MCP servers in .gemini/settings.json to let it act on your real systems, and graduate to the ADK when you need to build standalone agents.