How to Set Up Gemini CLI in 2026: The Definitive Installation Guide

Introduction

Gemini CLI puts the full power of Google's Gemini models directly inside your terminal. No browser tab, no copy-pasting code snippets, no context switching — just a conversational AI assistant that can read your files, run shell commands, call external APIs, and iterate on code alongside you in the environment where you already work.

Getting there requires a handful of one-time setup steps: a compatible Node.js runtime, the @google/gemini-cli package, a Google AI API key, and a small amount of shell configuration. None of these steps is complicated, but the order matters, the platform-specific differences are real, and the error messages you encounter when something goes wrong are rarely self-explanatory.

This guide covers the full installation path for macOS, Windows, and Linux in 2026. It walks through every command you need to run, every environment variable you need to set, and the five most common errors people hit during setup — along with their fixes. By the end you will have a working gemini binary, a verified API key, and the confidence to know that when something breaks, you can diagnose it.

---

TL;DR

• Gemini CLI requires Node.js 18 or higher and npm.
• Install globally with npm install -g @google/gemini-cli.
• Get a free API key from Google AI Studio and export it as GEMINI_API_KEY.
• Persist the variable in your shell profile (~/.zshrc, ~/.bashrc, or Windows environment settings).
• Verify the install with gemini --version, then run your first command.
• The five most common setup errors are covered in the Troubleshooting section below.

---

Prerequisites

Before installing Gemini CLI, make sure your system has the following in place.

Node.js 18 or Higher

Gemini CLI is distributed as an npm package and requires Node.js 18 (LTS) as a minimum. Node 20 and Node 22 are both supported and recommended for new installations. Node 16 and earlier will fail with a syntax error at startup.

Check your current version:

node --version
# v22.11.0

If Node is not installed, or if your version is below 18, install or upgrade it using the method appropriate for your platform (covered in each platform section below).

npm

npm ships bundled with Node.js. Any Node 18+ installation includes a compatible npm version. Confirm it is present:

npm --version
# 10.9.2

Internet Access

The installer fetches the package and its dependencies from the npm registry. You will also need to reach generativelanguage.googleapis.com at runtime for every Gemini API call. Corporate proxies and VPNs occasionally interfere with both — keep that in mind if you are setting up on a company machine.

---

macOS Installation

macOS is the most common development platform for Gemini CLI users. There are two recommended approaches: installing Node.js via Homebrew (the simpler path for most developers) and installing via npm directly if you already have a Node.js version manager in place.

Option 1: Homebrew + npm

If you do not already have Node.js installed, Homebrew is the fastest way to get a well-maintained version:

# Install Homebrew if you do not have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js (installs the current LTS release, currently Node 22)
brew install node

Confirm the versions:

node --version
# v22.11.0

npm --version
# 10.9.2

Then install Gemini CLI globally:

npm install -g @google/gemini-cli

Verify the binary is on your PATH:

gemini --version
# gemini-cli/0.1.x linux-arm64 node-v22.11.0

Option 2: Node Version Manager (nvm)

If you work across multiple Node.js projects with different runtime requirements, nvm is a better long-term choice than a system-wide Homebrew installation. It lets you switch Node versions per project without touching your global environment.

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Reload your shell profile
source ~/.zshrc   # or source ~/.bashrc

# Install the latest LTS release
nvm install --lts
nvm use --lts

# Confirm
node --version
# v22.11.0

Then install Gemini CLI:

npm install -g @google/gemini-cli

Apple Silicon (M1/M2/M3/M4) Notes

Gemini CLI ships prebuilt native binaries for arm64 (Apple Silicon) via the @google/gemini-cli-darwin-arm64 optional dependency. On a native ARM terminal the install is transparent — npm selects the correct binary automatically.

However, if you are running an x86_64 (Rosetta) shell session, npm will install the Intel binary instead. Running an ARM binary under Rosetta is not a problem, but running an ARM binary in a non-Rosetta shell that expects x86_64 will fail with an Exec format error. Confirm your terminal architecture before installing:

