Recently, Google launched its open-source AI terminal agent tool—gemini-cli. This tool brings the powerful Gemini 2.5 Pro model directly into developers' command lines.

This article serves as a comprehensive guide to help you fully understand gemini-cli, focusing on solving network, login, and configuration problems that Chinese users may encounter during installation and use.

Gemini CLI vs. Claude Code: Why Is It More Suitable for Chinese Users?

Before gemini-cli was introduced, Claude Code was the go-to AI assistant in the terminal for many developers. However, for Chinese users, the experience with Claude Code has always had some hard-to-ignore obstacles.

The emergence of gemini-cli has completely changed this situation. It not only matches Claude Code in functionality and performance but also shows significant advantages in several key areas:

• More friendly to Chinese users: The most critical point is that due to the extremely anti-China stance of Claude's CEO, Claude Code imposes many restrictions on network access and account registration for users in China. Especially when using Chinese for conversations, there is a high risk of account suspension, sometimes even immediately after registration and payment.
• Free and generous access to the Pro model: By logging in with a Google personal account, users can get up to 1,000 free daily requests to the Gemini 2.5 Pro model. In contrast, Claude Code's high-performance models usually require a paid subscription.

For Chinese developers seeking efficiency, stability, and freedom from regional restrictions, gemini-cli is undoubtedly the more attractive choice right now.

Installation and Startup

Before starting, make sure your computer has Node.js installed (version v20+ is recommended).

You can quickly launch it using the npx command without global installation, which is the officially recommended way to test:

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

Alternatively, you can choose to install it globally:

npm install -g @google/gemini-cli

gemini

When starting for the first time, gemini-cli will guide you to choose a theme color and authentication method. Select login with a Google account, not an API key, for reasons explained later.

Core Troubleshooting Guide: Solving Common Errors and Issues

The following section compiles the most common issues users encounter when using gemini-cli and provides detailed, verified solutions.

Issue 1: Login Failure or Interruption Due to Network Problems

Symptoms: After running the gemini command, it gets stuck on Waiting for auth... for a long time, or the terminal automatically exits without any prompt after completing Google authorization in the browser. Using debug mode (gemini -d) might show ETIMEDOUT (connection timeout) errors.

Root Cause: This is a typical network issue. Due to well-known reasons, direct access to Google services often fails. gemini-cli does not read the system's global proxy settings by default and requires separate proxy configuration for its terminal session.

Solutions:

1. Enable TUN mode in your proxy tool: This is one of the most direct and effective methods. TUN mode can take over the system's network traffic, ensuring that terminal network requests also go through the proxy. Many Chinese users have shared that enabling this mode resolves login issues immediately.

2. Set a temporary proxy in the terminal: If your proxy tool does not support TUN mode, or you prefer not to enable global proxy, you can set environment variables for the current session in the terminal.

   • Windows (PowerShell):

     $env:HTTP_PROXY="http://127.0.0.1:port"
     $env:HTTPS_PROXY="http://127.0.0.1:port"

     Replace "port" with the actual HTTP proxy port of your proxy software.

   • macOS / Linux (Bash/Zsh):

     export HTTPS_PROXY="http://127.0.0.1:port"

   After setting this, run gemini again in the same terminal window to proceed with normal login authorization.

Issue 2: Google Login Errors (Workspace Account or Missing Project Configuration)

Symptoms:

• Error A (Workspace): Failed to login. Ensure your Google account is not a Workspace account...
• Error B (Missing environment variable): GOOGLE_CLOUD_PROJECT environment variable not found.

Root Cause: These two errors are often related. When using a Google account (whether personal or Workspace) for login, gemini-cli needs to associate with a Google Cloud project for quota management and API calls.

Solutions:

1. Log in to the Google Cloud Console and create a project:

   • Visit the Google Cloud Console.
   • If you don't have any projects, the system usually automatically creates one named My First Project. You can also create a new project yourself.

2. Get the Project ID and set the environment variable:

   • In the project selector at the top of the console, find your project and copy its ID (usually a string containing letters and numbers).
   • Set the GOOGLE_CLOUD_PROJECT environment variable in the terminal.
     • Windows (PowerShell):

       $env:GOOGLE_CLOUD_PROJECT="your-project-id"

     • macOS / Linux (Bash/Zsh):

       export GOOGLE_CLOUD_PROJECT="your-project-id"

3. Enable the relevant API service: This is a crucial step; otherwise, you may encounter insufficient permission (Permission Denied, 403) errors.

   • In the Google Cloud Console search bar, search for "Gemini".
   • Find and enable the Gemini for Google Cloud API (it might also be called Cloud AI Companion API). Some tutorials recommend enabling all three related libraries found in the search to be safe.

4. Log in again:

   • After completing the above steps, restart gemini-cli.
   • If you encounter the Workspace account error, try entering the /auth command in gemini-cli and manually select the "Login with Google Workspace" option to log in.

Key Tips and Major Pitfall Warnings

Authentication Method Determines Available Models and Costs:

This is a very critical distinction!

• Google Account Login: This is the correct way to get free access to the Gemini 2.5 Pro model and the generous daily quota of 1000 requests.
• API Key Login: Using an API Key generated from Google AI Studio might result in being downgraded to the Gemini 2.5 Flash model, or you might get errors due to lack of Pro permissions. Furthermore, API Key usage is paid and more prone to 429 (rate limit exceeded) errors.

Conclusion: For the vast majority of users, be sure to choose the Google Account Login method.

Practical Tips to Enhance Your Experience

Mastering the following common commands can greatly improve your gemini-cli experience:

• Session Management: Save the current conversation at any time when the network is unstable to avoid losing your work.

  • /chat save [tag]: Save the current session with a specified tag.
  • /chat list: List all saved sessions.
  • /chat resume [tag]: Resume the specified session.

• Context Management (Memory Feature):

  • GEMINI.md File: Create a GEMINI.md file in your project's root directory or in the ~/.gemini/ directory under your user home. You can write custom instructions, code style guidelines, project background, etc., in this file. gemini-cli will automatically load this information as long-term memory during each interaction.
  • /memory add [context content]: Add a piece of content to the current session's memory.
  • /memory show: View the currently loaded memory content.
  • /memory refresh: Reload the context from the GEMINI.md file.

• Statistics:

  • /stats: View your API call statistics to understand your quota usage.