Gemini CLI Cheat Sheet [Cheat Sheet]

Gemini CLI ships with five subcommand groups, more than 30 flags, an interactive REPL with 25+ slash commands, a custom-commands system based on TOML files, the Skills framework, MCP server management, sandboxing via Docker or Podman, checkpointing for safe rollbacks, multi-directory workspace support, GEMINI.md project memory, and the ability to migrate hooks from Claude Code. The official docs scatter that surface across a dozen pages. This cheat sheet collapses everything into one reference, with real outputs captured on Ubuntu 26.04 LTS using Gemini CLI 0.40.1 against a paid Google AI Studio API key.

Original content from computingforgeeks.com - post 167354

If you came from the Gemini CLI install guide and want one page open while you code, this is it.

Verified working: May 2026 with Gemini CLI 0.40.1 against gemini-2.5-flash-lite, gemini-2.5-pro, and gemini-3-flash-preview on Ubuntu 26.04 LTS (Linux kernel 7.0).

Quick install reminder

sudo npm install -g @google/gemini-cli
gemini --version

0.40.1

For the full prerequisites (Node 20+, browser auth, free-tier quota notes) and platform-specific install paths, the dedicated Gemini CLI install walkthrough covers Linux, macOS, and Windows.

Top-level command map

Command	Purpose
`gemini`	Launch the interactive TUI agent (default).
`gemini [query]`	Open the TUI seeded with an initial prompt.
`gemini -p "..."`	Headless one-shot mode, prints to stdout.
`gemini -i "..."`	Run the prompt, then stay in the REPL.
`cat file \| gemini`	Pipe stdin into a query.
`gemini -r latest`	Resume the most recent session.
`gemini mcp`	Manage MCP servers (add, remove, list, enable, disable).
`gemini extensions`	Install, list, link, validate, update, enable, disable extensions.
`gemini skills`	Manage agent skills (install, link, list, enable, disable, –all variants).
`gemini hooks`	Migrate hooks from Claude Code (currently the only subcommand).
`gemini gemma`	Local Gemma model routing (setup, start, stop, status, logs).

Authentication and config

On first launch the CLI looks for one of three auth methods. Pick the one that matches your account:

Google OAuth (free tier): launch gemini in a desktop session, follow the browser flow. ~60 requests per minute, ~1,000 requests per day.
API key: set GEMINI_API_KEY from a Google AI Studio key. Best for servers, CI, and headless boxes.
Vertex AI: set GOOGLE_GENAI_USE_VERTEXAI=true with a service account. Best for enterprise or GCP-billed teams.

Real error from a fresh box without keys:

$ gemini -p 'echo /help' --output-format text
Please set an Auth method in your /root/.gemini/settings.json
or specify one of the following environment variables before running:
  GEMINI_API_KEY, GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_GENAI_USE_GCA

And a real free-tier quota error when the daily window is hit:

* Quota exceeded for metric: generativelanguage.googleapis.com/generate_content_free_tier_requests,
  limit: 5, model: gemini-3-flash
Please retry in 718.667265ms.
Suggested retry after 60s.

Run /stats inside the REPL to see live token usage, or watch the JSON output of --output-format json in headless mode (it prints a full stats object after every call).

API key on a Linux server

export GEMINI_API_KEY="aiza..."
echo 'export GEMINI_API_KEY="aiza..."' >> ~/.bashrc
gemini --list-extensions

Where the CLI stores state

Real layout from a working install after a few sessions:

$ ls -la ~/.gemini/
drwxr-xr-x  history/                 # interactive REPL transcripts per project
-rw-r--r--  installation_id          # anonymized telemetry id
-rw-r--r--  projects.json            # known projects map
drwxr-xr-x  tmp/                     # tool sandbox scratch
drwxr-xr-x  commands/                # custom TOML slash commands
# settings.json appears once you save preferences via /settings or by hand

The projects.json tracks which directories you have used the CLI in:

$ cat ~/.gemini/projects.json
{
  "projects": {
    "/root":           "root",
    "/root/gem-demo":  "gem-demo"
  }
}

settings.json hierarchy and full schema

