<div align="center">
  <img src="https://raw.githubusercontent.com/dhruv13x/geminiai-cli/main/geminiai-cli_logo.png" alt="geminiai-cli logo" width="200"/>
</div>

<div align="center">

<!-- Package Info -->
[![PyPI version](https://img.shields.io/pypi/v/geminiai-cli.svg)](https://pypi.org/project/geminiai-cli/)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
![Wheel](https://img.shields.io/pypi/wheel/geminiai-cli.svg)
[![Release](https://img.shields.io/badge/release-PyPI-blue)](https://pypi.org/project/geminiai-cli/)

<!-- Build & Quality -->
[![Build status](https://github.com/dhruv13x/geminiai-cli/actions/workflows/publish.yml/badge.svg)](https://github.com/dhruv13x/geminiai-cli/actions/workflows/publish.yml)
[![Codecov](https://codecov.io/gh/dhruv13x/geminiai-cli/graph/badge.svg)](https://codecov.io/gh/dhruv13x/geminiai-cli)
[![Test Coverage](https://img.shields.io/badge/coverage-90%25%2B-brightgreen.svg)](https://github.com/dhruv13x/geminiai-cli/actions/workflows/test.yml)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Ruff](https://img.shields.io/badge/linting-ruff-yellow.svg)](https://github.com/astral-sh/ruff)
![Security](https://img.shields.io/badge/security-CodeQL-blue.svg)

<!-- Usage -->
![Downloads](https://img.shields.io/pypi/dm/geminiai-cli.svg)
[![PyPI Downloads](https://img.shields.io/pypi/dm/geminiai-cli.svg)](https://pypistats.org/packages/geminiai-cli)
![OS](https://img.shields.io/badge/os-Linux%20%7C%20macOS%20%7C%20Windows-blue.svg)
[![Python Versions](https://img.shields.io/pypi/pyversions/geminiai-cli.svg)](https://pypi.org/project/geminiai-cli/)

<!-- License -->
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

</div>

# Gemini AI Automation Tool

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

## About

`geminiai-cli` is a powerful, "batteries-included" command-line interface designed to supercharge your Gemini AI experience. Whether you need to manage multiple accounts, ensure your configuration is safely backed up to the cloud (S3 or B2), or track your free tier usage to avoid rate limits, this tool has you covered. It wraps complex operations into simple, memorable commands.

## 🚀 Quick Start

### Prerequisites

- **Python**: 3.8 or higher
- **Dependencies**: `b2sdk`, `boto3`, `rich` (installed automatically)

### One-Command Installation

```bash
pip install geminiai-cli
# Or from source
pip install .
```

### Usage Example

Get up and running immediately. You can use `geminiai`, `geminiai-cli`, or the shorthand `ga`.

```bash
# Run a local backup
geminiai backup

# Sync your backups to the cloud (Push to S3 or B2)
geminiai sync push

# Get the next best account recommendation
ga recommend

# Check your account cooldown status
ga cooldown

# Use a specific profile (e.g., work)
ga --profile work backup

# View all available commands
geminiai --help
```

## ✨ Key Features

- **🛡️ God Level Backups**: Create local or **Cloud-based** backups (AWS S3 & Backblaze B2) of your Gemini configuration and chats.
- **☁️ Multi-Cloud Support**: Native support for **AWS S3** and **Backblaze B2** for redundant cloud storage.
- **🔄 Unified Cloud Sync**: Seamlessly `push` and `pull` backups between your local machine and the cloud.
- **👤 Configuration Profiles**: Manage multiple environments (e.g., personal, work) with the `--profile` flag and `profile` command.
- **💬 Chat Management**: Backup, restore, resume, and **cleanup** chat sessions and logs.
- **🧠 Smart Recommendation**: Automatically switch to the best available account based on cooldowns and usage history.
- **⏱️ Resets Management**: Track your Gemini free tier reset schedules to maximize usage without hitting limits.
- **❄️ Cooldown Tracking**: Monitor account cooldown status to avoid rate limiting.
- **📊 Visual Usage Stats**: Visualize usage patterns over the last 7 days.
- **🩺 Doctor Mode**: Run a system diagnostic check to identify and fix issues.
- **🔐 Credential Management**: Securely handle credentials via CLI, Environment Variables, or Doppler.
- **⚡ Integrity Checks**: Verify your configuration integrity against backups.
- **🔄 Automated Updates**: Built-in self-update mechanism.
- **🧙 Interactive Wizard**: Guided setup process for easy configuration (`config --init`).

## ⚙️ Configuration & Advanced Usage

### Environment Variables

You can configure credentials using `.env` files, environment variables, or Doppler. The priority order is: CLI Args > Doppler > Env Vars > `.env` file > Saved Config.

| Variable | Description |
| :--- | :--- |
| `GEMINI_AWS_ACCESS_KEY_ID` | Your AWS Access Key ID (for S3). |
| `GEMINI_AWS_SECRET_ACCESS_KEY` | Your AWS Secret Access Key (for S3). |
| `GEMINI_S3_BUCKET` | The name of your AWS S3 Bucket. |
| `GEMINI_S3_REGION` | The AWS Region (default: `us-east-1`). |
| `GEMINI_B2_KEY_ID` | Your Backblaze B2 Application Key ID. |
| `GEMINI_B2_APP_KEY` | Your Backblaze B2 Application Key. |
| `GEMINI_B2_BUCKET` | The name of your Backblaze B2 Bucket. |
| `DOPPLER_TOKEN` | Token for fetching secrets from Doppler. |

### CLI Commands

| Command | Description | Key Arguments |
| :--- | :--- | :--- |
| `backup` | Backup configuration and chats. | `--src`, `--archive-dir`, `--dest-dir-parent`, `--cloud`, `--bucket`, `--dry-run` |
| `restore` | Restore configuration from backup. | `--from-dir`, `--from-archive`, `--search-dir`, `--cloud`, `--force`, `--auto` |
| `sync` | Sync backups with Cloud (S3/B2). | `push`, `pull`, `--backup-dir`, `--bucket`, `--b2-id`, `--b2-key` |
| `chat` | Manage chat history. | `backup`, `restore`, `cleanup` (w/ `--dry-run`, `--force`), `resume` |
| `list-backups` | List available backups. | `--cloud`, `--search-dir`, `--bucket` |
| `prune` | Delete old backups. | `--keep`, `--cloud`, `--cloud-only`, `--dry-run`, `--bucket` |
| `check-integrity` | Verify configuration integrity. | `--src` |
| `check-b2` | Verify B2 credentials. | `--bucket`, `--b2-id`, `--b2-key` |
| `config` | Manage persistent settings. | `set`, `get`, `list`, `unset`, `--init`, `--force` |
| `resets` | Manage free tier reset schedules. | `--list`, `--next` (w/ email/id), `--add`, `--remove` |
| `cooldown` | Show account cooldown status. | `--cloud`, `--remove`, `--bucket` |
| `recommend` | Suggest next best account. | *(No arguments)* (Alias: `next`) |
| `stats` | Show usage statistics. | *(No arguments)* (Alias: `usage`) |
| `profile` | Manage configuration profiles. | `export`, `import` (w/ `--force`) |
| `doctor` | Run system diagnostics. | *(No arguments)* |

### Global Options

| Option | Description |
| :--- | :--- |
| `--profile <name>` | Specify a configuration profile to use (e.g., `work`). |
| `--login` | Login to Gemini CLI. |
| `--logout` | Logout from Gemini CLI. |
| `--session` | Show current active session. |
| `--update` | Reinstall/update Gemini CLI. |
| `--check-update` | Check for updates. |

## 🏗️ Architecture

The project is structured as a modular Python CLI application using `argparse` for command handling and `rich` for the UI.

```text
src/geminiai_cli/
├── cli.py             # Main Entry Point & Argument Parsing
├── cloud_factory.py   # Cloud Provider Factory (S3/B2)
├── cloud_s3.py        # AWS S3 Integration
├── b2.py              # Backblaze B2 Integration
├── backup.py          # Backup Logic
├── restore.py         # Restore Logic
├── chat.py            # Chat History Management
├── sync.py            # Cloud/Local Sync Logic (Push/Pull)
├── recommend.py       # Smart Account Recommendation
├── profile.py         # Profile Import/Export Logic
├── stats.py           # Visual Usage Statistics
├── integrity.py       # Integrity Check Logic
├── prune.py           # Backup Pruning Logic
├── doctor.py          # System Diagnostics
├── cooldown.py        # Cooldown Tracking
└── reset_helpers.py   # Reset Schedule Management
```

## 🗺️ Roadmap

### ✅ Completed
- **Account Management**: Seamless login/logout.
- **Multi-Cloud Support**: AWS S3 & Backblaze B2 integration.
- **Unified Sync**: Push and Pull backups seamlessly.
- **Profiles**: Support for multiple configuration profiles.
- **Resets & Cooldowns**: Smart rate limit management.
- **Automated Updates**: Self-updating mechanism.
- **Health Checks**: Doctor mode for diagnostics.
- **Chat Management**: Backup, restore, and cleanup capabilities.
- **Smart Recommendations**: Intelligent account switching.
- **Interactive Config**: Wizard-style setup.

### 🚧 Upcoming
- **Google Cloud Storage Support**: Native GCS integration.
- **Enhanced TUI**: Rich dashboards and real-time progress bars.
- **Webhooks**: Integration with Slack/Discord for alerts.
- **AI-Driven Anomaly Detection**: Smart backup analysis.

## 🤝 Contributing & License

Contributions are welcome! Please submit a pull request or open an issue on the GitHub repository.

This project is licensed under the MIT License.
