Gmail Cleaner

Gmail Cleaner is a modern command-line tool that helps you manage your Gmail inbox by deleting, archiving, or moving emails based on search queries. Built with Python, Typer, and uv, it offers a fast and secure way to clean up your mail.

Features

• Search & Action: Move to a 'to delete' label, archive, or permanently delete emails matching a query.
• Progressive Feedback: Real-time progress bars for both searching and batch operations (delete, archive, move).
• Whitelist Protection: Exclude emails containing whitelisted phrases automatically. Filtering is done server-side for speed and accuracy.
• Whitelist Management: Manage your exclusion list directly from the CLI.
• Modern CLI: Intuitive subcommands and beautiful help menus powered by Typer and Rich.
• Easy Installation: Global installation as a standalone tool via uv tool.

Installation

The recommended way to install Gmail Cleaner is using uv tool, which installs it in an isolated environment.

1. Install uv (if not already installed):

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone and Install:

   git clone https://github.com/mackrus/gmail-cleaner.git
   cd gmail-cleaner
   uv tool install . --force

   Alternatively, install directly from the repository:

   uv tool install git+https://github.com/mackrus/gmail-cleaner.git

Usage

Once installed, the gmail-cleaner command is available globally.

1. Search and Manage Emails

Use the run command to process emails matching a search query. After a search completes, the CLI will ask if you want to perform another search using the same flags.

• Move to 'to delete' label (Default):

  gmail-cleaner run "from:promotions@example.com"

• Archive emails:

  gmail-cleaner run "newsletter" --archive

• Permanently delete emails:

  gmail-cleaner run "spam" --permanently

2. Clean the 'to delete' Label

Permanently delete all emails currently in your 'to delete' label:

gmail-cleaner clean

3. Management

• Force re-authentication:

  gmail-cleaner remove-token

• View help:

  gmail-cleaner --help
  gmail-cleaner run --help

Whitelist Management

The whitelist ensures that important emails are never touched, even if they match your search query. The CLI now provides a dedicated command to manage it:

• Add a phrase:

  gmail-cleaner whitelist add "Important Project"

• Remove a phrase:

  gmail-cleaner whitelist remove "Important Project"

• List all phrases:

  gmail-cleaner whitelist list

Note: Filtering is now integrated directly into the Gmail search query for maximum efficiency.

Gmail API Credentials

To use this tool, you must provide your own Google Cloud credentials:

1. Go to the Google Cloud Console.
2. Create a project and enable the Gmail API.
3. Create OAuth 2.0 Client Credentials (Desktop App) and download the credentials.json.
4. Place the file in ~/.gmail-cleaner/credentials.json.

For more details, see OAUTH.md.

Uninstallation

To remove the tool and its configuration:

• Linux/macOS: ./uninstall.sh
• Windows: .\uninstall.ps1

Or manually via uv:

uv tool uninstall gmail-cleaner

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This tool can permanently delete emails. Use with caution. The authors are not responsible for any data loss.