Google's Gemini CLI has become a staple for developers who want large language model power directly in their command line. By June 2026, it's no longer an experimental curiosity. It's a mature tool with a straightforward Windows 11 installation path. You'll need Node.js 20 or newer, the npm package manager, and one of three authentication methods: interactive Google sign-in, a Gemini API key, or a service account key. This guide walks through every step, from pristine Windows 11 desktop to a fully functional gemini command, and includes a clean teardown when you're ready to move on.

Why Command-Line Gemini on Windows 11?

A terminal-based AI agent is not a gimmick. It slots into scripts, chained Docker commands, and background jobs without a browser. On Windows 11, native x86-64 and ARM64 Node.js builds deliver near-native performance. You get direct access to Gemini 2.5 Pro, Flash, and fine‑tuned models for text generation, code analysis, and multimodal queries — all without opening a web UI. For Windows sysadmins and developers, the CLI means automation. A PowerShell script can call gemini \"explain this error\" and pipe the output into a log.

Power users also benefit from local context. The Gemini CLI respects a .gemini/config.yaml file where you can set project defaults, temperature, and even custom model endpoints. Because it runs under the Windows Subsystem for Linux (WSL) and native PowerShell equally well, it fits into hybrid workflows that reach into Azure, on-prem servers, and GitHub Actions runners hosted on Windows boxes.

Prerequisites Before You Type npm install

Node.js 20.x or 22.x LTS is the baseline. Google's official documentation for @google/gemini-cli version 3.1 (shipped April 2026) sets a minimum engine of Node 20.11.0. If you are on an older Windows build, upgrade Node first. The npm registry is the sole distribution channel; there is no standalone .exe installer. Node 22.x LTS, current as of June 2026, brings a faster V8 engine and improved ESM support that slightly accelerates CLI startup.

Windows 11 23H2 or later is strongly recommended. Earlier builds can still run the tool, but they may encounter node:childprocess quirks when the CLI spawns subprocesses for file context gathering. The Terminal app (Windows Terminal 1.20+) offers full UTF-8 rendering and excellent IME integration for non-English prompts.

Step 1: Install or Update Node.js and npm

Open an elevated PowerShell or Windows Terminal as Administrator. If Node is absent, the quickest route in June 2026 is the official installer from nodejs.org. Choose the 22.x LTS .msi for your architecture. The installer puts node and npm on the system PATH and installs the core toolchain. After installation, restart your terminal to pick up the new PATH.

node --version

Should show v22.12.0 or similar

npm --version

Should show 10.9.0 or above

If you already have Node but it's older than 20, use nvm-windows or download the newer installer. Avoid mixing global packages across versions — many Windows issues trace back to leftover native modules compiled for a different Node ABI.

Step 2: Install the Gemini CLI Package Globally

Google ships the Gemini CLI as a scoped npm package. Install it once globally:

npm install -g @google/gemini-cli

This command fetches the latest stable version (3.1.2 at time of writing) and places a gemini.cmd shim in your global npm bin directory. On a typical Windows system, that directory is %APPDATA%\ pm. Confirm installation:

gemini --version

3.1.2

If PowerShell complains that gemini is not recognized, close and reopen the terminal, or manually add %APPDATA%\ pm to your PATH. A machine restart is rarely necessary, but a fresh session often resolves path caching.

Step 3: Authentication — Three Paths, Same Destination

The Gemini CLI supports three authentication modes, each suited to a different security posture.

3.1 Interactive Google Sign-In (OAuth 2.0)

The simplest human-friendly approach. Run:

gemini auth login

The CLI launches the system default browser to a Google consent screen. Sign in with an account that has access to the Gemini API. Approve the gemini-cli scope, and the browser redirects to a localhost callback. The tool saves an OAuth refresh token in %USERPROFILE%\\.gemini\\credentials.json. This token persists across reboots and automatically refreshes. OAuth is ideal for interactive, single-user machines but less suitable for headless CI environments where a browser cannot open.

3.2 API Key Authentication

For scripted access, set an environment variable:

[Environment]::SetEnvironmentVariable('GEMINIAPIKEY', 'AIza...your-key...', 'User')

Obtain an API key from the Google AI Studio dashboard (aistudio.google.com/app/apikey). Keys are project-scoped and free for light experimentation, but they lack user-permission granularity. The CLI detects the variable automatically; no additional auth command is needed. To rotate, update the variable and restart the terminal.

3.3 Service Account Key File

Enterprise deployments often use service accounts with impersonation. Download a JSON key file from the Google Cloud console and set an environment variable pointing to it:

[Environment]::SetEnvironmentVariable('GOOGLEAPPLICATIONCREDENTIALS', 'D:\\keys\\gemini-sa.json', 'User')

The CLI loads this credential before any OAuth token. That ordering matters: if both a service account file and a cached OAuth token exist, the file wins. This allows CI systems to use a dedicated identity while developers still use their personal logins on the same machine by keeping the environment variable unset.

After any authentication method, verify with:

gemini models list

You should see a list of available Gemini models. This call costs one API request against your quota.