uname -m
# arm64   ← Apple Silicon native
# x86_64  ← Rosetta or Intel

If you are using iTerm2 or Terminal.app with "Open using Rosetta" enabled for legacy compatibility, disable that setting before running the npm install to ensure you get the correct binary for your hardware.

Additionally, if you installed Node via Homebrew on Apple Silicon, the Homebrew prefix is /opt/homebrew rather than /usr/local. Make sure your PATH includes /opt/homebrew/bin:

# Add to ~/.zshrc if not already present
export PATH="/opt/homebrew/bin:$PATH"

---

Windows Installation

Option 1: npm via Node.js Installer

The official Node.js installer for Windows handles everything — runtime, npm, and PATH configuration — in a single GUI wizard.

1. Visit nodejs.org and download the LTS installer (.msi).
2. Run the installer. Accept the defaults. On the "Tools for Native Modules" screen, check "Automatically install the necessary tools" if you plan to use any native npm packages.
3. Open a new Command Prompt or PowerShell session (important — the old session will not see the updated PATH).
4. Confirm the installation:

node --version
# v22.11.0

npm --version
# 10.9.2

5. Install Gemini CLI:

npm install -g @google/gemini-cli

6. Verify:

gemini --version
# gemini-cli/0.1.x win32-x64 node-v22.11.0

Option 2: Windows Subsystem for Linux (WSL)

If you primarily develop in a Linux-like environment on Windows, WSL 2 gives you a full Ubuntu (or Debian, or Fedora) environment inside Windows. This is the recommended approach for developers who use shell scripting, Docker, or Unix tools extensively.

Install WSL with Ubuntu:

# Run as Administrator in PowerShell
wsl --install -d Ubuntu-24.04

Restart your machine when prompted, then open Ubuntu from the Start menu. Once inside the WSL terminal, follow the Linux installation steps below.

Tip: Store your projects under the WSL filesystem (~/projects/) rather than under the Windows filesystem (/mnt/c/Users/...). File I/O on Windows-mounted paths under WSL is significantly slower, which affects Gemini CLI operations that read many files.

---

Linux Installation

npm (All Distributions)

The most distribution-agnostic approach is to install Node.js via the official NodeSource repository or via nvm, then install Gemini CLI through npm. This gives you control over the Node.js version regardless of what your distribution's package manager offers.

Using nvm (recommended):

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Reload profile
source ~/.bashrc   # or source ~/.zshrc

# Install LTS Node
nvm install --lts
nvm use --lts

# Install Gemini CLI
npm install -g @google/gemini-cli

Using NodeSource apt repository (Ubuntu/Debian):

# Add the NodeSource 22.x repository
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# Install Node.js
sudo apt-get install -y nodejs

# Verify
node --version
# v22.11.0

# Install Gemini CLI
npm install -g @google/gemini-cli

Using NodeSource dnf/yum repository (Fedora/RHEL/CentOS):

# Add the NodeSource repository
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -

# Install Node.js
sudo dnf install -y nodejs

# Verify
node --version

# Install Gemini CLI
npm install -g @google/gemini-cli

Distribution-Specific Notes

| Distribution | Package Manager | Notes | |---|---|---| | Ubuntu 22.04 / 24.04 | apt | System nodejs is too old (v12/v18). Use NodeSource or nvm. | | Debian 12 (Bookworm) | apt | Node 18 is in Debian stable. Upgrade to 22 via NodeSource for best results. | | Fedora 39+ | dnf | System Node is often current. Check version before installing NodeSource. | | Arch Linux | pacman | sudo pacman -S nodejs npm installs a very recent Node. Usually fine. | | Alpine Linux | apk | apk add nodejs npm. Used in Docker images — verify the Node version in your base image. |

Global npm Permissions on Linux

By default, npm install -g on Linux requires root because global packages are written to /usr/lib/node_modules. Running sudo npm install -g is a common but problematic pattern — it can cause permission issues for subsequent non-root npm operations.

The better approach is to configure npm to use a directory in your home folder:

# Create a directory for global packages
mkdir -p ~/.npm-global

