Published on

The Ultimate Guide to a Flawless gemini-cli Install (Solving Proxy & Auth Errors)

Authors

If you're a developer exploring AI-driven tools, you've likely felt the immense potential of Google's gemini-cli. You've also likely hit the wall of frustration that stops 90% of users in their tracks: a series of cryptic network and authentication errors that make getting started feel impossible.

This is not another command reference. This is a strategic, opinionated playbook designed to get you past the initial "Great Filter" of installation. We will guide you flawlessly from zero to one, preemptively solving the most common configuration issues—the proxy trap and the hidden authentication requirements—that you won't find clearly explained anywhere else.

Our goal is singular: to get gemini-cli running successfully on your machine in the shortest time possible, frustration-free. Let's begin.

The Step-by-Step Installation Guide

1.1 Prerequisites: The Foundation

Before we begin, ensure you have Node.js installed on your system, and its version is 18 or higher. You can check your current version by running node -v in your terminal.

1.2 Core Installation: Choose Your Path

gemini-cli offers two primary installation methods. Choose the one that best fits your needs.

  • Method A: Global Install (Recommended)

    • Command:
      npm install -g @google/gemini-cli
    • Why: This installs gemini-cli once on your system, allowing you to run the gemini command from any directory. It's the most convenient option for long-term use.

  • Method B: NPX Execution (For a Quick Test)

    • Command:
      npx @google/gemini-cli
    • Why: This method downloads and runs the latest version of gemini-cli without permanently installing it on your system. It's perfect for a quick trial or one-off tasks.

1.3 Exclusive Core Technique: Configuring for a Network Proxy

Many corporate or development environments require a network proxy. Attempting to authenticate through a proxy without proper configuration will almost certainly fail. This is the first major hurdle this guide will help you overcome.

  • The Root Cause: The "Login with Google" authentication process requires your browser to redirect back to a localhost address on your machine after a successful login. If you've configured a system-wide proxy but haven't excluded localhost, this critical callback request is mistakenly sent to the external proxy server, which doesn't know how to route it back to your machine. This causes the authentication to hang or fail.

  • Windows Solution (Batch Scripts): We recommend using batch scripts to easily toggle your proxy settings.

    • set_proxy.bat (Run when on the proxy network): Save the following as a .bat file. Run it as an administrator before you need to use gemini-cli.

      :: Set your proxy. Replace 7897 with your actual proxy port.
setx HTTP_PROXY "http://localhost:7897"
setx HTTPS_PROXY "http://localhost:7897"

:: CRITICAL STEP: Exclude localhost to allow the auth callback to succeed.
setx NO_PROXY "localhost,127.0.0.1"

echo Proxy environment for gemini-cli set successfully.

    • unset_proxy.bat (Run when off the proxy network): Create this file to quickly clear the proxy settings.

      setx HTTP_PROXY ""
setx HTTPS_PROXY ""
setx NO_PROXY ""

echo Proxy environment cleared.

1.4 Configuration Hierarchy: Global vs. Project-Specific

gemini-cli cleverly manages configuration at two levels, allowing for both general defaults and project-specific overrides.

  • Global (User-level) Configuration (Recommended for primary credentials): This is the ideal place for settings you use everywhere, like your primary API key. On Windows, the path is typically C:\Users\{username}\.gemini.

  • Project-level Configuration: For settings specific to one project (like a unique GOOGLE_CLOUD_PROJECT), you can create a .gemini folder inside that project's directory. These settings will override any global settings, but only when you run gemini from within that project folder.

1.5 The .gemini Directory: Using .env and settings.json

Based on the hierarchy above, we recommend the following best practice for managing your configurations.

  • Use .env for Credentials: To securely and flexibly manage your credentials, use a .env file. gemini-cli will automatically load variables from a file named .env inside the .gemini directory. Create your primary .env file in your global user directory (C:\Users\{username}\.gemini\.env).

    # Example for C:\Users\{username}\.gemini\.env

# If you use API Key auth, add your primary key here.
GEMINI_API_KEY="YOUR_PRIMARY_API_KEY_HERE"

    For a project that needs a specific Google Cloud Project, create a separate .gemini/.env file inside that project's folder with just that variable: GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID_HERE".

  • A Glimpse into settings.json: Alongside .env, the .gemini directory is also home to settings.json. This file is used for persistent, non-secret configurations, such as changing the CLI's theme or enabling advanced features like sandboxing. We will explore this file in detail in later chapters, but it's important to know it exists as part of the core configuration system.

