How to Install Google Gemini CLI on Mac and Windows

Google Gemini CLI is an open-source AI agent that brings the power of Gemini directly into your terminal. With access to Gemini models and a massive 1 million token context window, it is one of the most capable free AI coding assistants available.

Why Gemini CLI?

• Free tier: 60 requests per minute and 1,000 requests per day at no cost
• 1M token context window: Read and understand entire codebases at once
• Built-in tools: Google Search grounding, file operations, shell commands, and web fetching
• Open source: Apache 2.0 license, fully transparent
• MCP support: Model Context Protocol for custom integrations

Prerequisites

Before installing Gemini CLI, ensure you have:

• Node.js version 20 or higher (required)
• A Google account (for free tier authentication)
• A terminal application (Terminal on macOS, PowerShell on Windows)

To check your Node.js version:

node --version

If you need Node.js 20+, download it from nodejs.org or use a version manager like nvm.

Installing on macOS

macOS users have three installation options.

Option 1: Homebrew (Recommended)

The easiest method for macOS users:

brew install gemini-cli

To update later:

brew upgrade gemini-cli

Option 2: npm Global Installation

For users who prefer npm:

npm install -g @google/gemini-cli

Option 3: Apple Silicon Specific

If you are on an M1, M2, M3, or M4 Mac and encounter architecture issues:

arch -arm64 npm install -g @google/gemini-cli

Quick Test (No Installation)

Want to try Gemini CLI without installing it permanently? Use npx:

npx @google/gemini-cli

This downloads and runs the latest version without a permanent installation.

Installing on Windows

Windows installation uses npm or npx.

Option 1: npm Global Installation (Recommended)

Open PowerShell and run:

npm install -g @google/gemini-cli

Option 2: Quick Test with npx

To try without permanent installation:

npx @google/gemini-cli

Option 3: WSL Installation

For users who prefer WSL (Windows Subsystem for Linux):

1. Open your WSL terminal

2. Ensure Node.js 20+ is installed:

node --version

3. Install via npm:

npm install -g @google/gemini-cli

Authentication Options

Gemini CLI offers three authentication methods.

Option 1: Login with Google (Recommended)

This is the simplest option and provides free access.

1. Start Gemini CLI:

gemini

2. Select Login with Google when prompted

3. Complete the browser authentication flow

Free tier benefits:

• 60 requests per minute
• 1,000 requests per day
• Access to Gemini models with 1M token context
• No API key management required

Option 2: Gemini API Key

For programmatic access or custom integrations:

1. Get your API key from Google AI Studio

2. Set the environment variable:

macOS/Linux:

export GEMINI_API_KEY="your-api-key-here"

Windows (PowerShell):

$env:GEMINI_API_KEY="your-api-key-here"

3. Run Gemini CLI:

gemini

Option 3: Google Cloud / Vertex AI (Enterprise)

For organizations using Google Cloud:

export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_GENAI_USE_VERTEXAI=true
gemini

Verify Installation

After authentication, verify everything works:

gemini --version

Try a simple prompt:

gemini "explain what this directory contains"

Release Channels

Gemini CLI offers multiple release channels:

# Stable (default)
npm install -g @google/gemini-cli@latest

# Preview (upcoming features)
npm install -g @google/gemini-cli@preview

# Nightly (cutting edge, may be unstable)
npm install -g @google/gemini-cli@nightly

Basic Usage

Once installed, you can use Gemini CLI for various tasks:

# Ask questions about your codebase
gemini "how does the authentication system work in this project?"

# Generate code
gemini "write a Python script to parse JSON logs"

# Summarize large files
cat large-file.py | gemini -p "summarize this code"

Leveraging the 1M Token Context Window

Gemini CLI's massive context window makes it ideal for:

• Codebase exploration: Understand entire projects at once
• Large file refactoring: Work with files that exceed other tools' limits
• Documentation generation: Analyze many files to create comprehensive docs
• Legacy code analysis: Summarize complex, undocumented systems

Troubleshooting

"command not found: gemini"

If the command is not found after npm installation:

1. Check your npm global bin directory:

npm bin -g

2. Verify the directory is in your PATH

3. Try reinstalling:

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

Node.js Version Issues

If you see errors about Node.js version:

# Check current version
node --version

# If below v20, update Node.js using nvm:
nvm install 20
nvm use 20

Rate Limit Errors

If you hit rate limits on the free tier:

• Wait a few minutes (limits reset quickly)
• Consider using an API key for higher limits
• Spread requests across time for batch operations

Next Steps

• Explore the official GitHub repository
• Read the Google Cloud documentation
• Install OpenAI Codex CLI for another powerful coding assistant
• Learn how to orchestrate multiple AI tools using Claude as an Engineering Manager