cull-gmail/docs/readme/head.md

The cull-gmail provides a software library and command line program to enable the culling of emails using the Gmail API.

Quick Start

Get started with cull-gmail in minutes using the built-in setup command:

1. Get OAuth2 credentials from Google Cloud Console
2. Initialize cull-gmail with guided setup:

   # Interactive setup (recommended)
   cull-gmail init --interactive --credential-file ~/Downloads/client_secret.json
   
   # Or preview first
   cull-gmail init --dry-run
   

3. Verify your setup:

   cull-gmail labels
   

Main Features

• Easy initialization: Guided setup with OAuth2 credential validation and secure file handling
• Flexible configuration: Support for file-based config, environment variables, and ephemeral tokens
• Safety first: Dry-run mode by default, interactive confirmations, and timestamped backups
• Label management: List and inspect Gmail labels for rule planning
• Message operations: Query, filter, and perform batch operations on Gmail messages
• Rule-based automation: Configure retention rules with time-based filtering and automated actions
• Token portability: Export/import OAuth2 tokens for containerized and CI/CD environments

Running the optional Gmail integration test

An optional, ignored integration test exercises the Gmail API end-to-end (networked). It is ignored by default and will not run in CI.

Steps to run locally:

1. Ensure you have valid OAuth client credentials configured for the library (see ClientConfig::builder() usage in docs).
2. Run the test explicitly with the ignored flag:

cargo test --test gmail_message_list_integration -- --ignored

Notes:

• The test performs a lightweight listing (max 10 messages) and should be safe, but it still uses your Gmail account.
• Do not run this in CI; it is intended only for local verification.