geminpy 1.4.0

Automated OAuth wrapper for Google Gemini CLI on macOS

geminpy

Automated OAuth wrapper for Google's Gemini CLI on macOS

geminpy eliminates the manual authentication steps required by Google's gemini CLI tool. It automatically handles the entire OAuth flow - from browser management to account selection - letting you use Gemini programmatically without interruption.

Why It Exists

Google's official gemini CLI requires manual OAuth authentication through a web browser each time you use it. This makes automation impossible and interrupts workflows. geminpy solves this by:

1. Automating the OAuth dance - No manual clicking through Google's authentication screens
2. Managing browser contexts - Uses isolated Chrome for Testing to avoid conflicts
3. Handling rate limits gracefully - Automatically retries with flash model when rate limited
4. Providing clean outputs - Filters authentication noise from responses

What It Does

geminpy acts as a transparent wrapper around the official gemini CLI, adding automation capabilities:

• Drop-in CLI replacement: Use it exactly like the original gemini command
• Programmatic API: Call Gemini from Python code with ask() function
• Multi-language support: Handles OAuth pages in 9+ languages
• Smart user detection: Remembers your preferred Google account
• Rate limit resilience: Automatic fallback to gemini-2.5-flash when quota exceeded
• Browser isolation: Uses Chrome for Testing to avoid disrupting your main browser

How It Works

Technical Architecture

The package orchestrates several components to achieve seamless automation:

User Request → GeminiClient → Browser Setup → OAuth Automation → Gemini CLI → Response
                     ↓              ↓               ↓                ↓
              BrowserManager  ChromeManager  OAuthAutomator  GeminiExecutor
                     ↓              ↓               ↓                ↓
              macdefaultbrowsy  Chrome CDP    Playwright      subprocess

Automation Flow

1. Browser Preparation

   • Installs Chrome for Testing if needed (via @puppeteer/browsers)
   • Saves current default browser
   • Temporarily switches to Chrome for Testing

2. OAuth Automation

   • Launches Chrome with remote debugging (--remote-debugging-port=9222)
   • Starts gemini CLI which opens OAuth URL
   • Playwright connects via Chrome DevTools Protocol
   • Automatically clicks your Google account
   • Detects and clicks sign-in button (multi-language, multi-strategy)
   • Waits for authentication success

3. Execution & Monitoring

   • Monitors gemini process output in real-time
   • Detects rate limits (429, quota exceeded, etc.)
   • Automatically retries with fallback model if needed
   • Extracts clean response from CLI output

4. Cleanup

   • Restores original default browser
   • Optionally quits Chrome
   • Returns pure response text

Key Components

• browser.manager: Controls macOS default browser via macdefaultbrowsy
• browser.chrome: Manages Chrome for Testing installation and lifecycle
• browser.automation: Playwright-based OAuth flow automation
• gemini.client: Main orchestrator coordinating all components
• gemini.executor: Subprocess management with real-time monitoring
• gemini.parser: Response extraction and cleaning

Installation

Prerequisites

macOS only - Browser automation requires macOS-specific tools.

Install geminpy

uv pip install geminpy

One-time setup: Install Playwright browsers

playwright install chromium

Usage

CLI Usage

Use exactly like the original gemini CLI:

# Ask a question
geminpy -p "Explain Python decorators"

# Use specific model with new shortcuts
geminpy -P -p "Write a Python function"  # Uses gemini-2.5-pro
geminpy -F -p "Quick question"           # Uses gemini-2.5-flash

# Traditional model selection still works
geminpy -m "gemini-pro" -p "Complex analysis"

# Enable verbose logging
geminpy --verbose -p "Debug this"

# Quit Chrome after completion
geminpy --quit-chrome -p "One-off query"

Programmatic Usage

from geminpy import ask

# Simple question-answer
response = ask("Explain quantum computing")
print(response)

# Async usage with full control
import asyncio
from geminpy import call_gemini_cli

async def main():
    response = await call_gemini_cli(
        gemini_args=["-m", "gemini-pro", "-p", "Your prompt"],
        user="[e-mail]",
        verbose=True,
        quit_browser=True
    )
    print(response)

asyncio.run(main())

Configuration

User Account Resolution

geminpy determines which Google account to use in this priority order:

1. CLI argument: --user="[e-mail]"
2. Environment variable: GEMINI_CLI_USER="[e-mail]"
3. Stored settings: From previous successful authentication
4. First available: Uses first Google account found

Settings Storage

Settings are automatically persisted to:

~/Library/Application Support/com.twardoch.chrometesting/settings.json

Contains:

• Chrome for Testing executable path
• Last used Google account email

Advanced Features

Multi-Language OAuth Support

Detects sign-in buttons in multiple languages:

• English, Polish, French, German, Spanish
• Italian, Russian, Japanese, Chinese
• Falls back to attribute and style-based detection

Rate Limit Handling

Automatic detection and retry logic:

Original request → Rate limit detected → Retry with gemini-2.5-flash → Final response

Browser Isolation

• Uses dedicated Chrome for Testing instance
• Preserves your regular browser state
• No profile contamination
• Clean OAuth every time

Troubleshooting

Common Issues

"Chrome CDP did not become available"

• Check if port 9222 is available: lsof -i :9222
• Look at Chrome logs: /tmp/gemini_chrome_stderr.log

"Could not find sign-in button"

• Enable verbose mode: --verbose
• Check screenshots: oauth_error.png, oauth_error_no_signin.png
• Ensure your Google account has Gemini access

Debug Mode

Enable comprehensive logging:

geminpy --verbose -p "Your question"

Shows:

• Chrome installation progress
• Browser switching operations
• OAuth automation steps
• Gemini CLI interactions
• Response parsing details

Development

Project Structure

src/geminpy/
├── browser/          # Browser automation components
│   ├── automation.py # OAuth flow automation
│   ├── chrome.py     # Chrome for Testing management
│   └── manager.py    # Default browser control
├── gemini/           # Gemini CLI integration
│   ├── client.py     # Main orchestrator
│   ├── executor.py   # Process management
│   └── parser.py     # Response extraction
├── core/             # Core utilities
│   ├── config.py     # Configuration
│   ├── constants.py  # Constants
│   └── exceptions.py # Custom exceptions
├── utils/            # Utilities
│   ├── platform.py   # Platform checks
│   └── storage.py    # Settings persistence
├── api.py            # Public API
└── cli.py            # CLI interface

Running Tests

# Run all tests
uvx hatch run test

# Run with coverage
uvx hatch run test-cov

# Type checking
uvx hatch run type-check

# Linting
uvx hatch run lint

Building

# Build package
uvx hatch build

# Install locally
uv pip install --system -e .

Security

• No credential storage - Only stores email preference
• Local automation only - All OAuth happens on your machine
• Temporary browser access - Restored after each use
• Process isolation - Chrome runs in separate process

Requirements

• Platform: macOS (Darwin) only
• Python: 3.10, 3.11, or 3.12
• Browser: Chrome for Testing (auto-installed)

License

MIT License - see LICENSE file for details.