Settings load in this priority order. Top of the list wins:

Project: ./.gemini/settings.json
User: ~/.gemini/settings.json
System: /etc/gemini-cli/settings.json (only used when present, useful for managed installs)

Annotated reference covering the keys most users actually touch:

{
  "selectedAuthType": "USE_GEMINI",        // OAuth | USE_GEMINI | VERTEX
  "theme": "Default Dark",
  "vimMode": false,                        // vim keybindings in the input
  "preferredEditor": "vim",                // for /editor and Ctrl+X
  "autoAccept": false,                     // auto-confirm read-only tool calls
  "checkpointing": { "enabled": true },    // enables /restore
  "sandbox": "docker",                     // docker | podman | false
  "usageStatisticsEnabled": false,         // anonymous telemetry
  "includeDirectories": [
    "../backend",
    "../frontend"
  ],
  "fileFiltering": {
    "respectGitIgnore":     true,
    "respectGeminiIgnore":  true
  },
  "chatCompression": {
    "contextPercentageThreshold": 60       // trigger /compress at 60%
  },
  "customThemes": {
    "my-theme": { /* color tokens */ }
  },
  "excludeTools": ["run_shell_command"],   // blacklist tools entirely
  "coreTools": ["read_file", "write_file"],// whitelist core tools (others off)
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "timeout": 15000,
      "trust": false,
      "includeTools": ["search_docs"],
      "excludeTools": ["delete_doc"]
    }
  },
  "telemetry": { "enabled": false }
}

Project-scoped overrides live in ./.gemini/settings.json at the root of the repo. Same schema applies, project values override user values.

.geminiignore

Drop a .geminiignore at the repo root to keep the agent away from generated files, secrets, and large directories. Same syntax as .gitignore:

# .geminiignore
node_modules/
dist/
.next/
.env
.env.*
*.log
secrets/
infra/state/

GEMINI.md project memory

A GEMINI.md at the project root is auto-loaded into context every session. The pattern mirrors CLAUDE.md in the .claude directory. Memory loads hierarchically: global (~/.gemini/GEMINI.md), then project, then any per-subdirectory GEMINI.md for the path you are working in.

Imports work via @./path syntax inside any GEMINI.md:

# GEMINI.md
@./docs/architecture.md
@./docs/coding-style.md

## Project context
This is a Go microservice that...

## Build and test
- Build: `make build`
- Test:  `go test ./...`
- Lint:  `golangci-lint run`

Generate a starter file with /init from inside the REPL. Reload after edits with /memory refresh.

Global flags reference

Flag	Purpose
`-m, --model`	Override the model. Aliases: `auto`, `pro`, `flash`, `flash-lite`. Or full IDs.
`-p, --prompt`	Run headless. Prompt prints, agent answers, process exits.
`-i, --prompt-interactive`	Seed the TUI with a prompt and stay interactive.
`-y, --yolo`	Auto-approve every action. Same as `--approval-mode yolo`.
`--approval-mode`	`default`, `auto_edit`, `yolo`, or `plan` (read-only).
`-w, --worktree`	Run in a fresh git worktree. Pass a name or auto-generate.
`-s, --sandbox`	Run tool calls in the configured sandbox (Docker or Podman).
`--skip-trust`	Trust the current workspace for this session only.
`--checkpointing`	Enable per-edit snapshots. Restore via `/restore`.
`-r, --resume`	Resume a previous session. `latest` or an index.
`--list-sessions`	Print sessions for the current project.
`--delete-session N`	Delete a session by index.
`--include-directories`	Add directories to the workspace map (repeatable, comma-separated).
`-e, --extensions`	Restrict the active extension set for this session.
`-l, --list-extensions`	List installed extensions and exit.
`-o, --output-format`	`text`, `json`, or `stream-json`. Use `json` for scripting.
`--policy` / `--admin-policy`	Load Policy Engine policy files for team-level lockdown.
`--allowed-mcp-server-names`	Only enable named MCP servers for this run.
`--screen-reader`	Optimise TUI output for screen readers.
`-d, --debug`	Open the F12 debug console with raw event logs.
`-v, --version`	Print version and exit.

