Install Gemini CLI — Free Version

Your complete, step-by-step guide to getting Google's powerful Gemini CLI up and running on your machine — for free. From prerequisites to your first AI-powered command, we've got every step covered.

Get Started on GitHub

What Is Gemini CLI?

AI in Your Terminal

Gemini CLI brings Google's Gemini AI model directly into your command-line environment. Interact with powerful AI — ask questions, generate code, analyse files — without ever leaving your terminal.

It's open-source, free to use with a Google account, and runs on macOS, Windows, and Linux.

What You Can Do

  • Chat with Gemini directly from the terminal
  • Generate and debug code on the fly
  • Analyse local files and directories
  • Run agentic tasks and multi-step workflows
  • Integrate with shell scripts and pipelines

Prerequisites Overview

Before installing Gemini CLI, make sure your system meets these requirements. The setup is lightweight — you likely already have most of these in place.

Node.js

Version 18 or higher required. Node.js powers the CLI runtime.

npm or npx

Comes bundled with Node.js. Used to run and install the CLI package.

Google Account

A free Google account is all you need to authenticate and access Gemini.

Internet Connection

Required for authentication and sending prompts to the Gemini API.

Step 1 — Check Your Node.js Version

Open your terminal and verify that Node.js version 18 or higher is installed. This is the single most important prerequisite before proceeding.

node --version
# Expected output: v18.0.0 or higher
# e.g. v20.11.0

Installing Node.js (If Needed)

1

Visit nodejs.org

Go to https://nodejs.org and download the LTS (Long Term Support) version — this is the recommended stable release for most users.

2

Run the Installer

Launch the downloaded installer and follow the on-screen prompts. Accept the default settings — they're suitable for most use cases.

3

Verify Installation

Close and reopen your terminal, then run node --version and npm --version to confirm both are installed correctly.

Quick Install

Step 2 — Run Gemini CLI with npx

The fastest way to launch Gemini CLI is using npx — no global install required. This runs the latest version of the CLI directly without permanently installing it on your machine.

npx https://github.com/google-gemini/gemini-cli

On first run, npx will download the necessary packages automatically. You'll see a brief download progress bar, after which the CLI will launch.

Step 3 — Install Globally (Optional)

If you plan to use Gemini CLI regularly, installing it globally means you can launch it from anywhere with a single command. This is ideal for developers who want seamless day-to-day access.

npm install -g @google/gemini-cli

After installation completes, verify the global install was successful:

gemini --version

npx vs. Global Install — Which Should You Choose?

Use npx (No Install)

  • No permanent files added to your system
  • Always fetches the latest version
  • Ideal for first-time users and quick trials
  • Slightly slower to start (downloads each time)

Use Global Install

  • Launches instantly from any directory
  • No internet needed to start (already cached)
  • Best for daily use and scripting
  • Requires manual updates with npm update -g
Authentication

Step 4 — Sign In with Your Google Account

When you launch Gemini CLI for the first time, it will prompt you to authenticate. This links the CLI to your free Google account and grants access to the Gemini API via the free tier.

The CLI will open a browser window automatically. Simply sign in with your existing Google account — no billing information or credit card is required for the free tier.

Authentication — Step by Step

The entire authentication process takes under 60 seconds. Once authorised, your credentials are cached locally so you won't need to sign in again on future sessions.

Step 5 — Choose Your Login Method

When Gemini CLI first launches, it will ask you to choose how you'd like to authenticate. There are two supported options:

Login with Google (Recommended)

The simplest option. Uses your Google account via OAuth. No API key needed. Perfect for individual users on the free tier. Select this option and follow the browser prompts.

Use an API Key

For advanced users or CI/CD pipelines. Generate a free Gemini API key from Google AI Studio at aistudio.google.com, then paste it when prompted in the terminal.

Generating a Free API Key (If Needed)

01

Go to Google AI Studio

Visit aistudio.google.com and sign in with your Google account.

02

Click "Get API Key"

In the left sidebar, click Get API Key, then Create API Key.

03

Copy Your Key

Copy the generated key and store it safely — you won't be able to view it again.

04

Paste into CLI

When the CLI prompts for an API key, paste your key and press Enter.

Free Tier — What's Included?

Gemini CLI's free tier is surprisingly generous. Here's what you get with a standard Google account — no payment required.

1M

Tokens per Minute

Up to 1 million tokens per minute on the free tier with Gemini 1.5 Pro.

1,500

Requests per Day

1,500 free API requests per day — more than enough for most developers.

$0

Cost to Start

Zero cost. No credit card. No billing setup required to use the free tier.

First Launch

Step 6 — Launch the CLI

Once authenticated, you're ready to start using Gemini CLI. Launch it with one of the following commands depending on how you installed it:

# If using npx:
npx https://github.com/google-gemini/gemini-cli

# If installed globally:
gemini

The CLI will load and display a welcome prompt. You're now inside an interactive session with Gemini — type any question or command to begin.

Your First Commands — Try These!

Not sure where to start? Here are some great first prompts to explore the power of Gemini CLI right away.

Ask a Question

