Gemini CLI with Load Balancing Support

🌟 Fork Purpose

This is a fork of the official Google Gemini CLI that adds load balancing support for multiple Gemini API keys and custom proxy services.

Key Enhancements

• 🔄 Load Balancing: Distribute requests across multiple Gemini API keys using round-robin or random algorithms
• 🌍 Proxy Support: Route requests through custom proxy services (e.g., Cloudflare AI Gateway) to bypass regional restrictions
• ⚡ High Availability: Automatic failover when one API key hits rate limits or fails
• 📊 Rate Management: Per-API-key rate limiting configuration
• 🔧 Easy Configuration: Simple JSON configuration file setup

Use Cases

• Bypass Regional Restrictions: Route Gemini API calls through proxy services in supported regions
• Scale API Usage: Distribute load across multiple API keys to increase throughput
• Improve Reliability: Reduce downtime with automatic failover between providers
• Cost Optimization: Balance usage across different billing accounts

Original Description

This repository contains the Gemini CLI, a command-line AI workflow tool that connects to your tools, understands your code and accelerates your workflows.

With the Gemini CLI you can:

• Query and edit large codebases in and beyond Gemini's 1M token context window.
• Generate new apps from PDFs or sketches, using Gemini's multimodal capabilities.
• Automate operational tasks, like querying pull requests or handling complex rebases.
• Use tools and MCP servers to connect new capabilities, including media generation with Imagen, Veo or Lyria
• Ground your queries with the Google Search tool, built into Gemini.

🚀 Load Balancing Setup

To use the load balancing features, set up the GEMINI_BALANCE authentication method:

1. Create Configuration File

Create a JSON configuration file (e.g., gemini_balance_config.json):

{
  "providers": [
    {
      "base_url": "https://your-proxy.example.com:8080",
      "google_cloud_project": "your-project-id-1",
      "gemini_api_key": "your-gemini-api-key-1"
    },
    {
      "base_url": "https://your-proxy.example.com:8080",
      "google_cloud_project": "your-project-id-2", 
      "gemini_api_key": "your-gemini-api-key-2"
    }
  ],
  "preferences": {
    "api_key_rate_limit": 60,
    "api_key_schedule_algorithm": "round_robin"
  }
}

2. Set Environment Variable

export GEMINI_BALANCE_PATH=/path/to/your/gemini_balance_config.json

3. Run with Load Balancing

gemini-balance -p "Your prompt here"

The CLI will automatically use the GEMINI_BALANCE authentication method and distribute requests across your configured providers.

Configuration Options

• api_key_schedule_algorithm: "round_robin" or "random"
• api_key_rate_limit: Requests per minute per API key
• base_url: Custom proxy URL (optional, defaults to Google's API)

Quickstart

Install from npm (Recommended)

1. Prerequisites: Ensure you have Node.js version 20 or higher installed.

2. Install globally:

   npm install -g @zxbu/gemini-cli-balance

3. Run the CLI:

   gemini-balance -p "Your prompt here"

Alternative: Build from Source

1. Clone and build:

   git clone https://github.com/zxbu/gemini-cli-balance.git
   cd gemini-cli-balance
   npm install
   npm run build

2. Run locally:

   node packages/cli/dist/index.js -p "Your prompt here"

With Homebrew

1. Prerequisites: Ensure you have Homebrew installed.

2. Install the CLI Execute the following command in your terminal:

   brew install gemini-cli

   Then, run the CLI from anywhere:

   gemini

Common Configuration steps

3. Pick a color theme
4. Authenticate: When prompted, sign in with your personal Google account. This will grant you up to 60 model requests per minute and 1,000 model requests per day using Gemini.

You are now ready to use the Gemini CLI!

Use a Gemini API key:

The Gemini API provides a free tier with 100 requests per day using Gemini 2.5 Pro, control over which model you use, and access to higher rate limits (with a paid plan):

1. Generate a key from Google AI Studio.

2. Set it as an environment variable in your terminal. Replace YOUR_API_KEY with your generated key.

   export GEMINI_API_KEY="YOUR_API_KEY"

3. (Optionally) Upgrade your Gemini API project to a paid plan on the API key page (will automatically unlock Tier 1 rate limits)

Use a Vertex AI API key:

The Vertex AI API provides a free tier using express mode for Gemini 2.5 Pro, control over which model you use, and access to higher rate limits with a billing account:

1. Generate a key from Google Cloud.

2. Set it as an environment variable in your terminal. Replace YOUR_API_KEY with your generated key and set GOOGLE_GENAI_USE_VERTEXAI to true

   export GOOGLE_API_KEY="YOUR_API_KEY"
   export GOOGLE_GENAI_USE_VERTEXAI=true

3. (Optionally) Add a billing account on your project to get access to higher usage limits

For other authentication methods, including Google Workspace accounts, see the authentication guide.

Examples

Once the CLI is running, you can start interacting with Gemini from your shell.

You can start a project from a new directory:

cd new-project/
gemini
> Write me a Gemini Discord bot that answers questions using a FAQ.md file I will provide

Or work with an existing project:

git clone https://github.com/google-gemini/gemini-cli
cd gemini-cli
gemini
> Give me a summary of all of the changes that went in yesterday

Next steps

• Learn how to contribute to or build from the source.
• Explore the available CLI Commands.
• If you encounter any issues, review the troubleshooting guide.
• For more comprehensive documentation, see the full documentation.
• Take a look at some popular tasks for more inspiration.
• Check out our Official Roadmap

Troubleshooting

Head over to the troubleshooting guide if you're having issues.

Popular tasks

Explore a new codebase

Start by cding into an existing or newly-cloned repository and running gemini.

> Describe the main pieces of this system's architecture.

> What security mechanisms are in place?

> Provide a step-by-step dev onboarding doc for developers new to the codebase.

> Summarize this codebase and highlight the most interesting patterns or techniques I could learn from.

> Identify potential areas for improvement or refactoring in this codebase, highlighting parts that appear fragile, complex, or hard to maintain.

> Which parts of this codebase might be challenging to scale or debug?

> Generate a README section for the [module name] module explaining what it does and how to use it.

> What kind of error handling and logging strategies does the project use?

> Which tools, libraries, and dependencies are used in this project?

Work with your existing code

> Implement a first draft for GitHub issue #123.

> Help me migrate this codebase to the latest version of Java. Start with a plan.

Automate your workflows

Use MCP servers to integrate your local system tools with your enterprise collaboration suite.

> Make me a slide deck showing the git history from the last 7 days, grouped by feature and team member.

> Make a full-screen web app for a wall display to show our most interacted-with GitHub issues.

Interact with your system

> Convert all the images in this directory to png, and rename them to use dates from the exif data.

> Organize my PDF invoices by month of expenditure.

Uninstall

Head over to the Uninstall guide for uninstallation instructions.

Terms of Service and Privacy Notice

For details on the terms of service and privacy notice applicable to your use of Gemini CLI, see the Terms of Service and Privacy Notice.