Model aliases

Alias	Resolves to	Use
`auto`	`gemini-2.5-pro` (or `gemini-3-pro-preview` if previews enabled)	Default. Sensible balance.
`pro`	`gemini-2.5-pro` / `gemini-3-pro-preview`	Complex reasoning, refactor, code review.
`flash`	`gemini-2.5-flash`	Fast everyday tasks.
`flash-lite`	`gemini-2.5-flash-lite`	Cheap, simple lookups.

Headless mode for scripting

# Quick code review of a diff
git diff main | gemini -p "Review this diff for security issues. Format: bullets."

# JSON output for downstream parsing (full token stats included)
gemini -p "List the top 3 risks in this Dockerfile" --output-format json < Dockerfile

# Stream JSON events for tail-friendly log capture
gemini -p "Summarise this log" --output-format stream-json < /var/log/syslog

# Multi-directory context via --include-directories
gemini -p "Find shared validation logic" --include-directories /repo/backend,/repo/frontend

Trust gotcha on servers: Gemini refuses to run inside an untrusted directory unless you opt in. Real error from a fresh checkout:

Gemini CLI is not running in a trusted directory.
To proceed, either use --skip-trust, set GEMINI_CLI_TRUST_WORKSPACE=true,
or trust this directory in interactive mode.

Pass --skip-trust for one-shot calls, or set GEMINI_CLI_TRUST_WORKSPACE=true in the environment for a CI runner.

Real session capture (JSON output)

Authentic output from a real run, captured exactly as the CLI emitted it. Note the dual-model split (a router model triages, the main model answers) and the per-model token breakdown:

$ gemini --skip-trust -p 'In one sentence, what does this code do?' \
    --output-format json --include-directories /root/gem-demo
{
  "session_id": "5bd072ad-8d9b-4d86-89d2-1b1371a3e612",
  "response": "The code defines a function that implements the FizzBuzz algorithm...",
  "stats": {
    "models": {
      "gemini-2.5-flash-lite": {
        "api":    { "totalRequests": 1, "totalLatencyMs": 3405 },
        "tokens": { "input": 742, "candidates": 55, "thoughts": 346, "total": 1143 },
        "roles":  { "utility_router": { "totalRequests": 1, ... } }
      },
      "gemini-3-flash-preview": {
        "api":    { "totalRequests": 2, "totalLatencyMs": 4131 },
        "tokens": { "input": 15734, ... }
      }
    }
  }
}

Pipe the stream into jq to filter for the bits you need:

# Just the answer
gemini -p "summarise" --output-format json | jq -r .response

# Total tokens spent across all models
gemini -p "review repo" --output-format json | jq '[.stats.models[].tokens.total] | add'

Interactive REPL slash commands

Command	What it does
`/help`	Show in-app command list.
`/about`	Print version, build, auth status, model.
`/auth`	Switch active auth method without restarting.
`/init`	Generate a starter `GEMINI.md` from the current repo.
`/settings`	Open `settings.json` for editing.
`/theme`	Cycle through built-in themes.
`/vim`	Toggle vim-style input keybindings.
`/editor`	Open `$EDITOR` for a long prompt.
`/clear`	Wipe the visible conversation, keep the model state.
`/compress`	Summarise the conversation in place. Frees tokens without losing context.
`/copy`	Copy the last reply to the system clipboard.
`/corgi`	Toggle the corgi mascot. Yes, really.
`/chat list`	List saved chats in the current project.
`/chat save <tag>`	Snapshot the current conversation under a tag.
`/chat resume <tag>`	Reload a saved chat into the active session.
`/chat delete <tag>`	Remove a saved chat.
`/restore`	List checkpoints from the current session.
`/restore <id>`	Roll files and conversation back to a checkpoint.
`/memory show`	Print the loaded GEMINI.md and per-session notes.
`/memory add <text>`	Append a note that survives the rest of the session.
`/memory refresh`	Re-read GEMINI.md from disk after edits.
`/mcp`	Show active MCP servers and their tools.
`/mcp reload`	Restart the configured MCP servers.
`/tools`	List active tools (built-in plus MCP plus extensions).
`/skills reload`	Reload skills from disk after edits.
`/agents reload`	Reload the agent registry.
`/commands list`	List all custom slash commands.
`/commands reload`	Re-read TOML command files.
`/extensions reload`	Reload extensions without exiting.
`/directory show`	List workspace roots.
`/directory add <path>`	Dynamically include a folder in the workspace.
`/stats`	Total token spend, cache hits, latency.
`/stats model`	Per-model breakdown.
`/stats tools`	Per-tool call count.
`/ide install`	Install IDE integration (VS Code companion).
`/ide enable`	Enable IDE context for the current session.
`/privacy`	Privacy policy and data handling.
`/docs`	Open the official docs.
`/bug`	Pre-fill a GitHub issue with anonymised diagnostics.
`/quit`	Exit the TUI cleanly.

