Gemini CLI is Google's open-source AI agent for the terminal. You launch it inside a project folder, type what you want in plain English, and it reads your files, writes code, runs shell commands, searches the web and calls external tools through MCP. The code is public on GitHub under an Apache 2.0 license, it runs on macOS, Linux and Windows, and a personal Google account gets you a free usage tier without entering a credit card.

This tutorial takes you from a blank terminal to real work. You will install the CLI, pick a sign-in method, run a first session, learn what each built-in tool does, write a GEMINI.md file so the agent understands your project, and then run five example tasks with the exact prompt to type. A comparison with Claude Code and Codex CLI and a list of common errors close it out.

If you are new to terminal agents in general, the companion Claude Code tutorial for beginners covers the same ground for Anthropic's tool, and the two read well together.

Google ships Gemini in many shapes: the Gemini app, Gemini in Gmail and Docs, NotebookLM, AI Studio and the Gemini API. Gemini CLI is the one that lives in your terminal. It is a command-line program, written in TypeScript, that wraps a Gemini model in an agent loop: it plans, calls a tool, reads the result, and repeats until your request is done. That loop is what separates it from pasting code into a chat window. The agent can open your files itself, run your test suite itself and fix what it broke itself.

Three things make it worth learning even if you already use another agent. First, it is open source, so you can read how every tool works and extend it. Second, the free tier tied to a personal Google account is generous enough for daily use by an individual (check the current limits page for exact numbers, since they change). Third, it has a very large context window, which means it can hold a big chunk of a codebase in memory at once and reason across it.

The same engine also powers Gemini Code Assist's agent mode in VS Code and the GitHub Actions integration, so the habits you build here transfer. If you want to understand how these agents work under the hood before touching one, read how to build an AI agent for beginners first; it explains the plan, act, observe loop that Gemini CLI runs for you.

You need Node.js version 20 or newer and a terminal. On Windows, use PowerShell or WSL; on macOS and Linux, any shell works. Check your Node version first.

node --version

If it prints a version below 20, upgrade Node before continuing.

There are two install paths. The global install puts a gemini command on your path permanently, which is what you want for daily use:

npm install -g @google/gemini-cli

The npx path runs it without installing anything:

npx @google/gemini-cli

Use npx to try it once; use the global install otherwise.

On macOS, Homebrew is a third option that keeps the CLI updated alongside your other tools:

brew install gemini-cli

Whichever path you chose, confirm the command works.

gemini --version

You should see a version number and no error.

Later, update a global install with the same npm command you used to install it. If you run into a permissions error on Linux during the global install, do not reach for sudo; the fix is in the errors section at the end of this article.

Run gemini once inside a project folder and the first screen asks how you want to authenticate. There are three real choices, and the right one depends on who pays and how much you plan to use it.

Login with Google. This is the default for individuals. Pick it, a browser tab opens, you approve access with a personal Google account, and the token is stored locally. You get the free tier at no cost, with a daily and per-minute request allowance. Check the current limits page for the exact numbers rather than trusting a blog post. If your Google account belongs to a Workspace organization, the CLI may ask for a Google Cloud project ID; set it with GOOGLE_CLOUD_PROJECT in your shell.

Gemini API key. Open Google AI Studio, click Get API key, create one, and export it before launching the CLI:

export GEMINI_API_KEY="your-key-here"

Then run gemini and choose the API key option.

An API key gives you pay-as-you-go billing through your Google Cloud or AI Studio account, and it is the route to take when the free login tier is not enough or when you want to script the CLI on a server where a browser login is impractical. Never commit that key to a repo; put it in your shell profile or a .env file that is ignored by git.

Vertex AI. Enterprise teams that already run Gemini through Google Cloud can point the CLI at Vertex by setting GOOGLE_API_KEY and GOOGLE_GENAI_USE_VERTEXAI=true. Skip this unless your company has told you to use it.

