Gemini AI Automation Tool

The Swiss Army Knife for Gemini AI Automation - Backups, Cloud Sync, and Account Management.

geminiai-cli is a powerful, "batteries-included" command-line interface designed to supercharge your Gemini AI experience. It handles backups (Local, S3, B2), synchronizes data across devices, manages multiple profiles, and intelligently tracks account usage to bypass rate limits.

⚡ Quick Start (The "5-Minute Rule")

Prerequisites

• Python: 3.8 or higher
• Optional: AWS CLI or Backblaze B2 CLI for credentials management.

Installation

# Install from PyPI
pip install geminiai-cli

# Or install from source
pip install .

Get Started Immediately

Copy and paste this snippet to configure your first profile, backup to the cloud, and verify your system health.

# 1. Run the interactive setup wizard
geminiai config --init

# 2. Run your first local backup
geminiai backup

# 3. Push your backup to the cloud (requires configured credentials)
geminiai sync push

# 4. Check the account dashboard
geminiai cooldown --cloud

# 5. Get a smart account recommendation
geminiai recommend

✨ Features

Core Capabilities

• 🛡️ God Level Backups: Securely backup your configuration and chat history to Local, AWS S3, or Backblaze B2 storage. Supports GPG Encryption for sensitive data.
• 🌍 Machine-Time Adaptive: Automatically detects and uses your system's local timezone for all calculations and displays. No more manual IST/UTC conversions.
• ☁️ Unified Cloud Sync: Seamlessly push and pull backups between your local machine and the cloud.

Smart Automation

• ⏱️ Smart Session Tracking: Tracks "First Used" timestamps to accurately predict Gemini's 24-hour rolling quota resets.
• 🧠 Intelligent Rotation: Automatically recommends the "healthiest" account based on session start times and Least Recently Used (LRU) logic.
• 🛡️ Accident Protection: Safeguards your session data by preventing accidental account switches from resetting your 24-hour quota clock.

Diagnostics & Management

• 📊 Visual Analytics: View beautiful, terminal-based bar charts of your usage history and account health.
• 🩺 Doctor Mode: Built-in diagnostic tool to validate your environment, dependencies, and configuration health.
• 🧹 Auto-Pruning: Automatically cleans up old backups and temporary files to keep your storage efficient.

🛠️ Configuration

You can configure geminiai-cli using Environment Variables, CLI Arguments, or the Interactive Config (geminiai config --init).

Priority Order: CLI Arguments > Environment Variables > .env / Doppler > Saved Config (~/.geminiai-cli/settings.json)

Environment Variables

Key CLI Arguments

🏗️ Architecture

The geminiai-cli is built with modularity and extensibility in mind.

src/geminiai_cli/
├── cli.py             # 🚀 Entry Point & Argument Routing
├── config.py          # ⚙️ Global Constants & Paths
├── backup.py          # 📦 Backup Logic (Local & Cloud dispatch)
├── restore.py         # ♻️ Restore Logic (Auto-selection & Session logs)
├── cooldown.py        # ❄️ Master Dashboard & Adaptive Time Logic
├── recommend.py       # 🧠 Recommendation Engine (Session-aware)
├── sync.py            # 🔄 Unified Sync (Push/Pull)
├── cloud_factory.py   # ☁️ Cloud Provider Abstract Factory
└── stats.py           # 📊 Visualization Module

Data Flow

1. User Input: CLI args are parsed by args.py and routed by cli.py.
2. Configuration: Settings are loaded from settings_cli.py (merging Env, CLI, and Config).
3. Action:
   • Backup: Compresses ~/.gemini, encrypts (optional), and uploads via CloudFactory.
   • Restore: Fetches list from cloud/local, decrypts, and extracts to ~/.gemini.
   • Recommendation: Queries cooldown.py for account status and selects the LRU "Ready" account.
4. Persistence: Usage stats and cooldowns are saved to JSON files in ~/.geminiai-cli.

🐞 Troubleshooting

Debug Mode: Currently, you can increase verbosity by inspecting the logs or running with standard python tracebacks enabled (default).

🤝 Contributing

We welcome contributions! Whether it's reporting a bug, suggesting a feature, or writing code.

See CONTRIBUTING.md for detailed instructions.

1. Setup Dev Environment: pip install -e .[dev]
2. Run Tests: pytest tests/
3. Submit PR: Follow the guidelines in the contributing guide.

🗺️ Roadmap

• Phase 1 (Completed): Core Backup/Restore, Multi-Cloud (S3/B2), Sync, Auto-Updates.
• Phase 2 (Completed): Machine-Time Adaptation, Session Tracking, Smart Rotation.
• Phase 3 (Upcoming):
  • 🔔 Webhooks: Slack/Discord notifications for backup status.
  • 🐍 Python SDK: Import geminiai as a library in your own scripts.
• Phase 4 (Vision): AI-driven anomaly detection and self-healing infrastructure.

See ROADMAP.md for the full detailed vision.