Fixing Gemini CLI Login Authorization Failures: Installation and Troubleshooting Guide

Due to network restrictions, directly accessing Google services (including the new Gemini CLI) can be problematic. Even with a VPN, login authorization failures or connection timeouts are common.

This guide details my experience resolving Gemini CLI login authorization failures, providing a simplified introduction, installation instructions, and usage tips to get you started quickly.

I. Gemini CLI Overview

What is Gemini CLI?

The Gemini CLI is Google's official command-line interface, similar to Claude Code. It allows users to interact with the Gemini AI model directly from the terminal, supporting tasks like asking questions, assisting with programming, and editing files.

Advantages

1. Generous Free Tier: For casual users, the free quota is sufficient for daily development and learning.
2. Strong Contextual Understanding: Supports long conversations, maintaining context for coherent interactions.
3. Cross-Platform Compatibility: Seamlessly supports Windows, macOS, and Linux, offering great flexibility.
4. Robust Community & Debugging Support: Despite limited official documentation, the built-in debug mode (e.g., -d option) helps in pinpointing and resolving issues.

How to Install Gemini CLI

1. Prerequisites

• Node.js Environment: Ensure you have Node.js installed (recommended v20.x or later).
• Network Access: You need access to Google services, typically requiring a proxy or VPN.

2. Installation Steps

• Open your terminal (CMD or PowerShell for Windows, Terminal for macOS/Linux).
• Execute the following command to install Gemini CLI globally:

  npm install -g @google/gemini-cli

• Verify the installation:

  gemini --version

  A version number indicates successful installation.

Basic Usage

• Start Interactive Mode:

  gemini

  This launches an interactive interface where you can input questions or commands.

• Common Options:

  • -d or --debug: Enables debug mode, outputting detailed connection and error information. Invaluable for troubleshooting.
  • --verbose: Outputs more log information.

• Exit: Press Esc or type exit in interactive mode to quit.

II. Resolving Login Authorization Failures: A Detailed Account

The Problem

When first using the gemini command, I encountered the following issues:

1. After running gemini, the terminal displayed Waiting for auth... (Press ESC to cancel) and automatically opened a Google login page in my browser.
2. After successfully logging in and granting authorization in the browser, the page redirected to localhost:11101, but the gemini process in the terminal exited without any error messages.

To investigate, I used the debug mode gemini -d and identified the specific error:

The error log showed AggregateError [ETIMEDOUT], indicating a timeout when connecting to the Google server (IP address 216.239.32.223).

Problem Analysis

Based on the error message and my network environment, the root cause was clear:

1. Network Access Restrictions: I am located in a region where Google services are not directly accessible.
2. Missing Proxy Settings: Although I had a system proxy enabled, Gemini CLI doesn't automatically read system proxy settings. It tried to connect directly to Google servers, leading to timeouts.
3. Unstable VPN Connection: In some cases, even with a proxy set, an unstable VPN connection could cause timeouts during the authentication process.

Solution Steps

Step 1: Ensure VPN Stability

• Verify that your proxy or VPN tool is functioning correctly. Switch to a server node with a stable, high-quality connection.
• If your proxy tool uses a whitelist or rule-based mode, ensure that relevant Google domains (e.g., *.google.com) or IP address ranges are within the proxy's scope.

Step 2: Set Proxy for the Terminal This is the most crucial step. You need to set the https_proxy environment variable for the current terminal session, directing Gemini CLI's network requests to your local proxy port.

• Windows (CMD):

  set https_proxy=http://127.0.0.1:10808

• Windows (PowerShell):

  $env:https_proxy="http://127.0.0.1:10808"

• macOS / Linux (Bash/Zsh):

  export https_proxy=http://127.0.0.1:10808

Note: Replace 10808 with the actual HTTP proxy port used by your proxy software.

Step 3: Re-run and Verify After setting the proxy, run the gemini command again. This time, the authorization process should complete successfully, and you should enter the interactive interface.

Key Takeaways

• Prioritize Network Troubleshooting: In restricted network environments, address proxy or VPN stability first when encountering connection timeouts.
• Terminal Proxy is Essential: Command-line tools often require manual setting of the https_proxy environment variable to access the network through a proxy.
• Leverage Debug Mode: gemini -d is invaluable for resolving connection and authentication issues, providing detailed error logs.
• Use ping for Connectivity Testing: Commands like ping 216.239.32.223 can directly test network connectivity to the target server.