Skip to content

Gemini CLI: Google's Open-Source Agent for Your Terminal

Install Gemini CLI, sign in, and use its built-in tools and MCP servers from the command line — plus the free-tier limits and authentication options that determine which path fits you.

CurrentLast verified

Platforms

  • Gemini CLI (macOS, Windows, Linux)

What the official documentation says

  • Gemini CLI is an open-source AI agent, Apache 2.0 licensed, that brings Gemini directly into the terminal, giving lightweight access to Gemini from the command line.

    Get started with Gemini CLI

  • The free tier with a personal Google account gives 60 requests per minute and 1,000 requests per day, with access to Gemini 3 models and a 1M token context window.

    Get started with Gemini CLI

  • Built-in tools include Google Search grounding, file operations, shell commands, and web fetching; it also supports MCP (Model Context Protocol) for custom integrations.

    Get started with Gemini CLI

  • Recommended system specifications are macOS 15+, Windows 11 24H2+, or Ubuntu 20.04+, Node.js 20.0.0+, and a Bash, Zsh, or PowerShell shell; casual usage is fine with 4GB+ RAM, and heavy usage (large codebases, deep context) is recommended to have 16GB+ RAM.

    Gemini CLI installation, execution, and releases

  • The standard install is `npm install -g @google/gemini-cli`; it can also be run without installing via `npx @google/gemini-cli`, or installed with Homebrew, MacPorts, or Anaconda.

    Gemini CLI installation, execution, and releases

  • There are three release channels — stable (published weekly, the default `latest` tag), preview (published weekly, install with the `preview` tag), and nightly (published daily from the main branch, install with the `nightly` tag).

    Gemini CLI installation, execution, and releases

  • For individual Google accounts, the recommended authentication is "Sign in with Google" — run `gemini`, choose "Sign in with Google," and follow the browser flow; credentials are cached locally for future sessions.

    Gemini CLI authentication setup

  • Most individual Google accounts do not require setting a Google Cloud project to authenticate; organization accounts (company, school, or Google Workspace) do require one.

    Gemini CLI authentication setup

  • An alternative authentication method is a Gemini API key from Google AI Studio, set as the GEMINI_API_KEY environment variable — used for AI Studio users and for headless mode.

    Gemini CLI authentication setup

  • Built-in commands are prefixed with a forward slash (/), an at symbol (@), or an exclamation mark (!); slash commands provide meta-level control over the CLI, including /about (version info), /auth (change authentication method), /bug (file an issue), and /agents (manage local and remote subagents, with sub-commands list, reload, enable, disable, config).

    Gemini CLI commands reference

  • An MCP server exposes tools and resources to Gemini CLI through the Model Context Protocol, letting it discover tools, execute them with defined arguments, and access resources such as files or API payloads; Gemini CLI supports Stdio, SSE, and Streamable HTTP transport mechanisms for MCP servers.

    MCP servers with Gemini CLI

  • MCP resources can be referenced in a conversation with the same @ syntax used for local files, using the form @server://resource/path.

    MCP servers with Gemini CLI

What it is

Gemini CLI is Google's open-source, Apache 2.0-licensed terminal agent — the most direct path from a prompt in your shell to the Gemini model, with built-in Google Search grounding, file operations, shell commands, and web fetching, plus MCP support for anything those don't cover. With a personal Google account, the free tier gives 60 requests per minute and 1,000 requests per day against Gemini 3 models with a 1M token context window — no API key required to get that.

Installing: several paths

Recommended specs: macOS 15+, Windows 11 24H2+, or Ubuntu 20.04+; Node.js 20.0.0+; Bash, Zsh, or PowerShell. 4GB+ RAM covers casual use; heavy use on large codebases benefits from 16GB+.

The standard install:

npm install -g @google/gemini-cli

Then run it:

gemini

If you'd rather not install anything permanently:

npx @google/gemini-cli

Homebrew (macOS/Linux), MacPorts (macOS), and Anaconda-based installs are also documented for restricted environments.

Release channels

Three channels exist. Stable (the latest tag, and the default) is published weekly — last week's preview plus fixes. Preview is also weekly but not fully vetted; expect possible regressions. Nightly builds daily from main and should be assumed to have pending issues. Unless you specifically want to test upcoming changes, stable is what npm install -g @google/gemini-cli gives you by default.

Authenticate

Run gemini and choose an authentication method:

  • Sign in with Google (recommended for most individuals) — follow the browser flow; credentials are cached locally afterward. Most personal accounts need nothing else. Organization accounts — company, school, or Google Workspace — need a Google Cloud project set explicitly.

  • Gemini API key — get one from Google AI Studio and export it:

    export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

    This path suits existing AI Studio users and headless/scripted use where a browser sign-in flow isn't available.

These are two genuinely separate paths — which one you used determines which quota and billing applies, so it's worth being deliberate about the choice rather than whichever came up first.

Commands worth knowing early