To switch methods later, type /auth inside a session. The choice is stored in ~/.gemini/settings.json, which is also where most other preferences live.

With auth done, you land in the interactive prompt. Pick a theme when asked (you can change it later with /theme), then type your first request. Start with something read-only so you can watch how the agent works before letting it change anything:

Explain what this project does and how it is organized. Do not change any files.

Watch the tool calls appear as it reads files.

Each time the agent wants to use a tool, it shows you the call. Read-only tools such as file reads and searches run without asking. Anything that writes a file or runs a shell command pauses and offers three choices: allow once, allow always for this session, or cancel. Say yes to file writes you have reviewed and be more careful with shell commands, exactly as you would with a new contractor who has your laptop.

Two input shortcuts matter from day one. Type @ followed by a path to pull a file or folder into the prompt, for example @src/auth.ts explain the login flow. Type ! followed by a shell command to run it yourself without leaving the session, for example !git status. Press Ctrl+C to stop a running task and /quit or Ctrl+D to leave.

You can also skip the interactive screen entirely and use the CLI like any other Unix tool with the -p flag:

gemini -p "Summarize the last 10 git commits in one paragraph"

That mode is how you script it or pipe input from other commands.

For experienced users there is --yolo, which auto-approves every tool call. Do not enable it on a project you have not committed. If you want to let the agent run freely but safely, use --sandbox, which runs tool calls inside a container so a wrong rm cannot touch your real disk.

Type /tools in any session and the CLI lists what the agent can call. The names change slightly between releases, but the families are stable and worth knowing, because the quality of your prompts improves once you know what the agent can actually do.

File tools. Read a file, read many files at once, list a directory, search file contents with a regex, find files by glob pattern, write a new file, and edit an existing file by replacing an exact block of text. The edit tool is the one you will see most, and it shows you a diff before it applies the change.

Shell. Runs any command in your shell and feeds the output back to the model. This is how it runs tests, installs packages, runs build scripts and inspects git history. Every shell call asks for approval unless you have allowed that exact command for the session.

Web tools. A Google search tool that grounds answers in current results, and a fetch tool that pulls the content of a URL you give it. Ask it to look up a library's changelog before upgrading and it will use both.

Memory. A save-memory tool that appends a fact to your global GEMINI.md so it persists across sessions. Tell it "remember that I prefer pnpm over npm" and it writes that line for you.

MCP servers. The Model Context Protocol is an open standard for plugging external tools into an agent. Gemini CLI reads an mcpServers block in ~/.gemini/settings.json or a project-level .gemini/settings.json, launches each server, and exposes its tools to the model. That is how you give the agent a database, a GitHub connection or a browser. A minimal entry looks like this:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    }
  }
}

Restart the CLI and run /mcp to confirm it connected.

For the full picture of how servers, tools and clients fit together, read what is MCP, the Model Context Protocol. The same servers you configure here work in Claude Code and Codex CLI with a slightly different config file, so the effort is not wasted if you switch.

GEMINI.md is a plain Markdown file the CLI loads into context at the start of every session. It plays the same role as CLAUDE.md in Claude Code and AGENTS.md in Codex CLI: it is where you write what a new teammate would need to know before touching the code. The agent reads it automatically; you never paste it.

The files are hierarchical. The CLI looks in three places and concatenates what it finds: a global file at ~/.gemini/GEMINI.md for preferences that apply to every project, a project file at the repository root, and any GEMINI.md in the subfolder you are currently working in. That lets you keep a short global file, a medium project file, and very specific notes inside, say, packages/api/. Run /memory show in a session to see exactly what got loaded and /memory refresh after you edit a file.

A good project file is short and concrete. Here is a starting point you can copy:

# Project notes for Gemini

## Stack
- Next.js app in /app, API routes in /app/api, Postgres via Drizzle
- Package manager: pnpm (never npm or yarn)

