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

This article serves as a comprehensive guide to help you fully understand gemini-cli and focuses on resolving network, login, and configuration issues that Chinese users may encounter during installation and usage.

Gemini CLI vs. Claude Code: Why is it more suitable for Chinese users?

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

The emergence of gemini-cli can be said to have completely changed this situation. It is not only comparable to Claude Code in terms of functionality and performance, but also demonstrates great advantages in several key aspects:

• More friendly to Chinese users: The most important point is that due to the extremely anti-China stance of the CEO of the company where Claude is located, Claude Code has many restrictions on network access and account registration in China, especially when using Chinese dialogues, there is a high probability of being banned, and even just registering and recharging will welcome a ban package.
• Free and generous access to the Pro model: By logging in with a personal Google account, users can get up to 1000 free Gemini 2.5 Pro model requests per day. In contrast, Claude Code's high-performance models usually require a paid subscription.

For Chinese developers who are pursuing efficiency, stability, and freedom from regional restrictions, gemini-cli is undoubtedly a more attractive choice at the moment.

Installation and Startup

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

You can quickly start it with the npx command without global installation, which is also the official recommended test method:

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

Alternatively, you can choose to install it globally:

npm install -g @google/gemini-cli

gemini

When you start it for the first time, gemini-cli will guide you to choose a theme color and authentication method. Choose to log in with your Google account, not with an API key, for reasons see below.

Core "Troubleshooting" Guide: Solving Common Errors and Problems

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

Problem 1: Login Failure or Interruption Due to Network Issues

Symptoms: After executing the gemini command, it gets stuck at Waiting for auth... for a long time, or the terminal exits automatically without any prompts after the browser completes Google authorization. Using debug mode (gemini -d) may show an ETIMEDOUT (connection timeout) error.

Root Cause: This is a typical network problem. For well-known reasons, direct access to Google services will fail. gemini-cli does not read the system's global proxy settings by default, and the proxy needs to be configured separately for the terminal session where it is located.

Solutions:

1. Enable TUN mode of the proxy tool: This is one of the most direct and effective methods. TUN mode can take over the system's network traffic and ensure that terminal network requests can also pass through the proxy. Many Chinese users have shared that the login problem is solved after enabling this mode.

2. Set up a temporary proxy in the terminal: If your proxy tool does not support TUN mode, or you do not want to enable a 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"

     Please 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 the settings are complete, run gemini again in that terminal window to complete the login authorization normally.

Problem 2: Google Login Error (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 variables): GOOGLE_CLOUD_PROJECT environment variable not found.

Root Cause: These two errors usually appear together. When logging in with a Google account (whether personal or Workspace), gemini-cli needs to associate a Google Cloud project for quota management and API calls.

Solutions:

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

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

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

   • 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 related API services: This is a crucial step, otherwise you will encounter a Permission Denied (403) error.

   • In the search box of the Google Cloud Console, search for "Gemini".
   • Find and enable Gemini for Google Cloud API (may also be called Cloud AI Companion API). Some tutorials suggest enabling all three related libraries found to ensure everything works correctly.

4. Log in again:

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

Key Skills and "Big Pit" Reminders

The authentication method determines the available models and fees:

This is a very important distinction!

• Google account login: This is the correct way to get the free Gemini 2.5 Pro model and a generous daily quota of 1000 requests.
• API Key Login: Using an API Key generated from Google AI Studio is likely to be downgraded to the Gemini 2.5 Flash model, or will report an error because it does not have Pro permissions. In addition, calling with an API Key is paid, and it is easier to encounter 429 (request rate too fast) errors.

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

Practical Tips to Enhance the Experience

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

• Session Management: When the network is unstable, save the current conversation at any time to avoid wasting your efforts.

  • /chat save [label]: Save the current session and specify a label.
  • /chat list: List all saved conversations.
  • /chat resume [label]: Restore the specified session.

• Context Management (Memory Function):

  • GEMINI.md file: Create a GEMINI.md file in the project root directory or in the user's home directory ~/.gemini/. You can write custom instructions, code style guidelines, project background, etc. in it. gemini-cli will automatically load this information as long-term memory for 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 quota usage.