# Tell npm to use it
npm config set prefix '~/.npm-global'

# Add it to your PATH in ~/.bashrc or ~/.zshrc
export PATH="$HOME/.npm-global/bin:$PATH"

# Reload your profile
source ~/.bashrc

# Now install without sudo
npm install -g @google/gemini-cli

---

API Key Configuration

Gemini CLI authenticates every request to the Gemini API using a key associated with your Google account. Without a valid key, every gemini command will fail with a 403 PERMISSION_DENIED error.

Step 1: Get Your Google AI API Key

1. Open Google AI Studio in your browser. You will need to sign in with a Google account.
2. Click "Create API key".
3. Select an existing Google Cloud project, or click "Create API key in new project" to have Google create one for you automatically.
4. Copy the generated key. It begins with AIza and is approximately 39 characters long.

Important: The key is shown only once in the creation dialog. Copy it immediately and store it somewhere safe (a password manager, not a plaintext file). If you lose it, you can generate a new key from the same page — the old key continues working until you revoke it.

The free tier (as of April 2026) includes generous request quotas under the Gemini 1.5 Flash model, which is sufficient for daily development use. Gemini 1.5 Pro and Gemini 2.0 models have lower free-tier limits and are billed per token above the threshold.

Step 2: Set the Environment Variable

Gemini CLI reads your API key from the GEMINI_API_KEY environment variable. Set it for your current shell session to verify things work:

# macOS / Linux
export GEMINI_API_KEY="AIzaYOUR_KEY_HERE"

# Windows PowerShell
$env:GEMINI_API_KEY = "AIzaYOUR_KEY_HERE"

# Windows Command Prompt
set GEMINI_API_KEY=AIzaYOUR_KEY_HERE

Test the key immediately by running a simple command:

gemini -p "Reply with exactly: API key works"
# API key works

If you see a response, the key is valid and the connection to the Gemini API is working. If you see a 403 or 401 error, double-check that you copied the full key and that there are no trailing spaces.

Step 3: Persist the API Key

An environment variable set with export only survives for the current terminal session. To make it permanent, add it to your shell profile.

---

Shell Configuration

zsh (macOS Default, Many Linux Systems)

Add the following line to ~/.zshrc:

# ~/.zshrc

# Gemini CLI API key
export GEMINI_API_KEY="AIzaYOUR_KEY_HERE"

Then reload the profile:

source ~/.zshrc

Confirm the variable is now set in a new terminal session:

echo $GEMINI_API_KEY
# AIzaYOUR_KEY_HERE

bash (Linux Default, macOS Alternative)

Add the export to ~/.bashrc for interactive shells, and to ~/.bash_profile if you want it available in login shells as well:

# ~/.bashrc

# Gemini CLI API key
export GEMINI_API_KEY="AIzaYOUR_KEY_HERE"

Reload:

source ~/.bashrc

Note: On macOS, Terminal.app opens login shells (reads ~/.bash_profile), while most Linux terminal emulators open interactive non-login shells (reads ~/.bashrc). If your variable disappears after restarting the terminal on macOS with bash, add it to ~/.bash_profile instead or source ~/.bashrc from ~/.bash_profile:

# ~/.bash_profile
[[ -f ~/.bashrc ]] && source ~/.bashrc

Windows (Persistent Environment Variables)

On Windows, the equivalent of shell profile persistence is a system or user environment variable. Open Settings, search for "environment variables", and add GEMINI_API_KEY as a user variable with your key as the value. New PowerShell and Command Prompt sessions will pick it up automatically.

Alternatively, add it to your PowerShell profile at $PROFILE:

# Open your PowerShell profile
notepad $PROFILE

# Add this line
$env:GEMINI_API_KEY = "AIzaYOUR_KEY_HERE"

PATH Configuration

On most systems, npm install -g adds the global bin directory to PATH automatically through the Node.js installer or nvm setup. If gemini is not found after installation, you need to add the npm global bin directory to your PATH manually.

Find the global bin directory:

