# How to use Gemini CLI: a step-by-step guide

URL: https://agentvera.dev/en/blog/how-to-use-gemini-cli/ · Published: 2026-10-25

How to use Gemini CLI: install it, choose a sign-in after the June 2026 change, write GEMINI.md, edit settings.json, add MCP servers and undo edits with checkpoints.

**In short:**

- Install Gemini CLI with npm, Homebrew or MacPorts, or try it with npx, then run gemini in a project folder and pick a sign-in method.
- Since June 18, 2026, unpaid tier and Google One users were moved to Antigravity CLI; Gemini CLI now works with paid Gemini API keys, Vertex AI and Code Assist Standard or Enterprise.
- Project rules go in GEMINI.md, settings in .gemini/settings.json, MCP servers are added with gemini mcp add, and checkpointing plus /restore lets you undo file edits.

To use Gemini CLI, install it with npm or Homebrew, run `gemini` inside a project folder, choose how to sign in, and then describe what you want in plain English. Gemini reads your files, proposes edits and shell commands, and by default asks before it runs each one.

Before you start, one important caveat. **Since June 18, 2026, Gemini CLI no longer serves unpaid tier and Google One users.** Google moved those users to Antigravity CLI. Gemini CLI keeps working with a paid Gemini API key, Vertex AI or a Gemini Code Assist Standard or Enterprise license. This guide covers install, sign-in, `GEMINI.md`, settings, MCP, approval modes, slash commands, checkpointing and resume. Everything here follows Google’s official Gemini CLI documentation as of October 2026.

## What Gemini CLI is

Gemini CLI is Google’s open-source coding agent for the terminal. It runs Gemini models, reads and edits files in the folder you start it from, runs shell commands, searches the web, connects to MCP servers and takes project instructions from `GEMINI.md`. It’s a [coding agent](/en/glossary/coding-agent/ "What is a coding agent"), not an autocomplete: you hand it a task and it works through it step by step. For a side-by-side with other agents, see [Gemini CLI vs Claude Code](/en/blog/gemini-cli-vs-claude-code/ "Gemini CLI vs Claude Code") and [Codex vs Gemini CLI](/en/blog/codex-vs-gemini-cli/ "Codex vs Gemini CLI").

## Step 1: install Gemini CLI

Gemini CLI needs Node.js. Pick whichever install fits your setup:

| Method | Command |
| --- | --- |
| Try it without installing | `npx @google/gemini-cli` |
| npm (any platform) | `npm install -g @google/gemini-cli` |
| macOS, Linux (Homebrew) | `brew install gemini-cli` |
| macOS (MacPorts) | `sudo port install gemini-cli` |

There are three release channels on npm: `@latest` (stable, weekly), `@preview` (weekly, ahead of stable) and `@nightly`. Most people should stay on stable. To update later, run `gemini update` or reinstall through your package manager. Check the install:

```bash
gemini --version
```

## Step 2: choose how to sign in

Move into a project and start it:

```bash
cd my-project
gemini
```

On first launch Gemini CLI asks how you want to authenticate. There are three options:

- **Sign in with Google:** opens the browser. After the June 2026 change this is for organizations with a Gemini Code Assist Standard or Enterprise license; set `GOOGLE_CLOUD_PROJECT` to your Google Cloud project ID before you start.
- **Gemini API key:** create a key in Google AI Studio and set `GEMINI_API_KEY`. Usage is billed per token on a paid key.
- **Vertex AI:** for teams on Google Cloud. Set `GOOGLE_API_KEY` and `GOOGLE_GENAI_USE_VERTEXAI=true`, or use your Cloud credentials.

```bash
export GEMINI_API_KEY="your-key"
gemini
```