What are the benefits of using TypeScript over JavaScript?

Generate Code

Write a Python function that reverses a linked list

Analyse a File

Summarise the contents of README.md

Explain an Error

Explain this error: TypeError: Cannot read properties of undefined

Step 7 — Explore the CLI Interface

Gemini CLI features an intuitive interactive interface. Once inside a session, you can type prompts naturally — just as you would in a chat. The CLI supports multi-line input, file references, and special slash commands.

Slash Commands

  • /help — View all available commands
  • /clear — Clear the current conversation
  • /quit or /exit — Exit the CLI
  • /model — Switch between Gemini models

Keyboard Shortcuts

  • Enter — Submit your prompt
  • Shift + Enter — New line (multi-line input)
  • Ctrl + C — Cancel current response
  • Up Arrow — Recall previous prompt

Step 8 — Pass Prompts Directly from the Shell

Gemini CLI isn't limited to interactive mode. You can pass prompts directly as command-line arguments — perfect for scripting, automation, and one-off queries without entering an interactive session.

# One-shot prompt:
gemini "Explain the difference between REST and GraphQL"

# Pipe file contents into Gemini:
cat server.js | gemini "Review this code for bugs"

# Summarise a file:
gemini -p "Summarise this document" < report.txt

Step 9 — Set Your API Key as an Environment Variable

If you're using an API key instead of Google login, it's best practice to store it as an environment variable rather than pasting it each session. This keeps your key secure and makes it available automatically.

# macOS / Linux — add to ~/.bashrc or ~/.zshrc:
export GEMINI_API_KEY="your-api-key-here"

# Windows (Command Prompt):
setx GEMINI_API_KEY "your-api-key-here"

# Windows (PowerShell):
$env:GEMINI_API_KEY = "your-api-key-here"

Step 10 — Update Gemini CLI

Keeping Gemini CLI up to date ensures you have the latest features, bug fixes, and model improvements. Here's how to update depending on your installation method.

Using npx

No action needed! npx always fetches the latest version automatically each time you run it.

npx https://github.com/google-gemini/gemini-cli

Global Install

Run the update command to pull the latest version to your global npm registry.

npm update -g @google/gemini-cli

Check Current Version

Verify which version you're currently running at any time.

gemini --version

Troubleshooting — Common Issues

Running into issues? Here are the most common problems users encounter during setup, and how to resolve them quickly.

❌ "node: command not found"

Node.js is not installed or not on your PATH. Download it from nodejs.org and reinstall, or add Node to your system PATH manually.

❌ "permission denied" on npm install -g

On macOS/Linux, prefix with sudo: sudo npm install -g @google/gemini-cli. Alternatively, configure npm to use a local directory.

❌ Authentication loop or browser doesn't open

Try running gemini auth logout then gemini auth login again. Ensure pop-ups are not blocked in your browser.

❌ "API key invalid" error

Double-check that your key was copied correctly with no extra spaces. Regenerate a new key from Google AI Studio if needed.

Troubleshooting — Network & Rate Limit Issues

Rate Limit Exceeded (429 Error)

You've hit the free tier limit. Wait a few minutes before retrying, or space out your requests. The limit resets every minute (requests per minute) and daily (requests per day).

Timeout or No Response

Check your internet connection. Long or complex prompts may take more time — try breaking them into smaller, more focused requests if the timeout persists.

Proxy or Firewall Blocking Requests

If you're on a corporate network, the Gemini API endpoint may be blocked. Configure your npm proxy settings or contact your network administrator.

Platform-Specific Notes

macOS

Use Terminal or iTerm2. Node.js is best installed via Homebrew: brew install node. Works seamlessly on both Intel and Apple Silicon (M1/M2/M3).

Windows

Use PowerShell or Windows Terminal. Download Node.js from nodejs.org. For the best experience, consider using WSL2 (Windows Subsystem for Linux).

Linux

Install Node.js via your package manager: sudo apt install nodejs npm on Ubuntu/Debian, or sudo dnf install nodejs on Fedora. Use nvm for version management.

Advanced Usage — Agentic Mode

Gemini CLI supports agentic mode — where Gemini can autonomously execute multi-step tasks on your behalf, including reading files, running shell commands, and iterating on code.

Agentic tasks are triggered naturally through your prompts. For example:

gemini "Audit my project directory for security vulnerabilities and suggest fixes"

gemini "Refactor all .js files in /src to use async/await instead of callbacks"

Gemini CLI vs. Other AI CLI Tools

Wondering how Gemini CLI stacks up against the competition? Here's a quick comparison of the most popular AI command-line tools available today.

You're All Set!

Installation Complete 🎉

Congratulations — you've successfully installed and configured Gemini CLI! You now have access to one of the most capable AI models available, right from your terminal.

📚 Documentation

Explore the full docs at github.com/google-gemini/gemini-cli for advanced configuration and features.

🤖 AI Studio

Visit aistudio.google.com to manage your API keys, view usage, and explore Gemini models.

💬 Community

Join the discussion on GitHub Issues and the Google AI Developer Forum to get help and share tips.