feat(auth): enable Gemini CLI stateless authentication via environment variables

Implement support for loading Gemini CLI credentials directly from environment variables (e.g., GEMINI_CLI_ACCESS_TOKEN) for stateless hosting environments.

The credential management tool (`credential_tool.py`) now includes a new option to export existing file-based Gemini OAuth credentials into a standard .env file format, simplifying setup for platforms without persistent storage.

- Provider logic is updated to prioritize loading credentials from environment variables over local files.
- Prevents saving newly refreshed access tokens back to the file system when the credentials originated from environment variables.
- Updates README documentation detailing the new tool option and required environment variables.
- Adds `time` import and `Accept` header for robustness.

README.md

@@ -119,6 +119,25 @@ For many providers, **no configuration is necessary**. The proxy automatically d
 
 You only need to create a `.env` file to set your `PROXY_API_KEY` and to override or add credentials if the automatic discovery doesn't suit your needs.
 
+#### Interactive Credential Management Tool
+
+For easier credential management, you can use the interactive credential tool:
+
+```bash
+python -m rotator_library.credential_tool
+```
+
+This tool provides:
+1. **Add OAuth Credential** - Interactive OAuth flow for Gemini CLI, Qwen Code, and iFlow
+2. **Add API Key** - Add API keys for any LiteLLM-supported provider
+3. **Export Gemini CLI to .env** - NEW! Export OAuth credentials to environment variables for stateless deployments
+
+**For Stateless Hosting (Railway, Render, Vercel, etc.):**
+- Use option 3 to export your Gemini CLI credentials to `.env` format
+- The generated file contains all necessary environment variables
+- Simply paste these into your hosting platform's environment settings
+- No file persistence required - credentials load automatically from environment variables
+
 **Example `.env` configuration:**
 ```env
 # A secret key for your proxy server to authenticate requests.
@@ -137,6 +156,16 @@ OPENROUTER_API_KEY_1="YOUR_OPENROUTER_API_KEY_1"
 # You can override this by specifying a path to your credential file.
 GEMINI_CLI_OAUTH_1="/path/to/your/specific/gemini_creds.json"
 
+# --- Gemini CLI: Stateless Deployment Support ---
+# For hosts without file persistence (Railway, Render, etc.), you can provide
+# Gemini CLI credentials directly via environment variables:
+GEMINI_CLI_ACCESS_TOKEN="ya29.your-access-token"
+GEMINI_CLI_REFRESH_TOKEN="1//your-refresh-token"
+GEMINI_CLI_EXPIRY_DATE="1234567890000"
+GEMINI_CLI_EMAIL="your-email@gmail.com"
+# Optional: GEMINI_CLI_PROJECT_ID, GEMINI_CLI_CLIENT_ID, etc.
+# See IMPLEMENTATION_SUMMARY.md for full list of supported variables
+
 # --- Dual Authentication Support ---
 # Some providers (qwen_code, iflow) support BOTH OAuth and direct API keys.
 # You can use either method, or mix both for credential rotation:

src/rotator_library/credential_tool.py

@@ -3,6 +3,7 @@
 import asyncio
 import json
 import re
+import time
 from pathlib import Path
 from dotenv import set_key, get_key
 
@@ -220,6 +221,102 @@ async def setup_new_credential(provider_name: str):
         console.print(Panel(f"An error occurred during setup for {provider_name}: {e}", style="bold red", title="Error"))
 
 
+async def export_gemini_cli_to_env():
+    """
+    Export a Gemini CLI credential JSON file to .env format.
+    Generates one .env file per credential.
+    """
+    console.print(Panel("[bold cyan]Export Gemini CLI Credential to .env[/bold cyan]", expand=False))
+
+    # Find all gemini_cli credentials
+    gemini_cli_files = list(OAUTH_BASE_DIR.glob("gemini_cli_oauth_*.json"))
+
+    if not gemini_cli_files:
+        console.print(Panel("No Gemini CLI credentials found. Please add one first using 'Add OAuth Credential'.",
+                          style="bold red", title="No Credentials"))
+        return
+
+    # Display available credentials
+    cred_text = Text()
+    for i, cred_file in enumerate(gemini_cli_files):
+        try:
+            with open(cred_file, 'r') as f:
+                creds = json.load(f)
+            email = creds.get("_proxy_metadata", {}).get("email", "unknown")
+            cred_text.append(f"  {i + 1}. {cred_file.name} ({email})\n")
+        except Exception as e:
+            cred_text.append(f"  {i + 1}. {cred_file.name} (error reading: {e})\n")
+
+    console.print(Panel(cred_text, title="Available Gemini CLI Credentials", style="bold blue"))
+
+    choice = Prompt.ask(
+        Text.from_markup("[bold]Please select a credential to export or type [red]'b'[/red] to go back[/bold]"),
+        choices=[str(i + 1) for i in range(len(gemini_cli_files))] + ["b"],
+        show_choices=False
+    )
+
+    if choice.lower() == 'b':
+        return
+
+    try:
+        choice_index = int(choice) - 1
+        if 0 <= choice_index < len(gemini_cli_files):
+            cred_file = gemini_cli_files[choice_index]
+
+            # Load the credential
+            with open(cred_file, 'r') as f:
+                creds = json.load(f)
+
+            # Extract metadata
+            email = creds.get("_proxy_metadata", {}).get("email", "unknown")
+            project_id = creds.get("_proxy_metadata", {}).get("project_id", "")
+
+            # Generate .env file name
+            safe_email = email.replace("@", "_at_").replace(".", "_")
+            env_filename = f"gemini_cli_{safe_email}.env"
+            env_filepath = OAUTH_BASE_DIR / env_filename
+
+            # Build .env content
+            env_lines = [
+                f"# Gemini CLI Credential for: {email}",
+                f"# Generated from: {cred_file.name}",
+                f"# Generated at: {time.strftime('%Y-%m-%d %H:%M:%S')}",
+                "",
+                f"GEMINI_CLI_ACCESS_TOKEN={creds.get('access_token', '')}",
+                f"GEMINI_CLI_REFRESH_TOKEN={creds.get('refresh_token', '')}",
+                f"GEMINI_CLI_EXPIRY_DATE={creds.get('expiry_date', 0)}",
+                f"GEMINI_CLI_CLIENT_ID={creds.get('client_id', '')}",
+                f"GEMINI_CLI_CLIENT_SECRET={creds.get('client_secret', '')}",
+                f"GEMINI_CLI_TOKEN_URI={creds.get('token_uri', 'https://oauth2.googleapis.com/token')}",
+                f"GEMINI_CLI_UNIVERSE_DOMAIN={creds.get('universe_domain', 'googleapis.com')}",
+                f"GEMINI_CLI_EMAIL={email}",
+            ]
+
+            # Add project_id if present
+            if project_id:
+                env_lines.append(f"GEMINI_CLI_PROJECT_ID={project_id}")
+
+            # Write to .env file
+            with open(env_filepath, 'w') as f:
+                f.write('\n'.join(env_lines))
+
+            success_text = Text.from_markup(
+                f"Successfully exported credential to [bold yellow]'{env_filepath}'[/bold yellow]\n\n"
+                f"To use this credential:\n"
+                f"1. Copy [bold yellow]{env_filepath.name}[/bold yellow] to your deployment environment\n"
+                f"2. Load the variables: [bold cyan]export $(cat {env_filepath.name} | grep -v '^#' | xargs)[/bold cyan]\n"
+                f"3. Or source it: [bold cyan]source {env_filepath.name}[/bold cyan]\n"
+                f"4. The Gemini CLI provider will automatically use these environment variables"
+            )
+            console.print(Panel(success_text, style="bold green", title="Success"))
+        else:
+            console.print("[bold red]Invalid choice. Please try again.[/bold red]")
+    except ValueError:
+        console.print("[bold red]Invalid input. Please enter a number or 'b'.[/bold red]")
+    except Exception as e:
+        console.print(Panel(f"An error occurred during export: {e}", style="bold red", title="Error"))
+
+
 async def main():
     """
     An interactive CLI tool to add new credentials.
@@ -229,20 +326,20 @@ async def main():
     
     while True:
         console.print(Panel(
-            Text.from_markup("1. Add OAuth Credential\n2. Add API Key"),
+            Text.from_markup("1. Add OAuth Credential\n2. Add API Key\n3. Export Gemini CLI credential to .env"),
             title="Choose credential type",
             style="bold blue"
         ))
-        
+
         setup_type = Prompt.ask(
             Text.from_markup("[bold]Please select an option or type [red]'q'[/red] to quit[/bold]"),
-            choices=["1", "2", "q"],
+            choices=["1", "2", "3", "q"],
             show_choices=False
         )
 
         if setup_type.lower() == 'q':
             break
-        
+
         if setup_type == "1":
             available_providers = get_available_providers()
             oauth_friendly_names = {
@@ -282,6 +379,9 @@ async def main():
         elif setup_type == "2":
             await setup_api_key()
 
+        elif setup_type == "3":
+            await export_gemini_cli_to_env()
+
         console.print("\n" + "="*50 + "\n")
 
 def run_credential_tool():

src/rotator_library/providers/gemini_auth_base.py

@@ -1,7 +1,8 @@
 # src/rotator_library/providers/gemini_auth_base.py
 
+import os
 import webbrowser
-from typing import Union
+from typing import Union, Optional
 import json
 import time
 import asyncio
@@ -29,13 +30,80 @@ class GeminiAuthBase:
         self._credentials_cache: Dict[str, Dict[str, Any]] = {}
         self._refresh_locks: Dict[str, asyncio.Lock] = {}
 
+    def _load_from_env(self) -> Optional[Dict[str, Any]]:
+        """
+        Load OAuth credentials from environment variables for stateless deployments.
+
+        Expected environment variables:
+        - GEMINI_CLI_ACCESS_TOKEN (required)
+        - GEMINI_CLI_REFRESH_TOKEN (required)
+        - GEMINI_CLI_EXPIRY_DATE (optional, defaults to 0)
+        - GEMINI_CLI_CLIENT_ID (optional, uses default)
+        - GEMINI_CLI_CLIENT_SECRET (optional, uses default)
+        - GEMINI_CLI_TOKEN_URI (optional, uses default)
+        - GEMINI_CLI_UNIVERSE_DOMAIN (optional, defaults to googleapis.com)
+        - GEMINI_CLI_EMAIL (optional, defaults to "env-user")
+        - GEMINI_CLI_PROJECT_ID (optional)
+
+        Returns:
+            Dict with credential structure if env vars present, None otherwise
+        """
+        access_token = os.getenv("GEMINI_CLI_ACCESS_TOKEN")
+        refresh_token = os.getenv("GEMINI_CLI_REFRESH_TOKEN")
+
+        # Both access and refresh tokens are required
+        if not (access_token and refresh_token):
+            return None
+
+        lib_logger.debug("Loading Gemini CLI credentials from environment variables")
+
+        # Parse expiry_date as float, default to 0 if not present
+        expiry_str = os.getenv("GEMINI_CLI_EXPIRY_DATE", "0")
+        try:
+            expiry_date = float(expiry_str)
+        except ValueError:
+            lib_logger.warning(f"Invalid GEMINI_CLI_EXPIRY_DATE value: {expiry_str}, using 0")
+            expiry_date = 0
+
+        creds = {
+            "access_token": access_token,
+            "refresh_token": refresh_token,
+            "expiry_date": expiry_date,
+            "client_id": os.getenv("GEMINI_CLI_CLIENT_ID", CLIENT_ID),
+            "client_secret": os.getenv("GEMINI_CLI_CLIENT_SECRET", CLIENT_SECRET),
+            "token_uri": os.getenv("GEMINI_CLI_TOKEN_URI", TOKEN_URI),
+            "universe_domain": os.getenv("GEMINI_CLI_UNIVERSE_DOMAIN", "googleapis.com"),
+            "_proxy_metadata": {
+                "email": os.getenv("GEMINI_CLI_EMAIL", "env-user"),
+                "last_check_timestamp": time.time(),
+                "loaded_from_env": True  # Flag to indicate env-based credentials
+            }
+        }
+
+        # Add project_id if provided
+        project_id = os.getenv("GEMINI_CLI_PROJECT_ID")
+        if project_id:
+            creds["_proxy_metadata"]["project_id"] = project_id
+
+        return creds
+
     async def _load_credentials(self, path: str) -> Dict[str, Any]:
         if path in self._credentials_cache:
             return self._credentials_cache[path]
-        
+
         async with self._get_lock(path):
             if path in self._credentials_cache:
                 return self._credentials_cache[path]
+
+            # First, try loading from environment variables
+            env_creds = self._load_from_env()
+            if env_creds:
+                lib_logger.info("Using Gemini CLI credentials from environment variables")
+                # Cache env-based credentials using the path as key
+                self._credentials_cache[path] = env_creds
+                return env_creds
+
+            # Fall back to file-based loading
             try:
                 lib_logger.debug(f"Loading Gemini credentials from file: {path}")
                 with open(path, 'r') as f:
@@ -52,6 +120,12 @@ class GeminiAuthBase:
 
     async def _save_credentials(self, path: str, creds: Dict[str, Any]):
         self._credentials_cache[path] = creds
+
+        # Don't save to file if credentials were loaded from environment
+        if creds.get("_proxy_metadata", {}).get("loaded_from_env"):
+            lib_logger.debug("Credentials loaded from env, skipping file save")
+            return
+
         try:
             with open(path, 'w') as f:
                 json.dump(creds, f, indent=2)

src/rotator_library/providers/gemini_cli_provider.py

@@ -596,6 +596,7 @@ class GeminiCliProvider(GeminiAuthBase, ProviderInterface):
                     "User-Agent": "google-api-nodejs-client/9.15.1",
                     "X-Goog-Api-Client": "gl-node/22.17.0",
                     "Client-Metadata": "ideType=IDE_UNSPECIFIED,platform=PLATFORM_UNSPECIFIED,pluginType=GEMINI",
+                    "Accept": "application/json",
                 })
                 try:
                     async with client.stream("POST", url, headers=final_headers, json=request_payload, params={"alt": "sse"}, timeout=600) as response: