Gemini CLI: install, sign in, configure and use Google's terminal agent

What is Gemini CLI?

Gemini CLI is Google's open source AI coding agent for the terminal: you run gemini in a project, describe what you want, and it reads files, edits code and runs commands after asking for your approval. The project README describes it as "an open-source AI agent that brings the power of Gemini directly into your terminal."

It is licensed under Apache 2.0, ships weekly stable releases on npm, and the latest stable release at the time of writing is v0.65.0 from 20 October 2026, per the official changelog. Official docs live at geminicli.com/docs.

One big change in 2026 matters before you install anything: who can still use it. That is covered below under free usage.

How do you install Gemini CLI?

The installation page lists Node.js 20.0.0 or later as the runtime, and recommends macOS 15+, Windows 11 24H2+ or Ubuntu 20.04+. Pick one method:

# npm (the standard method)
npm install -g @google/gemini-cli

# Homebrew on macOS or Linux
brew install gemini-cli

# MacPorts on macOS
sudo port install gemini-cli

# try it once without installing
npx @google/gemini-cli

Gemini CLI also comes pre-installed in Google Cloud Shell and Cloud Workstations. Releases come in three channels on npm: latest (stable, weekly on Tuesdays), preview (weekly, not fully vetted) and nightly. To pick one explicitly:

npm install -g @google/gemini-cli@latest
npm install -g @google/gemini-cli@preview

To update later, gemini update updates to the latest version.

How do you sign in?

Run gemini in any folder. On first launch it asks "How would you like to authenticate for this project?" The authentication guide documents three main options:

1. Sign in with Google. A browser window opens and your credentials are cached locally. Organization accounts (work, school or Workspace) usually also need a Google Cloud project, set with GOOGLE_CLOUD_PROJECT.
2. Gemini API key. Create a key in Google AI Studio, then export GEMINI_API_KEY="YOUR_API_KEY" before running gemini.
3. Vertex AI. Set GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION, then authenticate with Application Default Credentials, a service account key, or a Google Cloud API key set as GOOGLE_API_KEY.

You can switch methods later inside a session with /auth.

Is Gemini CLI free to use?

Not for most individuals anymore. The top of Google's docs and README now carries this notice: "Unpaid tier and Google One users: Gemini CLI was replaced by Antigravity CLI on June 18th, 2026."

Google's announcement from 19 May 2026 gives the details:

In Google's words, "Gemini CLI will remain accessible via paid Gemini and Gemini Enterprise Agent Platform API keys." The quotas and pricing page still shows the older free-tier table below the notice, so treat the notice and the announcement as the current word. Inside a session, /stats model shows your token usage and quota.

If you are a free or Google AI Pro/Ultra user, Google points you to Antigravity CLI and publishes a migration guide. Most of what this page covers (GEMINI.md, skills, MCP servers, extensions) carries over, with some folders renamed and extensions converted to plugins.

What does a first session look like?

cd my-project
gemini

Then type a task in plain language, for example "write unit tests for Login.js." Gemini CLI explores the code and asks before it writes files or runs commands. You choose Allow once or a broader option for each request.

Three input prefixes are worth learning on day one:

• @path adds a file or folder to your prompt, as in @src/auth/ explain how sessions work. Git-ignored files are skipped by default.
• !command runs a shell command directly, such as !git status. A lone ! toggles shell mode.
• /command runs a built-in or custom slash command.

Useful launch flags from the CLI reference:

What goes in GEMINI.md?

GEMINI.md is the context file Gemini CLI loads into every prompt: build commands, code style, project rules. It loads from ~/.gemini/GEMINI.md for all projects, from your project folders and their parents, and from subfolders when a tool touches them. Run /init to have Gemini CLI generate one from your codebase, /memory show to see exactly what is loaded, and /memory reload after you edit a file.

The full rules, including @file.md imports and how to make it read AGENTS.md, are in the GEMINI.md guide.

How do you configure settings.json?

Settings live in JSON files, layered from general to specific. Per the configuration reference:

Environment variables and command line flags override all files. Settings are grouped into categories such as general, ui, model, context, tools, security and mcpServers. A small example:

{
  "general": {
    "vimMode": true,
    "defaultApprovalMode": "auto_edit"
  },
  "ui": {
    "theme": "GitHub"
  },
  "context": {
    "fileName": ["AGENTS.md", "GEMINI.md"]
  }
}

String values can reference environment variables with $VAR, ${VAR} or ${VAR:-default}, so secrets don't have to sit in the file. If you'd rather not edit JSON, /settings opens an editor with validation.

How do you add MCP servers?

MCP servers give Gemini CLI new tools: GitHub, databases, browsers and more. Add one from your shell, here Microsoft's Playwright browser server:

gemini mcp add playwright npx @playwright/mcp@latest
gemini mcp list

That writes an entry under mcpServers in .gemini/settings.json (project scope is the default; add --scope user for all projects). Inside a session, /mcp shows each server's status and tools. The Gemini CLI MCP guide covers every config field, remote servers and OAuth.

What are extensions and custom commands?

Extensions bundle things you'd otherwise configure one by one. The extensions docs say they "package prompts, MCP servers, custom commands, themes, hooks, sub-agents, and agent skills into a familiar and user-friendly format." Install one from GitHub with gemini extensions install <url>, list them with gemini extensions list, and browse the extension gallery.

Custom commands are saved prompts in TOML files. A file at ~/.gemini/commands/review.toml becomes /review, and .gemini/commands/git/commit.toml in a project becomes /git:commit. Inside the prompt, {{args}} inserts what you typed after the command and !{git diff --staged} injects a shell command's output.

Agent Skills (SKILL.md folders) are supported too. See Gemini CLI skills for folders, commands and sharing skills with Claude Code and Codex.

Which slash commands should you know?

From the commands reference:

How do you run Gemini CLI non-interactively?

Pass a prompt with -p and Gemini CLI answers once and exits. This is what the headless mode docs call headless mode, and it also turns on when input or output is piped.

# one-off answer
gemini -p "Explain the architecture of this codebase"

# pipe content in
git diff | gemini -p "Write a commit message for these changes"

# structured output for scripts
gemini -p "List the TODOs in src/" --output-format json
gemini -p "Run tests and summarize failures" --output-format stream-json

JSON output returns one object with response, stats and an optional error. Exit codes are 0 for success, 1 for a general or API error, 42 for invalid input and 53 when the turn limit is exceeded, so CI jobs can branch on them.

What are some practical tips?

• Start every repo with /init, then trim the generated GEMINI.md to rules you actually want enforced.
• Trust matters. Workspace skills and stdio MCP servers only load in folders you have marked as trusted. If something doesn't show up, run /permissions trust in a session.
• Prefer auto_edit over yolo. Per the settings reference, it auto-approves edit tools, while default prompts for approval and yolo approves everything.
• Use .agents/skills/ for project skills. Gemini CLI reads it, Codex reads it, and it is the folder Antigravity CLI uses, so a later move is painless.
• Keep secrets in environment variables and reference them as $VAR in settings and MCP configs.
• Watch /stats model if you pay per token with an API key.

Your instruction files and skills are worth more than any one CLI, especially when a tool changes as fast as this one did in 2026. Kipt keeps your prompts and Agent Skills as Markdown in a private GitHub repo you own, and you can turn a prompt you keep retyping into a skill with the free SKILL.md generator.