Built-in commands use three prefixes: / for meta-level CLI control, @ for referencing files or MCP resources, and ! for shell commands. A few slash commands to know from day one:

  • /about — version info, worth including when you file an issue.
  • /auth — change your authentication method without restarting.
  • /bug — file an issue against the Gemini CLI GitHub repository directly from the session.
  • /agents — manage subagents, with list, reload, enable, disable, and config sub-commands.

Extend it with MCP servers

An MCP server exposes tools and resources to Gemini CLI over the Model Context Protocol — a bridge to databases, internal APIs, or anything else your built-in tools don't reach. Gemini CLI supports Stdio, SSE, and Streamable HTTP transports for these servers, discovering their tools automatically once configured.

Once a server is connected, its resources are addressable the same way local files are, just with their own scheme:

@server://resource/path

Three terminal workflows worth trying

Rename files by content. "Rename the photos in my photos directory based on their contents" — Gemini CLI asks permission, then renames each file based on what's actually in the image.

Read a codebase, not just its README. Point it at a public repository — "Clone the chalk repository from https://github.com/chalk/chalk, read its key source files, and explain how it works" — and it clones, reads, and summarizes from the actual source.

Automate a repetitive terminal task. Because Gemini CLI can run non-interactively in scripts, operational tasks like querying pull requests or handling a complex rebase are documented use cases beyond interactive chat.

When to reach for the CLI

If the task lives in a terminal already — reading a codebase, running shell commands, automating something repetitive with file or Git operations — Gemini CLI is the most direct tool for it. For building an application that calls Gemini programmatically instead, see Getting started with the Gemini API; for giving Gemini its own callable functions inside a larger agent, see Function calling and tools.

How to do it

  1. Install it: npm install -g @google/gemini-cli (or run it without installing via npx @google/gemini-cli).
  2. Run gemini and choose an authentication method — Sign in with Google for most personal accounts, or export GEMINI_API_KEY for AI Studio users and headless use.
  3. Complete the browser sign-in flow if you chose Sign in with Google; credentials are cached locally for future sessions.
  4. Try a prompt directly in the terminal, using built-in tools like file operations, shell commands, or Google Search grounding as needed.
  5. Connect an MCP server if you need tools or resources beyond the built-ins, then reference its resources with @server://resource/path.

On Windows

  1. Windows 11 24H2+ is the recommended OS version; PowerShell is one of the supported shells alongside Bash and Zsh.
  2. Install and run the same way as other platforms — npm install -g @google/gemini-cli, then gemini.

On mobile

N/AGemini CLI is a terminal tool for macOS, Windows, and Linux; the documentation does not describe a mobile client.

Use cases

  • Asking Gemini CLI to rename a folder of photos based on their actual visual content, rather than doing it by hand.
  • Cloning an unfamiliar open-source repository and asking Gemini CLI to explain how it works by reading the actual source, not just the README.
  • Connecting an MCP server to give Gemini CLI access to a project-specific tool or data source beyond its built-in file, shell, and search tools.

Common mistakes

  • Assuming any Google account gets 1M-context Gemini 3 access with zero setup. Organization accounts (company, school, Google Workspace) need a Google Cloud project set explicitly — only most individual accounts skip that step.
  • Installing with the preview or nightly tag by accident when stability was actually the goal — preview and nightly may contain regressions; stable (the latest tag, and the default) is what most users want.
  • Not knowing GEMINI_API_KEY is a completely separate authentication path from "Sign in with Google" — mixing them up leads to confusion about which quota or billing applies.
  • Forgetting that resources exposed by an MCP server use their own @server://resource/path syntax, distinct from the @ syntax for referencing a local file.

FAQ

Is Gemini CLI free to use?
With a personal Google account and the free tier, yes — 60 requests per minute and 1,000 requests per day, with Gemini 3 models and a 1M token context window, no API key management required.
How do I install it?
The standard method is npm install -g @google/gemini-cli, then run gemini. You can also run it without installing via npx @google/gemini-cli, or install with Homebrew, MacPorts, or Anaconda.
Which authentication method should I use?
For most individual developers, "Sign in with Google" inside the gemini command is the recommended path — no API key to manage. Use a Gemini API key instead if you're already an AI Studio user or running Gemini CLI headlessly.
Can Gemini CLI use tools beyond what's built in?
Yes — it supports MCP (Model Context Protocol) servers, which expose additional tools and resources over Stdio, SSE, or Streamable HTTP transport. Once connected, an MCP server's resources can be referenced in chat with @server://resource/path.
What's the difference between the stable, preview, and nightly channels?
Stable is published weekly and is what npm install -g @google/gemini-cli installs by default — the full promotion of the prior week's preview plus fixes. Preview is also weekly but not fully vetted. Nightly is built daily from the main branch and should be assumed to have pending issues.

Official sources

These are the pages this tutorial is checked against. Follow them if you need the vendor's exact wording.

Source status