Gemini CLI Auth Manager

Gemini CLI Auth Manager is a lightweight tool designed for the Google Gemini CLI environment. It supports instant multi-account switching, automatic rotation on quota exhaustion, and unified account pool management!

📖 中文版本 (Chinese Version)

---

✨ Features

• Instant Switching: Switch between multiple accounts in seconds.
• Auto-Backup: Automatically saves your credentials upon switching.
• 🆕 Gemini 3.1 Series Support: Fully compatible with the latest gemini-3.1-pro and gemini-3.1-flash-lite models.
• 🆕 Intelligent Rotation Strategies:
  • gemini3.1-series-only (Default): Monitors all 3.1 models.
  • gemini3.1-pro-only: Focuses exclusively on Pro model quota.
  • custom: Supports regex-based model matching.
• Quota Pre-check: Real-time quota monitoring via Google API, auto-switches before exhaustion (Default threshold: 10%).
• Native OAuth Login: One-click browser login to officially authenticate and capture accounts directly.
• Interactive Menu: Visual configuration interface (gchange menu).
• Slash Command: Seamlessly integrated as /change in Gemini CLI.

---

🚀 Installation

git clone https://github.com/Besty0728/Gemini-CLI-Auth-Manager.git
cd Gemini-CLI-Auth-Manager
python install.py

Dependencies

• Python 3.8+
• requests library (pip install requests)
• Gemini CLI available as gemini on your PATH

Linux/macOS Notes

• The installer creates ~/.gemini/gchange and links it as ~/.local/bin/gchange when possible.
• If gchange is not found after installation, add this to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

---

🛠 Usage

1. Slash Commands (Inside Gemini CLI)

Command	Description
/change <n>	Switch to account #n
/change next	Switch to the next available account
/change menu	Open the interactive management menu
/change strategy	View or change rotation strategy
/change config	Quick view of auto-switch configuration

2. Terminal Commands

Command	Description
gchange	List all accounts and status
gchange <n>	Fast switch to account #n
gchange menu	Open interactive menu (Recommended)
gchange pool login	Add a new account via OAuth
gchange uninstall	Uninstall this tool

---

⚙️ Configuration

Settings are stored in ~/.gemini/auth_config.json.

Key	Default	Description
strategy	gemini3.1-series-only	conservative, gemini3.1-pro-only, gemini3.1-series-only, custom
threshold	10	Switch account when remaining quota < 10%
model_pattern	gemini-3.1.*	Regex pattern for model monitoring
auto_restart	false	Automatically restart CLI after a switch when the current platform can launch gemini

---

📂 Project Structure

~/.gemini/
├── gemini_cli_auth_manager.py  # Core script
├── auth_config.json            # Configuration file
├── google_accounts.json        # Account index metadata
├── auth_profiles/              # Account credentials storage
│   ├── user1@gmail.com/
│   └── ...
├── hooks/
│   ├── quota_pre_check.py      # BeforeAgent Hook
│   └── quota_auto_switch.py    # AfterAgent Hook
└── commands/
    └── change.toml             # Slash command config

---

📅 Changelog

[v2.6] - 2026-05-11

• 🗑 New: One-click uninstall via gchange uninstall [--force] [--keep-accounts] and python install.py --uninstall.
• 🛠 Fix: gchange now works immediately after install — no terminal restart needed.
• 🛠 Fix: Uninstall no longer touches PATH to avoid breaking Gemini CLI's own entries.

[v2.5] - 2026-05-06

• 🛠 Fix: Corrected the directory name in the installation instructions (cd Gemini-CLI-Auth-Manager) so the steps work on case-sensitive systems like Linux and macOS. (Thanks @getbot887, closes #5)

[v2.4] - 2026-05-03

• 🌍 Cross-Platform: Added Linux and macOS compatibility — Unix launcher, dynamic platform detection, sys.executable for subprocess calls. (Thanks @bincat233)
• 🛠 Fix: Handle quoted combined commands like 'pool login' correctly. (Thanks @victorinfinops)
• 🛠 Fix: auto_restart config key can now be set via gchange config.

[v2.3] - 2026-03-22

• ✨ Enhancement: Fully updated UI and internal logic to version 2.3.
• ✨ Optimization: Improved response speed and accuracy of quota monitoring.
• 🛠 Fix: Resolved several residual references and display issues from v2.2.
• 🚀 Installer: Upgraded installer for more reliable hook configurations.

[v2.2] - 2026-02-15

• 🆕 Gemini 3.1 Support: Added auto-rotation support for gemini-3.1-pro and gemini-3.1-flash-lite.
• 🆕 Smart Strategies: Introduced rotation strategies like gemini3.1-series-only.
• ⚡ Auto-Rotation: Implemented automatic account switching based on quota pre-checks.

---

🗑 Uninstall

One-command cleanup removes all installed files:

# Interactive uninstall (shows what will be removed, asks for confirmation)
gchange uninstall

# Skip confirmation
gchange uninstall --force

# Keep account data (profiles + tracking)
gchange uninstall --keep-accounts

Alternatively, run from the source directory:

python install.py --uninstall

What gets removed:

• Core script, CLI launcher, slash command, hook scripts, config file
• Auto-switch hooks from settings.json (other settings preserved)
• GEMINI_FORCE_FILE_STORAGE environment variable
• Account data (profiles + tracking) — unless --keep-accounts is used

PATH entries are intentionally left untouched, as ~/.gemini may be shared with Gemini CLI itself.

❤️ Credits

Developed by Besty. Feel free to submit Issues or PRs!