Gemini CLI Setup Guide: Complete Installation (2026)

Gemini CLI is Google's open-source, terminal-based AI coding agent. It brings the power of Gemini 2.5 Pro directly to your command line, allowing you to chat with AI, edit code, run commands, and manage files without leaving the terminal. It is free to use with a Google account and offers a generous daily usage allowance.

This guide walks through the complete setup process on macOS, Linux, and Windows, plus configuration tips and practical usage examples.

What Is Gemini CLI?

Gemini CLI is an agentic AI tool that runs in your terminal. Think of it as Claude Code or GitHub Copilot CLI but powered by Google's Gemini models.

Feature	Details
Model	Gemini 2.5 Pro (default)
Price	Free (with Google account)
Daily limit	1,000 requests/day (free tier)
Context	Reads your local files and project structure
Actions	Edit files, run commands, search code, create files
Platform	macOS, Linux, Windows (via WSL or native)
Open source	Yes (Apache 2.0 license)

Prerequisites

Before installing Gemini CLI, make sure you have:

Node.js 18 or later installed
A Google account (free Gmail account works)
A terminal application (Terminal on macOS, any terminal on Linux, or Windows Terminal)

Check your Node.js version:

node --version
# Should output v18.0.0 or higher

If you need to install or update Node.js:

# macOS (using Homebrew)
brew install node

# Linux (using nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install --lts

# Windows (using winget)
winget install OpenJS.NodeJS.LTS

Step 1: Install Gemini CLI

The simplest way to run Gemini CLI is with npx, which runs it without a global install:

npx https://github.com/anthropics/claude-code gemini

Wait, that is not right. Gemini CLI is a Google product. Here is the correct installation:

Method 1: Run with npx (no install needed)

npx @anthropic-ai/gemini-cli

Actually, let me correct that. Gemini CLI is installed through npm as follows:

Method 1: Run directly with npx

npx @google/gemini-cli

This downloads and runs the latest version without a permanent installation. It is the fastest way to try it out.

Method 2: Global install with npm

npm install -g @google/gemini-cli

After installation, you can run it from anywhere:

gemini

Method 3: Install from source

For contributors or those who want the latest development version:

git clone https://github.com/google-gemini/gemini-cli.git
cd gemini-cli
npm install
npm run build
npm link

Verify the installation

gemini --version

You should see the version number printed to the terminal.

Step 2: Authenticate with Google

The first time you run Gemini CLI, it will prompt you to authenticate with your Google account.

gemini

You will see a message like:

Welcome to Gemini CLI!
To get started, you need to sign in with your Google account.
Opening browser for authentication...

A browser window will open automatically.
Sign in with your Google account.
Grant the requested permissions.
The browser will confirm authentication.
Return to your terminal -- Gemini CLI is now ready.

Alternative: Authenticate with an API key

If you prefer to use a Gemini API key instead of OAuth:

Get an API key from aistudio.google.com/apikey.
Set the environment variable:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export GEMINI_API_KEY="your-api-key-here"

Restart your terminal or source the profile:

source ~/.zshrc  # or ~/.bashrc

Run Gemini CLI -- it will use the API key automatically:

gemini

Authentication methods compared

Method	Setup	Best For
Google OAuth (default)	Browser sign-in	Personal use, highest free limits
API key	Environment variable	CI/CD, automation, scripts
Service account	JSON key file	Enterprise, server environments

Step 3: Basic Configuration

Gemini CLI can be configured through a settings file and environment variables.

Configuration file

Create or edit the configuration file at ~/.gemini/settings.json:

{
  "model": "gemini-2.5-pro",
  "theme": "dark",
  "autoApprove": false,
  "sandboxMode": true,
  "maxTokens": 8192,
  "temperature": 0.7
}

Key configuration options

Setting	Default	Description
`model`	`gemini-2.5-pro`	Which Gemini model to use
`theme`	`dark`	Terminal color theme (dark/light)
`autoApprove`	`false`	Auto-approve file edits and commands
`sandboxMode`	`true`	Restrict destructive operations
`maxTokens`	`8192`	Maximum output tokens per response
`temperature`	`0.7`	Creativity level (0.0-1.0)

Project-level configuration

Create a .gemini file in your project root to set project-specific instructions:

# .gemini

## Project Context
This is a Next.js 15 application using TypeScript, Tailwind CSS, and Prisma ORM.

## Coding Standards
- Use TypeScript strict mode
- Follow the existing naming conventions in the codebase
- Write JSDoc comments for all exported functions
- Use server components by default, client components only when needed

## Testing
- Write tests using Vitest
- Place test files next to the source files with .test.ts extension

Gemini CLI reads this file automatically when you run it from the project directory.

Step 4: Essential Commands

Start an interactive session

# Navigate to your project directory
cd /path/to/your/project

# Start Gemini CLI
gemini

Run a single command

# Ask a question without entering interactive mode
gemini "Explain what this project does based on the package.json and README"

Common interactive commands

Once inside the interactive session, you can use these commands:

Command	Description
`/help`	Show all available commands
`/model`	Switch the active model
`/context`	Show current context (loaded files)
`/clear`	Clear the conversation history
`/compact`	Summarize conversation to save context
`/quit` or `Ctrl+C`	Exit Gemini CLI
`/stats`	Show token usage statistics

Step 5: Practical Usage Examples

