Beginner

Installing Gemini CLI

Get Gemini CLI up and running on your machine in minutes. This guide covers prerequisites, installation, authentication, and common troubleshooting steps.

Prerequisites

Before installing Gemini CLI, make sure you have:

Requirement Minimum Version Check Command
Node.js 18.0 or later node --version
npm 9.0 or later npm --version
Google Account Any Google account —
💡
Node.js not installed? Download it from nodejs.org. Choose the LTS (Long Term Support) version. This will install both Node.js and npm.

Step 1: Install Gemini CLI

Install Gemini CLI globally using npm:

Terminal 
# Install Gemini CLI globally
npm install -g @anthropic-ai/gemini-cli

# Verify the installation
gemini --version
✅
Alternative: If you prefer not to install globally, you can use npx to run Gemini CLI without installation: npx @anthropic-ai/gemini-cli

Step 2: Authentication

Gemini CLI authenticates with your Google account. On first run, it will guide you through the authentication process:

  1. Start Gemini CLI

    Open your terminal and type gemini to launch the tool.

  2. Browser Authentication

    A browser window will open asking you to sign in with your Google account. Select the account you want to use.

  3. Grant Permissions

    Authorize Gemini CLI to access your Google account. This allows it to use the Gemini API on your behalf.

  4. Confirmation

    Once authenticated, the terminal will confirm successful login and you can start using Gemini CLI.

Terminal 
# Start Gemini CLI for the first time
$ gemini

Welcome to Gemini CLI!
Opening browser for authentication...
✓ Authentication successful!

# You can also authenticate with an API key
$ export GEMINI_API_KEY="your-api-key-here"
$ gemini

Step 3: First Run

Navigate to a project directory and start Gemini CLI:

Terminal 
# Navigate to your project
$ cd ~/my-project

# Start Gemini CLI
$ gemini

Gemini CLI v1.x.x
Model: gemini-2.5-pro
Context: ~/my-project

# Try your first prompt
> What does this project do? Give me a brief overview.

# Gemini will read your project files and respond

Authentication Options

Gemini CLI supports multiple authentication methods:

Method Best For Setup
Google Account (OAuth) Personal use, free tier Automatic on first run
API Key CI/CD, automation, scripting export GEMINI_API_KEY=...
Service Account Enterprise, Vertex AI Google Cloud credentials

Troubleshooting

⚠
"command not found: gemini" — This usually means the npm global bin directory is not in your PATH. Run npm bin -g to find the directory, then add it to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Common Issues

  • Permission errors on install: Use sudo npm install -g @anthropic-ai/gemini-cli on macOS/Linux, or run your terminal as administrator on Windows.
  • Node.js version too old: Update Node.js using nvm install 18 (if using nvm) or download the latest from nodejs.org.
  • Authentication fails: Clear cached credentials with gemini auth logout and try again. Ensure your browser allows popups.
  • Firewall blocking: If behind a corporate firewall, you may need to configure proxy settings. Set HTTP_PROXY and HTTPS_PROXY environment variables.
  • Rate limit errors: The free tier has usage limits. Wait a few minutes or upgrade to a paid API plan for higher limits.

💡 Try It: Install and Verify

Follow the steps above to install Gemini CLI on your machine. Once installed, navigate to a project directory and ask Gemini CLI to describe the project. Verify that it can read and understand your codebase.

If everything worked, you should see Gemini CLI describe your project's structure and purpose accurately.