@-files and ! shell passthrough

Two patterns make the REPL ten times faster:

# Attach a file
@src/auth.ts review this for SQL injection

# Attach multiple files
@src/auth.ts @src/db.ts find shared validation logic

# Attach an entire directory recursively (respects .gitignore + .geminiignore)
@./src/api/

# Attach an image for vision-capable models
@screenshot.png explain what this UI is doing

# Run a shell command and feed output back into the chat
!git status
!docker compose ps

# Enter persistent shell mode (a single ! on its own line)
!
$ pwd
$ ls -la
$ !          # exits shell mode

Custom slash commands (TOML)

Custom commands are TOML files dropped under .gemini/commands/ (project) or ~/.gemini/commands/ (user). The filename becomes the slash command. A category folder produces namespaced commands:

~/.gemini/commands/review.toml → /review
~/.gemini/commands/security/audit.toml → /security:audit

TOML schema

# ~/.gemini/commands/review.toml
description = "Review code for security issues"
prompt = """Please review the following code for security vulnerabilities:

{{args}}

Focus on injection, auth, and crypto issues."""

Invoke from the REPL or headless mode. The {{args}} placeholder receives whatever you typed after the command name. The agent has access to whatever @-files you mention:

$ gemini -p '/review @unsafe.py'
1. Avoid `os.system`. Use the `subprocess` module instead, which provides
   better control and security.
2. Use Argument Lists. When using `subprocess.run` or `subprocess.Popen`,
   pass the command and its arguments as a list rather than a single string.
3. Disable Shell Execution. Set `shell=False` to ensure the command is
   executed directly without a shell.
...

Built-in tools reference

The agent calls these tools directly. List them at runtime with /tools and lock down individuals via excludeTools or coreTools in settings.json.

Tool	Purpose
`read_file`	Read one file into context.
`read_many_files`	Bulk read multiple files.
`write_file`	Create or overwrite a file.
`replace`	Targeted string-replace edit.
`list_directory`	List a directory.
`glob`	Glob-pattern file search.
`search_file_content`	Ripgrep-style content search.
`codebase_investigator`	Cross-file reasoning over the workspace.
`run_shell_command`	Execute a shell command (subject to approval mode).
`web_fetch`	Fetch a URL and add its rendered text to context.
`google_web_search`	Run a Google Search and return ranked results.
`save_memory`	Persist a fact across sessions (writes to GEMINI.md).

Sandbox: Docker or Podman

The --sandbox flag and "sandbox": "docker" | "podman" in settings tell the CLI to run every shell tool call inside a container. The agent can still read and write files in the workspace, but binary execution happens in an isolated environment. Useful when you do not trust an extension or want to test risky commands without leaving traces.

# One-off sandbox run
gemini --sandbox -p "build and run the test suite"

# Permanent sandbox via settings
echo '{"sandbox":"docker"}' > ~/.gemini/settings.json

Pair the sandbox with --approval-mode plan for the strictest “look, do not touch” mode.

Checkpointing and /restore

Checkpointing snapshots files before each agent edit. If a refactor goes sideways, roll back without touching git:

# Enable for one session
gemini --checkpointing

# Or persist in settings.json
{
  "checkpointing": { "enabled": true }
}

Inside the REPL:

/restore           # list checkpoints
/restore 3         # roll back to checkpoint 3 (files + chat state)