Ask questions about your codebase

> What does the authentication middleware in src/middleware.ts do?
  Explain any potential security issues.

Gemini CLI will read the file and provide analysis without you needing to copy-paste code.

Edit files through natural language

> Add input validation to the POST /api/users endpoint in
  src/routes/users.ts. Validate that email is a valid format
  and name is between 2-50 characters. Return 400 with
  descriptive error messages for invalid input.

Gemini CLI will propose edits, show you a diff, and ask for approval before making changes.

Run and debug commands

> Run the test suite and fix any failing tests.

Gemini CLI can execute shell commands, read the output, and take action based on the results.

Generate new files

> Create a new API endpoint at src/routes/products.ts with
  full CRUD operations. Follow the same patterns used in
  src/routes/users.ts. Include input validation and error handling.

Multi-step tasks

> I want to add a dark mode feature to this React app.
  1. Add a theme context provider
  2. Create a theme toggle component
  3. Update the tailwind config for dark mode
  4. Apply dark mode classes to the layout component

Gemini CLI will work through each step, making edits across multiple files.

Step 6: Advanced Configuration

Custom model selection

You can switch models based on your needs:

# Use a specific model
gemini --model gemini-2.5-flash

# Or set it in the interactive session
> /model gemini-2.5-flash

Available models:

Model	Speed	Quality	Daily Limit
gemini-2.5-pro	Medium	Highest	1,000 req/day
gemini-2.5-flash	Fast	High	1,500 req/day
gemini-2.0-flash	Fastest	Good	1,500 req/day

Environment variables

# ~/.zshrc or ~/.bashrc

# API key authentication
export GEMINI_API_KEY="your-key"

# Custom model
export GEMINI_MODEL="gemini-2.5-pro"

# Disable telemetry
export GEMINI_CLI_TELEMETRY="off"

# Set output token limit
export GEMINI_MAX_TOKENS="16384"

Integration with other tools

Use with tmux or screen:

# Start a persistent Gemini CLI session in tmux
tmux new-session -d -s gemini "gemini"

# Attach to it later
tmux attach -t gemini

Use in scripts:

#!/bin/bash
# Automated code review script

gemini "Review the changes in the last git commit. \
Check for bugs, security issues, and style problems. \
Output a markdown report." > review.md

echo "Review saved to review.md"

Pipe content into Gemini:

# Analyze a log file
cat error.log | gemini "Analyze these error logs and identify the root cause."

# Review a diff
git diff HEAD~1 | gemini "Review this diff for potential issues."

Troubleshooting

Issue	Cause	Fix
`command not found: gemini`	Not installed globally	Run `npm install -g @google/gemini-cli`
`Node.js version too old`	Requires Node 18+	Update Node.js with nvm or brew
Authentication fails	Browser blocked	Try API key auth instead
`Rate limit exceeded`	Hit daily limit	Wait until reset (midnight PT) or use API key with billing
Slow responses	Large context	Use `/compact` to summarize conversation
File edits not working	Permission issues	Check file permissions, run from project root
`GEMINI_API_KEY not found`	Env var not set	Add to shell profile and restart terminal

Reset authentication

If you need to re-authenticate:

# Clear stored credentials
rm -rf ~/.gemini/auth
gemini  # Will prompt for login again

Update Gemini CLI

# If installed globally
npm update -g @google/gemini-cli

# If using npx, it always uses the latest version
npx @google/gemini-cli

Gemini CLI vs. Other AI CLI Tools

Feature	Gemini CLI	Claude Code	GitHub Copilot CLI	Aider
Price	Free	API costs	$10/mo	API costs
Default model	Gemini 2.5 Pro	Claude Sonnet 4.5	GPT-4o	Multiple
Daily free limit	1,000 requests	None (pay per token)	Unlimited (with sub)	None
File editing	Yes	Yes	Limited	Yes
Command execution	Yes	Yes	Yes	Limited
Open source	Yes	No	No	Yes
Best for	Free usage, Google ecosystem	Complex coding	Quick commands	Git-aware editing

Frequently Asked Questions

Is Gemini CLI really free? Yes. With Google account authentication, you get 1,000 requests per day at no cost. For higher limits, you can use a paid API key.

Does Gemini CLI send my code to Google? Yes. Your code is sent to Google's API for processing. If you work with sensitive code, review Google's AI data usage policies. For fully offline AI, use local models with Ollama instead.

Can I use Gemini CLI for commercial projects? Yes. There are no restrictions on using Gemini CLI for commercial work.

Does it work with all programming languages? Gemini CLI works with any text file. It performs best with popular languages like Python, JavaScript, TypeScript, Go, Java, and Rust.

Can I use it alongside other AI coding tools? Yes. Gemini CLI works independently of your IDE. You can use it alongside Cursor, VS Code with Copilot, or any other editor.

Wrapping Up

Gemini CLI is the most generous free AI coding tool available in the terminal. With 1,000 daily requests, Gemini 2.5 Pro as the default model, and full agentic capabilities, it handles everything from quick questions to complex multi-file refactors. The setup takes under five minutes, and Google account authentication means zero API costs.

If you are building projects that need AI-generated media, try Hypereal AI free -- 35 credits, no credit card required. It provides APIs for image, video, and avatar generation that you can easily call from the same terminal where you run Gemini CLI.