So, you've heard about gemini-cli, the powerful command-line tool that brings Google's AI models directly to your terminal. You're excited, but maybe also a little wary. You've been down this road before: cryptic installation errors, confusing authentication steps, and that sinking feeling that you're missing a critical piece of the puzzle.

You're right to be cautious. For many developers, the journey stops before it even begins, blocked by obscure network proxy issues or confusing GOOGLE_CLOUD_PROJECT requirements.

This article is designed to change that narrative. It's more than just a quickstart; it's a battle-tested walkthrough that anticipates and solves the most common frustrations.

Now, let me help you get started quickly. The following is a complete, unabridged chapter excerpted from my comprehensive guide, Gemini CLI: From Zero to Automated Workflows.

Chapter 1: Flawless Installation & Environment Setup

The goal of this chapter is singular: to guide you flawlessly from zero to one. We will navigate the installation, solve common configuration issues preemptively, and get your first command running successfully in the shortest time possible.

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. The configuration is stored in ~/.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 (~/.gemini/.env).

  # Example for ~/.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:

       • URL: https://console.cloud.google.com/marketplace/product/google/cloudaicompanion.googleapis.com

    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.

You're All Set! But This is Just the Beginning...

Congratulations! You have successfully installed, configured, and authenticated gemini-cli, sidestepping the most common and frustrating issues that block new users. You now have a working tool, but you've only scratched the surface of its true potential.

What's next?

How do you use the @ command to make the AI understand your entire codebase? How do you craft a GEMINI.md file to teach it your project's specific coding standards? How do you set up an MCP server to connect it to external APIs and build truly powerful, automated workflows?

This setup guide is just the first step.

If you found this detailed chapter helpful, it's just a glimpse of the value packed into the complete, unofficial handbook: Gemini CLI: From Zero to Automated Workflows.

In the full guide, you will get exclusive access to:

• Advanced GEMINI.md strategies to craft a bespoke AI "brain" for your projects.
• Deep dives into every built-in tool, with practical examples that turn you into a power user.
• A full, step-by-step capstone project where we build a real-world automation engine from scratch.
• And much more...

Stop wasting hours on trial-and-error. Get the complete guide now and become a gemini-cli master today.