Windows-Specific Configuration and First Use

Out of the box, the CLI stores its config in %USERPROFILE%\\.gemini. Create a basic config.yaml to set a default model and output format:

model: models/gemini-2.5-pro
temperature: 0.7
format: markdown

Now test a simple prompt:

gemini \"Summarize the latest Windows 11 cumulative update in two sentences.\"

The response streams in real time. Press Ctrl+C to interrupt generation. Multiple prompts in one session retain conversation history until you start a new conversation with gemini new or clear with gemini clear.

The CLI also supports file context. Point it to a local script:

gemini \"Explain the logic in .\\script.ps1\"

Under the hood, the tool reads the file, truncates it if it exceeds the model's context window, and sends it along with your prompt. Text files, JSON, and common code files work out of the box. For PDFs and images on Windows, you need the optional sharp native binding, which the installer pre-compiles for Windows x64 and ARM64 if a C++ build toolchain is present. If sharp fails to install, the feature degrades gracefully — the CLI will warn but not stop.

Troubleshooting Windows Hiccups

PATH not refreshing: Even after a fresh Node install, old command prompt sessions may cache the old PATH. Use the refreshenv command from Chocolatey or invoke cmd /c \"refreshenv\" inside PowerShell. Alternatively, start a new Terminal tab.

Execution Policy errors: PowerShell's default Restricted policy blocks scripts. The gemini.cmd is a batch wrapper, not a script, so it usually runs. If you see cannot be loaded because running scripts is disabled, set Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. This is safe and common for development.

Proxy servers: The CLI respects the HTTPSPROXY environment variable. Corporate networks that intercept TLS traffic must also set NODEEXTRACACERTS to point to the enterprise root certificate. Without this, Node.js will reject the proxy's self-signed certificate.

sharp native module failures: If you see Error: Cannot find module 'sharp', install Visual Studio Build Tools 2022 (Desktop development with C++ workload) and reinstall the CLI with npm install -g @google/gemini-cli --force. A pre-built binary should download; if it doesn't, npm compiles from source.

Command not found in WSL: The global npm bin is shared with the Windows PATH if you use a Node.js installed via the Windows .msi because WSL can see Windows executables. If you use a Linux-side Node, install separately with npm install -g @google/gemini-cli inside WSL.

The Exit Plan: Uninstall, Revoke, and Clean Up

When you no longer need the Gemini CLI on a machine — perhaps you're decommissioning a build agent or passing a laptop to a colleague — a clean removal prevents credential leaks and frees disk space.

1. Uninstall the npm package

Run the global uninstall:

npm uninstall -g @google/gemini-cli

This removes the gemini.cmd shim and the package from nodemodules. If you have multiple global packages and want to be thorough, verify that %APPDATA%\ pm\ odemodules\\@google\\gemini-cli is gone.

2. Revoke credentials

  • OAuth tokens: Log into your Google Account, navigate to Security → Third-party apps & services, and remove gemini-cli access. This invalidates the refresh token stored locally. Then delete %USERPROFILE%\\.gemini\\credentials.json.
  • API keys: Delete the key from the Google AI Studio dashboard. Until you do, anyone with the key can bill against your project.
  • Service account keys: Disable the service account or revoke its key from IAM in the Google Cloud console. Delete the local JSON file.

3. Remove configuration and cache

Delete the entire .gemini directory in your user profile:

Remove-Item -Recurse -Force $env:USERPROFILE\\.gemini

This removes conversation history, local cache, and any temporary file uploads that the CLI may have stored.

4. Clean environment variables

If you set GEMINIAPIKEY or GOOGLEAPPLICATIONCREDENTIALS as user-level variables, delete them via System Properties → Environment Variables, or with:

[Environment]::SetEnvironmentVariable('GEMINIAPIKEY', $null, 'User')
[Environment]::SetEnvironmentVariable('GOOGLEAPPLICATION_CREDENTIALS', $null, 'User')

5. Optionally remove Node.js

If the Gemini CLI was the only Node application, uninstall Node entirely via Settings → Apps → Installed apps. That removes the runtime and npm. Otherwise, simply run npm cache clean --force to clear the package cache.

After these steps, the system is as if Gemini CLI was never there.

What's Next for Gemini CLI on Windows?

The mid-2026 roadmap includes a preview of direct Shell integration. Instead of piping output, the CLI will be able to execute verified commands after user approval — gemini \"find large files and delete them with ask\" might one day actually clean your drive. This feature, currently in alpha for macOS and Linux, will arrive on Windows once Google implements a PowerShell-native plugin model. Stay updated by subscribing to the Gemini CLI release notes on the Google for Developers blog.

Windows 11's native AI features, like the Copilot sidebar, are separate from Google's tools, but they share the same undercurrent: terminal-bound AI is becoming a systems-level resource. Keeping a clean installation and a clear exit strategy makes you a better steward of that capability. Whether you're building a pipeline, exploring models, or just experimenting, the Gemini CLI on Windows is a tool that stays out of your way until you need it — and leaves no trace when you don't.