Use this when iterating on a tricky refactor: ask, review, restore, retry. Faster than git stash for small experiments.

Approval modes

Mode	Behaviour	When to use
`default`	Prompts on every tool call.	First time on a new repo.
`auto_edit`	Auto-approves edits, prompts on shell + writes outside the workspace.	Routine refactor work after you trust the agent.
`yolo`	Auto-approves everything. Same as `--yolo` or `Ctrl+Y`.	Disposable VMs and sandboxed worktrees only.
`plan`	Read-only. Refuses edits, refuses shell. Only reads and reasons.	Code reviews, audits, exploration.

Keyboard shortcuts

Action	Shortcut
Submit message	`Enter`
New line in input	`Shift+Enter`
Cancel running tool call / prompt	`Esc`
Exit (press twice)	`Ctrl+C` `Ctrl+C`
Clear screen	`Ctrl+L`
Paste text or image	`Ctrl+V`
Toggle YOLO mode	`Ctrl+Y`
Open external `$EDITOR` for prompt	`Ctrl+X`
Toggle tool-call descriptions	`Ctrl+T`
Autocomplete (commands, files, models)	`Tab`
Input history navigation	`Up` / `Down`
Open debug console	`F12` (with `--debug`)

Managing MCP servers

$ gemini mcp add --help
Usage: gemini mcp add [options] <name> <commandOrUrl> [args...]
Options:
  -s, --scope          user | project (default: project)
  -t, --transport      stdio | sse | http (default: stdio)
  -e, --env KEY=value  environment variables (repeatable)
  -H, --header         HTTP headers for sse/http (repeatable)
      --timeout        connection timeout in ms
      --trust          bypass tool-call confirmation prompts
      --description    server description
      --include-tools  comma-separated tool whitelist
      --exclude-tools  comma-separated tool blacklist

Common server adds

# Filesystem (scoped to one directory)
gemini mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /home/user/projects

# GitHub (needs GITHUB_TOKEN)
gemini mcp add github -e GITHUB_TOKEN=$GITHUB_TOKEN \
  npx -y @modelcontextprotocol/server-github

# Postgres
gemini mcp add postgres npx -y @modelcontextprotocol/server-postgres \
  "postgresql://user:pass@host:5432/db"

# Context7 with a tool whitelist
gemini mcp add context7 --include-tools search_docs \
  npx -y @upstash/context7-mcp@latest

# Remote SSE server with auth header
gemini mcp add company-tools https://mcp.company.com/sse \
  --transport sse \
  -H "Authorization: Bearer $MCP_TOKEN" \
  --timeout 20000

List the active set with gemini mcp list, toggle individuals from inside the TUI with /mcp, restart all of them with /mcp reload.

Skills

Skills are self-contained agent roles with their own prompt, tools, and metadata. The CLI ships one built-in skill (skill-creator) that helps you write new ones. Real list output:

$ gemini skills list --all
Discovered Agent Skills:

skill-creator [Enabled] [Built-in]
  Description: Guide for creating effective skills.
  Location:    /usr/local/lib/node_modules/@google/gemini-cli/bundle/builtin/skill-creator/SKILL.md

# Install from a git repo (user scope by default)
gemini skills install https://github.com/your-org/skill-release-notes

# Install from a sub-path inside a monorepo of skills
gemini skills install https://github.com/some/monorepo --path skills/security-review

# Project-scoped install
gemini skills install ./local-skill --scope workspace

# Live-link a local skill while you build it
gemini skills link ./security-review

# Toggle individuals (or all)
gemini skills enable security-review
gemini skills disable security-review
gemini skills enable --all
gemini skills disable --all

# Acknowledge security risks and skip the prompt
gemini skills install <source> --consent

Extensions

Extensions bundle commands, themes, MCP servers, hook handlers, and policies. Distribute a full toolkit to a team in one git URL.

# Install from a github repo with auto-update
gemini extensions install https://github.com/your-org/your-extension --auto-update

# Install at a specific git ref (tag, branch, commit)
gemini extensions install https://github.com/your-org/your-extension --ref v2.1.0