You can switch methods later with `/auth`. If you were using Gemini CLI on a free personal account, Google’s notice points you to Antigravity CLI instead; [Gemini CLI vs Claude Code](/en/blog/gemini-cli-vs-claude-code/ "Gemini CLI vs Claude Code") covers the move in detail. Check [Google’s Gemini API pricing](https://ai.google.dev/gemini-api/docs/pricing "Gemini API pricing") for current rates before you run long sessions on a key.

## Step 3: your first task

Start with something small and real:

```text
Explain how the payment module is structured, then add input validation
to the refund endpoint and run the tests.
```

Gemini will read the files it needs, show you each edit and command, and wait for your OK. A few shortcuts help from day one:

- `@path/to/file` adds a file (or a whole folder) to your prompt.
- `!git status` runs a shell command directly. A bare `!` toggles shell mode on and off.
- `gemini -p "summarize README.md"` runs a single prompt without the interactive UI and prints the answer. Add `--output-format json` when a script needs to read the result.
- `/copy` copies the last answer to the clipboard.

## Step 4: write a GEMINI.md

`GEMINI.md` is a Markdown file of instructions that Gemini CLI loads and sends with every prompt: how to build and test, code style, what not to touch. Run `/init` and Gemini generates a first version from your project. Keep it short and concrete:

```markdown
# Project: billing-service

## Commands
- Install: npm ci
- Test: npm test (run before you say a task is done)

## Style
- TypeScript, 2-space indent, strict equality only.
- New endpoints go in src/routes and need a test.

## Don't
- Don't edit files in src/generated.
```

Gemini CLI loads context files in layers and joins them together:

1. **Global:** `~/.gemini/GEMINI.md`, your personal defaults for every project.
2. **Workspace:** `GEMINI.md` files in your project folder and its parent folders.
3. **Just in time:** when a tool touches a file in a subfolder, Gemini also picks up any `GEMINI.md` in that folder and its parents.

You can split a long file with imports, for example a line `@./docs/style-guide.md`. To see what the model actually receives, run `/memory show`; `/memory list` shows which files were loaded. After you edit a file mid-session, reload it with `/memory reload`.

If your repo already has an `AGENTS.md`, you don’t need to duplicate it. Set `context.fileName` in settings to `["AGENTS.md", "GEMINI.md"]`. [CLAUDE.md vs AGENTS.md](/en/blog/claude-md-agents-md/ "CLAUDE.md and AGENTS.md") explains how to keep one set of rules for several agents.

## Step 5: settings.json

Gemini CLI reads settings from JSON files:

- `~/.gemini/settings.json` for your user settings;
- `.gemini/settings.json` inside a project for workspace settings.

Run `/settings` to change most options in an editor inside the CLI instead of editing JSON by hand. A small example:

```json
{
  "general": {
    "defaultApprovalMode": "auto_edit",
    "checkpointing": { "enabled": true }
  },
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}
```

The model can be set per run with `-m` / `--model`. The aliases `auto` (the default), `pro`, `flash` and `flash-lite` let you pick by speed and depth without remembering exact model names; `/model` changes it in a session.

## Step 6: approval modes and the sandbox

Gemini CLI asks before running tools unless you tell it otherwise. The `--approval-mode` flag sets the behavior:

| Mode | What happens |
| --- | --- |
| `default` | Asks before every tool call |
| `auto_edit` | Approves file edits automatically, still asks before other tools such as shell commands |
| `plan` | Read-only: Gemini can look and plan but not change anything |
| `yolo` | Approves every tool call; only for an isolated environment |

The older `--yolo` flag still exists but is deprecated in favor of `--approval-mode=yolo`. You can make `auto_edit` or `plan` the default in settings; yolo can only be turned on from the command line.

The sandbox is **off by default**. Start with `--sandbox` (or `-s`) to run tools in an isolated environment: Seatbelt on macOS, or a Docker or Podman container. If you want to use `auto_edit` or yolo regularly, turn the sandbox on first. [AI coding agent security](/en/blog/ai-coding-agent-security/ "AI coding agent security") explains why approvals alone aren’t enough.

## Step 7: connect MCP servers

[MCP](/en/glossary/mcp/ "What is MCP") servers give Gemini extra tools: documentation lookup, a browser, GitHub, your database. Add one from the shell:

```bash
gemini mcp add github npx -y @modelcontextprotocol/server-github
```

For an HTTP server, add `--transport http` and a URL instead of a command. `--env KEY=value` passes environment variables, and `--scope user` makes the server available in every project instead of just this one. `gemini mcp list` shows what’s configured and `gemini mcp remove <name>` deletes a server.

Under the hood these go into the `mcpServers` section of `settings.json`, so you can also edit them there. Inside a session, `/mcp` lists servers and their tools, `/mcp auth` signs in to servers that use OAuth, and `/mcp reload` restarts them. New to the idea? Read [what is an MCP server](/en/blog/what-is-mcp-server/ "What is an MCP server"). Every server adds tool descriptions to the [context window](/en/glossary/context-window/ "What is a context window"), so only keep the ones you use.

## Step 8: the slash commands worth knowing

| Command | What it does |
| --- | --- |
| `/init` | Generate a `GEMINI.md` for the project |
| `/memory show` | Show the instructions the model is getting |
| `/settings` | Open the settings editor |
| `/model` | Change the model |
| `/auth` | Change the sign-in method |
| `/mcp` | List MCP servers and tools |
| `/tools` | List the tools Gemini can use |
| `/stats` | Session, model and tool usage |
| `/compress` | Replace the conversation with a summary to save tokens |
| `/clear` | Clear the screen and start fresh |
| `/resume` | Browse and resume saved sessions |
| `/rewind` | Step back through the conversation (also Esc twice) |
| `/restore` | Restore files from a checkpoint |
| `/directory` | Add more folders to the workspace |
| `/help` | List every command |

You can also write your own commands. A `.toml` file in `~/.gemini/commands/` becomes a personal slash command, and one in `.gemini/commands/` inside a project is shared with everyone who uses the repo. `/commands list` shows them.

## Step 9: checkpointing and undo

Checkpointing is Gemini CLI’s safety net, and it’s **off by default**. Turn it on in `settings.json`:

```json
{
  "general": {
    "checkpointing": { "enabled": true }
  }
}
```

From then on, every time you approve a tool that changes files, Gemini first saves a snapshot of your project in a separate shadow git repository under `~/.gemini/history/`. It doesn’t touch your own git history. Run `/restore` to see the list of checkpoints, and `/restore <id>` to put your files and the conversation back to that point. Gemini then offers the original tool call again, so you can rerun it, change it or skip it.

Even without checkpointing, `/rewind` (or Esc twice) lets you go back to an earlier prompt and choose to undo the conversation, the code changes or both.

## Step 10: resume sessions

Gemini CLI saves your sessions per project:

- `gemini --resume latest` (or `-r latest`) continues the most recent session.
- `gemini --list-sessions` shows the saved sessions with numbers; `gemini --resume 3` opens one of them.
- Inside a session, `/resume` lets you browse, save and reopen conversations.

You can also pass a new prompt right away: `gemini -r latest "check for type errors"`.

## Tips for better results

- **Commit before big tasks.** Checkpoints are good; a git commit is better and works with every tool.
- **Say how to verify.** “Run `npm test` and fix failures” beats “make it work”.
- **Use plan mode for bigger changes.** Let Gemini look around and propose a plan before it edits anything.
- **Reference files with `@`.** It’s faster than waiting for Gemini to find them and keeps context focused.
- **Compress or clear between tasks.** `/compress` keeps a summary; `/clear` starts over. Either one saves tokens.
- **One agent per worktree.** If you run more than one agent, give each its own [git worktree](/en/blog/git-worktree-parallel-agents/ "Git worktrees for parallel agents") so they don’t overwrite each other.

## When one terminal isn’t enough

Gemini CLI is often one of several agents a team uses. Once you want Gemini on one task and Codex or Claude Code on another, or one agent checking another’s work, a single terminal gets crowded.

AgentVera is a desktop app for macOS, Windows and Linux that runs Gemini CLI (and other CLI agents) in real terminals, side by side. Each Gemini agent uses its own Google sign-in or `GEMINI_API_KEY`; the terminal asks which on first launch. See the [Gemini CLI in AgentVera](/en/agents/gemini-cli/ "Gemini CLI in AgentVera") page for details.

- **[Workspace](/en/features/workspace/ "Workspace"):** a grid of agents per project, from 1×1 to 5×4. Each Gemini agent starts with its own session and reopens it after a relaunch.
- **Permissions per agent:** choose Ask, Auto or Full access when you create the agent.
- **Instructions:** Gemini CLI has no flag for extra instructions, so AgentVera’s Role field doesn’t reach it. Put the rules in `GEMINI.md` or `AGENTS.md` instead.
- **[MCP manager](/en/features/mcp-manager/ "MCP manager"):** servers you set up in AgentVera attach to Gemini on launch, merged by name with your own Gemini settings.
- **[Flows](/en/features/flows/ "Flows"):** pass one agent’s result to the next, for example Gemini writes and another agent reviews.
- **[Code review](/en/features/code-review/ "Code review"):** review an agent’s changes automatically at the end of a turn.
- **Worktrees:** create one from the [Git panel](/en/features/git-and-github/ "Git and GitHub") and start an agent in it.

The grid, worktrees, code review and the MCP manager are on the free plan; flows are on Pro and Team. [Download AgentVera](/en/download/ "Download AgentVera") and try it on your own repo. If you’re on a free Google account, AgentVera also supports [Antigravity](/en/agents/antigravity/ "Antigravity in AgentVera").

## Wrapping up

Install Gemini CLI, run `gemini`, and pick a sign-in that still works after June 2026: a paid API key, Vertex AI or a Code Assist license. Run `/init` and keep your `GEMINI.md` short, set defaults with `/settings`, and add MCP servers only when you need them. Stay in the default approval mode until you trust the setup, turn on checkpointing so `/restore` can undo edits, and use `--resume latest` to pick up where you left off. To compare with OpenAI’s agent, read [how to use Codex CLI](/en/blog/how-to-use-codex-cli/ "How to use Codex CLI").

## Frequently asked questions

**Is Gemini CLI still free?** Not for personal accounts. Google’s notice says that on June 18, 2026, unpaid tier and Google One users were moved to Antigravity CLI. Gemini CLI keeps working with paid Gemini API keys, Vertex AI and Gemini Code Assist Standard or Enterprise licenses.

**What is the difference between GEMINI.md and AGENTS.md?** Both are Markdown files of project instructions. Gemini CLI reads GEMINI.md by default. If your team already keeps rules in AGENTS.md, set context.fileName in settings.json to a list such as ["AGENTS.md", "GEMINI.md"] and Gemini CLI will read both.

**How do I stop Gemini CLI from running commands without asking?** Stay in the default approval mode, which asks before every tool call. auto_edit approves file edits but still asks before other tools, and yolo approves everything, so only use yolo inside a sandbox you trust.

**How do I undo a change Gemini CLI made?** Turn on checkpointing in settings.json. Gemini CLI then saves a snapshot before each file edit, and /restore puts your files back. Without checkpointing, /rewind (or Esc twice) can still step back through the conversation and its file changes.

**How do I continue an earlier Gemini CLI session?** Start Gemini CLI with --resume latest to continue the most recent session, or run gemini --list-sessions and resume one by its number. Inside a session, /resume lets you browse and pick a saved conversation.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/