> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gemini CLI

> Connect Gemini CLI to AihubMax

## Overview

[Gemini CLI](https://github.com/google-gemini/gemini-cli) is Google's open-source command-line AI tool that lets you interact with Gemini models directly from the terminal for code understanding, generation, and editing.

By connecting Gemini CLI to AihubMax, you can use AihubMax's Gemini model offerings.

<Warning>
  Gemini CLI does not support custom base URLs through configuration files. Configuration requires modifying source files inside the installed package. This modification needs to be reapplied after package updates.
</Warning>

## Prerequisites

<CardGroup cols={2}>
  <Card title="AihubMax API Key" icon="key">
    An active AihubMax API key with access to Gemini models. [Go to AihubMax →](https://api.aihubmax.com/console)
  </Card>

  <Card title="Node.js 20+" icon="node-js">
    Node.js v20 or later and npm are required for installing Gemini CLI. [Download Node.js →](https://nodejs.org/en/download/)
  </Card>
</CardGroup>

## Installation & Configuration

<Steps>
  <Step title="Step 1: Install Gemini CLI">
    ```bash theme={null}
    npm install -g @google/gemini-cli
    ```
  </Step>

  <Step title="Step 2: Set Your API Key">
    Before configuring environment variables, go to the [AihubMax Console](https://api.aihubmax.com/console) to create a dedicated key:

    1. Open the "API Keys" page and click "Create Key".
    2. Name the key "Gemini CLI" or another easily identifiable name.
    3. **Make sure to select the "Gemini\_CLI" group** — this group enables the additional transcoding and rate limits required by the Gemini protocol.

    <Warning>
      If you don't select the "Gemini\_CLI" group, Gemini CLI may not be able to call AihubMax's Gemini models properly, or you may encounter 403/429 errors.
    </Warning>

    After generating the key, set it as the `GEMINI_API_KEY` environment variable. Choose either method below: use **CC-Switch** for automatic injection, or manually export the variable in your shell profile.

    <Tabs>
      <Tab title="CC-Switch (Recommended)">
        1. Download and install the package matching your system from [GitHub Releases](https://github.com/farion1231/cc-switch/releases).
        2. In CC-Switch, add a new "Gemini CLI" configuration. Keep the default Base URL as `https://api.aihubmax.com`, and select "Custom Header" for the authentication method.
        3. Go back to the AihubMax key list, click **"Import to CCS"** next to your target key, and select the configuration you just created.

        ![One-click import of Gemini CLI configuration from AihubMax](https://zdaif.oss-cn-hangzhou.aliyuncs.com/asset/img/pages/aihubmax/20260329003930220.png)

        After launching a terminal through CC-Switch, the tool will automatically inject `GEMINI_API_KEY` into the current shell — no manual export needed.
      </Tab>

      <Tab title="macOS / Linux">
        ```bash theme={null}
        export GEMINI_API_KEY="sk-your-foxapi-api-key"
        ```

        Then reload your shell configuration:

        ```bash theme={null}
        source ~/.zshrc  # or source ~/.bashrc
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        ```powershell theme={null}
        [Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "sk-your-foxapi-api-key", "User")
        ```

        Restart PowerShell after setting the variable.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Step 3: Modify the Base URL">
    <Tip>
      CC-Switch only injects `GEMINI_API_KEY` — it does not modify the Base URL configuration inside the CLI installation directory. Regardless of which method you chose in the previous step, the following modification must be performed once.
    </Tip>

    Gemini CLI does not support custom base URLs through configuration. You need to modify two source files inside the installed package.

    First, find your npm global installation directory:

    ```bash theme={null}
    npm root -g
    ```

    If you've cloned this docs repository, you can also run the bundled helper script to patch both files automatically:

    ```bash theme={null}
    bash 101.api_docs/mintlify/ai-tools/patch-gemini-cli-base-url.sh
    ```

    The script resolves the global install directory, patches both `index.mjs` and `index.cjs`, and creates `.foxapi.bak` backups of the original files.

    Then modify the following two files:

    **File 1:** `{install_dir}/@google/gemini-cli/node_modules/@google/genai/dist/node/index.mjs` (around line \~11222)

    **File 2:** `{install_dir}/@google/gemini-cli/node_modules/@google/genai/dist/node/index.cjs` (around line \~11244)

    In both files, find and replace:

    ```js theme={null}
    // Before:
    initHttpOptions.baseUrl = `https://generativelanguage.googleapis.com/`;

    // After:
    initHttpOptions.baseUrl = `https://api.aihubmax.com/`;
    ```

    <Tip>
      On macOS/Linux, you can use `sed` for quick replacement:

      ```bash theme={null}
      INSTALL_DIR=$(npm root -g)
      sed -i.bak 's|https://generativelanguage.googleapis.com/|https://api.aihubmax.com/|g' \
        "$INSTALL_DIR/@google/gemini-cli/node_modules/@google/genai/dist/node/index.mjs" \
        "$INSTALL_DIR/@google/gemini-cli/node_modules/@google/genai/dist/node/index.cjs"
      ```
    </Tip>

    <Warning>
      After updating Gemini CLI (`npm update -g @google/gemini-cli`), the source files will be overwritten. You will need to re-apply this modification.
    </Warning>
  </Step>

  <Step title="Step 4: Start Using Gemini CLI">
    Launch Gemini CLI in your project directory:

    ```bash theme={null}
    cd /path/to/your/project
    gemini
    ```

    Or run a one-off command:

    ```bash theme={null}
    gemini "Explain the structure of this project"
    ```

    To switch models in interactive mode, type `/model`.
  </Step>
</Steps>

## Verify the Connection

Run a test command to confirm everything is working:

```bash theme={null}
gemini "Hello, please confirm you are working properly."
```

A successful response confirms that Gemini CLI is correctly routing through AihubMax.

## Available Models

| Model                    | Description                                  |
| ------------------------ | -------------------------------------------- |
| `gemini-2.5-pro`         | Most capable Gemini model for complex tasks  |
| `gemini-2.5-flash`       | Fast and efficient for everyday coding tasks |
| `gemini-3-pro-preview`   | Next-gen Gemini Pro preview                  |
| `gemini-3-flash-preview` | Next-gen Gemini Flash preview                |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication error">
    * Verify your `GEMINI_API_KEY` environment variable is set correctly, with a value that is your AihubMax API Key (starts with `sk-`).
    * Ensure the key has not expired and has sufficient balance.
    * Verify the key has access to Gemini models.
  </Accordion>

  <Accordion title="Connection timeout or errors">
    * Verify the base URL modification was applied correctly in **both** files (`index.mjs` and `index.cjs`).
    * Check your network connection to `api.aihubmax.com`.
    * Try using a VPN if your region has connectivity issues.
  </Accordion>

  <Accordion title="Changes lost after update">
    * After running `npm update -g @google/gemini-cli`, the source files are overwritten.
    * Re-apply the base URL modification following Step 3 above.
  </Accordion>

  <Accordion title="Model not available">
    * Confirm the model name matches the AihubMax model list.
    * Use `/model` in interactive mode to switch between available models.
  </Accordion>
</AccordionGroup>