# Install pre-release builds
gemini extensions install https://github.com/your-org/your-extension --pre-release

# Install from a local checkout (live-linked, edits reflect immediately)
gemini extensions link ./my-extension

# List installed
gemini extensions list

# Update everything
gemini extensions update --all

# Disable temporarily
gemini extensions disable my-extension

# Validate before publishing
gemini extensions validate ./my-extension

# Scaffold a new extension from a template
gemini extensions new ./my-new-ext mcp-server

Available templates for extensions new: custom-commands, exclude-tools, hooks, mcp-server, policies, skills, themes-example.

Hooks (migrate from Claude Code)

If you already wrote hooks for Claude Code, the migrate command rewrites them into Gemini’s format:

$ gemini hooks migrate --from-claude
# Reads .claude/settings.json, writes converted hook config under .gemini/
# Prints any hooks that need manual review

The hooks system itself uses the same event taxonomy: PreToolUse, PostToolUse, Stop, UserPromptSubmit. The rewrite preserves matchers and commands, but anything that called a Claude-specific tool name needs a manual update.

Local Gemma model routing

Gemma is Google’s open-weights model family. The gemini gemma subcommand provisions a local LiteRT-LM server so the CLI can route prompts to a CPU- or GPU-hosted Gemma model instead of the cloud API. Useful for offline work, sensitive code, or saving free-tier quota:

# Download model + runtime, default port 9379
gemini gemma setup

# Setup without auto-starting
gemini gemma setup --start=false

# Re-download even if present
gemini gemma setup --force

# Lifecycle
gemini gemma start
gemini gemma status
gemini gemma logs
gemini gemma stop

With Gemma running, set the model on a per-invocation basis with -m gemma-3-12b. Combine with --approval-mode plan for read-only local exploration that costs nothing and leaks nothing.

Sessions, history, and resume

gemini --list-sessions             # what is recoverable
gemini --resume latest             # pick up the most recent
gemini --resume 3                  # pick up index 3
gemini --delete-session 5          # tidy up

Real output after a run:

$ gemini --list-sessions
Available sessions for this project (1):
  1. List 3 functions defined (Just now) [875c2ac1-4eec-42dd-a7b0-cccc97bcbd53]

Sessions live under ~/.gemini/history/<project>/. They are JSON, so you can grep, archive, or feed them into another tool.

Worktree workflow

The -w flag spins the agent up inside a fresh git worktree. Useful for parallel sessions on the same repo, or to keep the agent’s edits isolated from your in-flight branch.

# Auto-named worktree
gemini -w -p "refactor src/auth/* into smaller modules"

# Named worktree (created if missing, reused if it exists)
gemini -w fix-flaky-tests

When the agent finishes, review the diff with git diff inside the worktree, then merge or discard with the usual git worktree commands.

IDE integration

The CLI can attach to an editor for richer context (cursor position, open file, diff view). Currently best-supported in VS Code and Zed:

# Inside the REPL
/ide install     # installs the companion extension
/ide enable      # connects this session to the IDE

# Or for Zed (ACP / Agent Client Protocol)
gemini --experimental-acp
gemini --experimental-zed-integration

Output formats and JSON parsing

# Plain text. Default. Best for shell pipes and humans.
gemini -p "summarise" --output-format text < report.md

# JSON. One object on stdout. Easiest to parse with jq.
gemini -p "extract action items" --output-format json < meeting.txt | jq .

# Stream JSON. One event per line. Best for long-running prompts.
gemini -p "review the entire repo" --output-format stream-json | tee events.ndjson

Use --raw-output only when you specifically need ANSI escapes preserved. Pair it with --accept-raw-output-risk to suppress the security warning. Untrusted model output piped to a terminal can issue control sequences, so leave the warning on whenever the prompt sources are not yours.

Common errors and fixes

Error: “Please set an Auth method”

No env var, no settings.json. Either export GEMINI_API_KEY or run gemini interactively once and choose an auth method.

Error: “Gemini CLI is not running in a trusted directory”

Pass --skip-trust for one run, set GEMINI_CLI_TRUST_WORKSPACE=true in the environment for CI, or trust the directory once from the interactive UI for normal desktop work.

