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

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, 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 and Codex vs Gemini CLI.

Step 1: install Gemini CLI

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

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:

gemini --version

Step 2: choose how to sign in

Move into a project and start it:

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.

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 covers the move in detail. Check Google’s 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:

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:

# 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 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:

{
  "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:

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 explains why approvals alone aren’t enough.

Step 7: connect MCP servers

MCP servers give Gemini extra tools: documentation lookup, a browser, GitHub, your database. Add one from the shell:

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. Every server adds tool descriptions to the context window, so only keep the ones you use.

Step 8: the slash commands worth knowing

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:

{
  "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 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 page for details.

• 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: servers you set up in AgentVera attach to Gemini on launch, merged by name with your own Gemini settings.
• Flows: pass one agent’s result to the next, for example Gemini writes and another agent reviews.
• Code review: review an agent’s changes automatically at the end of a turn.
• Worktrees: create one from the Git panel 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 and try it on your own repo. If you’re on a free Google account, AgentVera also supports Antigravity.

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.