1.6 Your First Run: The Authentication Crossroads

You are now ready to run the gemini command for the first time, which will initiate the authentication process.

  • Option 1: Login with Google (The Generous Free Quota Path)

    • Process: A browser window will open to guide you through the Google login process.

    • IMPORTANT: The Mandatory GOOGLE_CLOUD_PROJECT Configuration For many users, simply logging in is not enough. The authentication will fail unless you pre-configure a GOOGLE_CLOUD_PROJECT environment variable. This is not an optional step if you fall into any of the following categories:

      • You have a Google Workspace account (e.g., [email protected]).
      • You have an active, paid Gemini Code Assist license.
      • You received a Code Assist license through a program like the Google Developer Program.
      • You are attempting to use the service from a geographic region not supported by the free tier for individuals.
      • Your Google account holder is under the age of 18.

      If you meet any of these conditions, follow the next two sections precisely.

    Step-by-Step: Enabling the API and Finding Your Project ID

    Before you can configure the variable, you must enable the correct API in your Google Cloud project and get your Project ID.

    1. Navigate to the Gemini API Page: Open your browser and go to the official Gemini for Google Cloud API page in the marketplace:

    2. Select Your Project: At the top of the Google Cloud console, ensure you have selected the correct project from the dropdown menu. If you don't have one, you'll need to create one first.

    3. Enable the API: You will see a blue button.

      • If the API is not yet active for this project, the button will say "Enable". Click it and wait for the process to complete.
      • If the API is already active, the button may say Manage. This means you are ready for the next step.

    4. Copy Your Project ID: Once the API is enabled, locate and copy your Project ID. You can find it in the "Project info" card on your project's main dashboard, or by clicking the project selection dropdown at the top of the page. The ID is a unique string, often in the format your-project-name-123456.

    Final Step: Configure the Environment Variable

    With your Project ID copied, you must now provide it to gemini-cli. As established in Section 1.5, the best method is to create a project-specific .env file.

    1. In your project's root directory, create the following file path: .gemini/.env.

    2. Open the .env file and add the following line, replacing "your-copied-project-id" with the ID you just copied from the Google Cloud console.

      # Inside your-project/.gemini/.env
GOOGLE_CLOUD_PROJECT="your-copied-project-id"

    Now, when you run gemini from within this project folder, it will automatically load this variable, and your "Login with Google" authentication will succeed.

  • Option 2: Gemini API Key (The Automation-Ready Path)

    • Process: Obtain your API Key from Google AI Studio and place it in your global .gemini/.env file.
    • Strategic Value: This method is independent of local cached files, making it the premier choice for automated workflows, which we will cover in later chapters.

1.7 Troubleshooting Your First Run

  • Problem: gemini: command not found?

    • Cause: The installation path for gemini-cli is not in your system's PATH environment variable.
    • Solution (Windows): Run (Get-Command gemini).Source in PowerShell or where gemini in CMD to find the absolute path, then add this path to your system's environment variables.
    • Solution (macOS/Linux): Run which gemini to find the path and ensure it's in your PATH.

  • Problem: Authentication fails with TLS connection failed or other network errors?

    • Cause: This is almost certainly caused by an improperly configured network proxy.
    • Solution: Please strictly follow the guide in Section 1.3 to configure your proxy settings.

1.8 A Clean Slate: How to Uninstall

  • For Global Installs: Run npm uninstall -g @google/gemini-cli.
  • For NPX Users: You need to clear the NPX cache. Find your cache path by running npm config get cache, then delete the _npx folder within that directory.

From Setup to System

Congratulations. You've now overcome the most common hurdles that block developers from even starting with gemini-cli. A flawless installation is just the starting line, but a crucial one.

The real power of gemini-cli isn't just making it run; it's transforming it into an automated co-pilot that is deeply integrated into your personal workflow, capable of writing code, analyzing files, and even building other AI agents.

This article is Chapter 1 of my complete, unofficial guide: "Gemini CLI: From Zero to Automated Workflows". If you're ready to move beyond basic commands and learn how to build a true AI-powered development system, this guide is your definitive playbook.

Get the full guide here: [https://www.geminicliguide.com/]

Discuss on Twitter • View on GitHub