Error: “Quota exceeded for metric: generate_content_free_tier_requests”

Free-tier OAuth has per-minute and per-day caps. The CLI auto-retries with backoff, but if the daily cap is hit you wait until reset. Switch to API key auth (paid AI Studio key) or to a Gemma local model for the rest of the day.

Error: “Ripgrep is not available. Falling back to GrepTool”

Install ripgrep (sudo apt install -y ripgrep on Ubuntu, sudo dnf install -y ripgrep on Rocky/Fedora). Big speed-up on large repos. The CLI falls back gracefully if it is missing, but searches take longer.

Issue: WSL2 path mismatches

If gemini launches under Windows but tries to read a WSL path, configure PATH and HOME consistently. Easiest fix: install Gemini CLI inside the WSL distro using the Linux instructions, not the Windows installer.

Gemini CLI vs Claude Code vs Codex CLI vs Aider vs OpenCode

Picking between the terminal AI coding agents comes down to budget, ecosystem, and the model behaviour you prefer:

Gemini CLI: free OAuth tier (60 RPM, 1K RPD), 1M-token Gemini 2.5 Pro context, native Google Search tool, strong at long-document reasoning.
Claude Code: paid Pro/Max, deepest agent ecosystem (skills, hooks, MCP), best Sonnet/Opus models. See the Claude Code cheat sheet.
Codex CLI: pay-per-use OpenAI, sharpest at short focused refactors. See the Codex CLI cheat sheet.
Aider: git-native, multi-provider, repo-map-aware. See the Aider cheat sheet.
OpenCode: open-source TUI, server-mode native, multi-provider. See the OpenCode CLI cheat sheet, plus the OpenCode vs Claude Code vs Cursor comparison.

Frequently asked questions

Is Gemini CLI free?

Yes on the OAuth tier. Sign in with a Google account and you get ~60 requests per minute and ~1,000 requests per day at no cost. Heavier usage routes through an AI Studio API key, which is paid per token.

Where is the Gemini CLI config file?

User-level config is ~/.gemini/settings.json. Project-level overrides go in ./.gemini/settings.json. System-wide config can live at /etc/gemini-cli/settings.json. Project values override user values, which override system values. Custom commands live alongside under commands/.

How do I create a custom slash command in Gemini CLI?

Drop a TOML file at ~/.gemini/commands/<name>.toml (user) or .gemini/commands/<name>.toml (project). Set description and prompt; use {{args}} as the placeholder. A subdirectory becomes a category, so commands/security/audit.toml creates /security:audit.

Can Gemini CLI run offline?

Yes. Run gemini gemma setup to download a Gemma model and the LiteRT-LM runtime locally. Once the local server is running on port 9379, set -m gemma-3-12b (or whichever variant you downloaded) and the cloud API is no longer needed.

How do I use MCP servers with Gemini CLI?

Add a server with gemini mcp add <name> <command> [args]. Pass -t http or -t sse for remote servers. Use -e KEY=val for env vars, -H "Header: value" for HTTP headers, and --include-tools / --exclude-tools to whitelist or blacklist exposed tools. List active servers with gemini mcp list or /mcp from inside the TUI.

What is the difference between auto, pro, flash, and flash-lite?

auto is Gemini’s default routing (typically Gemini 2.5 Pro, or 3-Pro-preview if previews are enabled). pro pins the same family for complex reasoning. flash uses Gemini 2.5 Flash for fast everyday work. flash-lite uses the cheapest, fastest variant for utility tasks like routing or short summaries.

How do I roll back changes the agent made?

Launch with --checkpointing (or set "checkpointing": {"enabled": true} in settings.json). Inside the REPL, run /restore to list snapshots and /restore <id> to roll back files and conversation state to that point.

Keep this open while you work

Gemini CLI ships fast. When a new release lands, check the freshness block at the top of this page to confirm the version you are running matches what was tested. Pair this with the Gemini CLI install guide for first-time setup, the Aider cheat sheet if you alternate with that agent, and the Ollama commands cheat sheet if you also run local models alongside.