## Commands
- Tests: pnpm test
- Type check: pnpm tsc --noEmit
- Never run pnpm build; it is deployed from CI

## Rules
- Run the type check before you say a task is done
- Do not edit files in /generated; they are produced by a script
- Prefer small diffs; ask before touching more than 5 files

Write rules as commands, not as background prose.

The sections that pay off fastest are the ones that stop the agent from doing something expensive or wrong: the build command it must not run, the folder it must not edit, the test it must run before declaring victory. Add a rule every time the agent makes the same mistake twice.

Over a month the file becomes the most valuable document in the repo, and it doubles as onboarding for humans. If you already have a CLAUDE.md, you can keep both files nearly identical; the guide to Claude Code skills guide covers a structure that ports to Gemini without changes.

Two launch flags, listed with the slash commands below, change how a session behaves from the start. gemini -m <model> picks a specific Gemini model instead of the default, useful when you want the faster Flash tier for cheap tasks. gemini --checkpointing snapshots your files before every edit so /restore has something to restore. Turn it on permanently in ~/.gemini/settings.json and forget about it. Add --sandbox when you want to let the agent run commands with less supervision, and reserve --yolo for throwaway projects.

Reading about tools teaches less than running five real tasks. Each one below is safe on a real repository if your working tree is committed first. Copy the prompt exactly, press Enter, and review the diff with git diff afterward.

Task 1: Explain an unfamiliar codebase. Clone any open-source project you have never read and run this from its root:

Give me a map of this codebase: entry points, the main modules and what each one owns, how a request flows through it, and the three files I should read first. Do not modify anything.

Ten minutes of reading becomes a two-minute briefing.

Task 2: Add tests to a file that has none. Pick a small utility module and hand it over with the @ syntax:

@src/utils/dates.ts Write unit tests for every exported function in this file using the test framework already configured in this project. Cover edge cases like empty input and invalid dates. Run the tests and fix any failures before you finish.

Approve the file write, then the shell call.

Task 3: Fix a bug from an error message. Paste the real stack trace from your logs:

When a user submits the signup form the server logs: Cannot destructure property 'email' of 'req.body' as it is undefined, at handleSignup (app/api/signup/route.ts:42). Find the cause, explain it in two sentences, then fix it and add a regression test.

Read the explanation before you approve the fix.

Task 4: Upgrade a dependency safely. This one uses the web tools and the shell together:

We are on an old major version of zod. Look up the current version and its migration guide, list every breaking change that affects this codebase, apply the migration, run the type check and the tests, and summarize what you changed.

Watch it search, then edit, then run tests.

Task 5: Batch work in a script. Use non-interactive mode from a shell loop to process many files:

for f in docs/*.md; do
  gemini -p "Fix spelling and grammar in this file without changing its meaning or formatting. Output only the corrected file." < "$f" > "$f.fixed"
done

Review a couple of outputs before replacing the originals.

Notice the pattern across all five prompts: state the goal, name the files or the error, say what done looks like (tests pass, type check passes, summary written), and say what the agent must not touch. That structure is the whole art of working with terminal agents, and it is covered in depth in the prompt engineering guide. The AI Mastery course turns it into a habit: the agent modules walk through AI Mastery course agent modules so you learn the pattern once and apply it anywhere.

The three big terminal agents are closer than their marketing suggests. All of them run in your shell, read your repo, ask before writing, load a Markdown instructions file, and speak MCP. The differences are in who makes the model, how you pay, and what extras ship in the box.

A practical way to choose: start with Gemini CLI if you want a zero-cost way to learn how agents behave. Move to Claude Code when you need the deepest customization (hooks, skills, subagents) and are willing to pay for it; what is Claude Code explains those features.

Pick Codex CLI when your team already lives in ChatGPT and wants the cloud agent that opens pull requests from a sandbox; the OpenAI Codex CLI tutorial walks through that setup. Many developers keep two installed and use whichever has quota left that day, which is a perfectly reasonable strategy.