npm bin -g
# /opt/homebrew/bin           ← macOS Homebrew
# /home/yourname/.nvm/versions/node/v22.11.0/bin  ← nvm
# /home/yourname/.npm-global/bin   ← custom prefix

Add that path to your shell profile:

# Example for nvm on Linux — add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.nvm/versions/node/v22.11.0/bin:$PATH"

After reloading the profile, which gemini should return the full path to the binary.

---

Verifying the Installation

With Node.js, Gemini CLI, and the API key all configured, run through these checks to confirm everything is working end to end.

Check the Version

gemini --version
# gemini-cli/0.1.x darwin-arm64 node-v22.11.0

The output confirms the Gemini CLI version, your platform, and the Node.js version in use.

Run Your First Command

The -p flag (short for --prompt) sends a single prompt without entering the interactive session:

gemini -p "What is the current year?"
# The current year is 2026.

Open the Interactive Session

gemini

You should see the Gemini CLI welcome banner and a > prompt. Type a question:

> Explain what a Merkle tree is in two sentences.

Gemini will stream the response directly to your terminal. Press Ctrl+C or type /exit to leave the session.

Check Available Commands

Inside the interactive session, type /help to see all available slash commands:

> /help

Key commands to know immediately:

| Command | What it does | |---|---| | /mcp | Show connected MCP server status | | /stats | Display token usage for the current session | | /clear | Clear conversation history | | /exit | Exit Gemini CLI | | @filename | Include a file's contents in your next prompt |

---

Troubleshooting Common Issues

Error 1: command not found: gemini

Symptom: After running npm install -g @google/gemini-cli, the shell reports command not found: gemini or zsh: command not found: gemini.

Root cause: The npm global bin directory is not on your PATH.

Fix:

# Find where npm installed the binary
npm bin -g

# Add that directory to PATH in your shell profile
# Example output: /opt/homebrew/bin
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify
which gemini
# /opt/homebrew/bin/gemini

If you are using nvm, ensure you have called nvm use or nvm use --lts before installing — nvm uses a different bin directory for each Node version, and switching versions can make a previously installed global binary invisible.

Error 2: 403 PERMISSION_DENIED on Every Request

Symptom: Every gemini command fails with an error like:

Error: 403 PERMISSION_DENIED
API key not valid. Please pass a valid API key.

Root cause: Either GEMINI_API_KEY is not set, is set to the wrong value, or the key has been revoked.

Fix:

# Check if the variable is set
echo $GEMINI_API_KEY
# (empty output means it is not set)

# Set it for the current session
export GEMINI_API_KEY="AIzaYOUR_KEY_HERE"

# Confirm it matches your key in Google AI Studio exactly
# Keys start with AIza and are 39 characters
echo ${#GEMINI_API_KEY}
# 39

If the key is set but still rejected, regenerate a new key in Google AI Studio and update the variable.

Error 3: EACCES: permission denied During Global Install

Symptom: npm install -g @google/gemini-cli fails with:

npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/@google
npm error errno -13

Root cause: Your global npm prefix (/usr/local) is owned by root, but you are running npm as a regular user.

Fix (Linux): Configure a user-owned global prefix as described in the Linux section:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @google/gemini-cli

Fix (macOS with Homebrew): Homebrew manages its own prefix at /opt/homebrew (Apple Silicon) or /usr/local (Intel) and sets permissions correctly. If you are hitting this error on macOS, you likely installed Node.js without Homebrew and the permissions on /usr/local/lib are incorrect. Either reinstall Node via Homebrew, or use the user-prefix approach above.

Error 4: node: bad option: --require or Syntax Errors at Startup

Symptom: Running gemini produces an immediate Node.js error:

/usr/local/lib/node_modules/@google/gemini-cli/dist/index.js:1
SyntaxError: Unexpected token '?'

or

node: bad option: --require

Root cause: Your Node.js version is below 18. The ??= nullish assignment operator and other modern syntax used by Gemini CLI are not available in older runtimes.

Fix:

# Check your node version
node --version
# v16.20.0  ← too old

# Upgrade using nvm
nvm install --lts
nvm use --lts
node --version
# v22.11.0  ← good

# Reinstall Gemini CLI against the new Node version
npm install -g @google/gemini-cli

Error 5: CERT_HAS_EXPIRED or UNABLE_TO_VERIFY_LEAF_SIGNATURE

Symptom: Gemini CLI fails with a TLS/SSL certificate error when making API calls:

Error: CERT_HAS_EXPIRED
  at TLSSocket.onConnectEnd (_tls_wrap.js:...)

Root cause: This almost always occurs in corporate environments where a TLS-intercepting proxy (often called a "man-in-the-middle" proxy or "SSL inspection" proxy) sits between your machine and the internet. The proxy presents its own certificate, which Node.js does not trust by default.

Fix: Ask your IT department for the corporate root CA certificate in PEM format, then point Node.js at it:

# Set the path to your corporate CA bundle
export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca-bundle.crt"

# Add to your shell profile to make it permanent
echo 'export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca-bundle.crt"' >> ~/.zshrc

Do not use NODE_TLS_REJECT_UNAUTHORIZED=0 as a fix. It disables all certificate validation, which leaves every HTTPS connection your terminal makes open to interception without warning.

---

FAQ

Q: Is the Gemini API key the same as a Google Cloud service account key?

No. The key you get from Google AI Studio is a simple API key tied to your personal Google account and billed to a Google Cloud project. A service account key is a JSON file used by server-side applications to authenticate as a non-human identity. For Gemini CLI on a developer workstation, the Google AI Studio API key is the correct credential. Service account keys are more appropriate for CI/CD pipelines and automated scripts that run in production environments without a human in the loop.

Q: How do I switch between Gemini model versions?

Gemini CLI defaults to Gemini 1.5 Flash for interactive sessions. To use a specific model, pass the --model flag:

gemini --model gemini-2.0-flash-exp -p "Summarise this file" @README.md

You can also set a default model in your project or global settings file at ~/.gemini/settings.json:

{
  "model": "gemini-2.0-flash-exp"
}

Q: Can I install Gemini CLI without a global npm install?

Yes. Use npx to run Gemini CLI on demand without installing it globally:

npx @google/gemini-cli -p "Hello world"

npx downloads and caches the package the first time, then reuses the cache. The drawback is a slight startup delay on the first run, and you lose the short gemini alias for the interactive session. For day-to-day use, the global install is more convenient.

Q: Does Gemini CLI work offline?

No. Every prompt requires a live connection to generativelanguage.googleapis.com. There is no local model bundled with the CLI. File reading, shell command execution, and MCP server communication all happen locally, but the actual inference runs in Google's cloud. If your internet connection drops mid-session, in-flight requests will time out and the session will need to be restarted.

Q: How do I update Gemini CLI to a new version?

Updating follows the same command as the original install:

npm update -g @google/gemini-cli

Or, to force the absolute latest version regardless of semver range:

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

Check the installed version afterwards with gemini --version to confirm the update took effect. Breaking changes between major versions are documented in the changelog on GitHub.

---

Conclusion

Setting up Gemini CLI is a one-time investment of around ten minutes that pays dividends every working day. The process is the same wherever you develop: install a current Node.js runtime, install the npm package, configure your API key as a persistent environment variable, and run gemini --version to confirm the binary is on your PATH.

The platform differences are real but narrow. Apple Silicon users need to be mindful of Rosetta and the /opt/homebrew prefix. Linux users benefit from configuring a user-owned npm prefix to avoid permission headaches. Windows users get the smoothest experience via the official Node.js installer, or via WSL 2 if their development workflow is already Unix-oriented.

Once the setup is complete, the next productive step is exploring what Gemini CLI can do in your specific codebase. Start with simple file analysis — pass a source file with @filename and ask a question about it. From there, move to multi-file workflows, then experiment with MCP servers to connect Gemini CLI to your databases, version control, and internal APIs. The MCP server guide and the power tips article are good next reads once you have the basics working.

The hardest part is already behind you. The binary is installed, the key is configured, and the terminal is ready.