gmail-cli

A CLI tool for syncing Gmail to a local SQLite database, optimized for agent workflows. Enables fast local search and reads without hitting the Gmail API on every query.

Installation

pip install -e .

Quick Start

1. Authenticate with Gmail:

   gmail-cli auth oauth

   Follow the wizard to set up OAuth2 credentials from Google Cloud Console.

2. Sync your Gmail:

   gmail-cli sync full

   This will download all your Gmail messages to a local SQLite database.

3. Search your messages:

   gmail-cli search "invoice"

4. Read a message:

   gmail-cli read <message-id>

Authentication

The tool uses OAuth2 to authenticate with Gmail. You'll need to:

1. Create a Google Cloud project
2. Enable the Gmail API
3. Create OAuth2 credentials (Desktop app)
4. Download and save the credentials to ~/.gmail-cli/credentials.json

Run gmail-cli auth oauth for a step-by-step wizard.

Configuration

All data is stored in ~/.gmail-cli/:

• credentials.json - Your OAuth credentials
• token.json - Auto-generated OAuth tokens
• gmail.db - SQLite database (created after first sync)
• attachments/ - Downloaded attachments

Commands

Authentication

• gmail-cli auth oauth - Set up OAuth2 authentication
• gmail-cli auth status - Show authentication status
• gmail-cli auth logout - Clear stored credentials

Status

• gmail-cli status - Show overall status (auth, database, sync state)

Sync

• gmail-cli sync full - Full sync of all Gmail messages (resumes if interrupted)
• gmail-cli sync full --force - Force fresh sync from scratch
• gmail-cli sync full --workers 2 - Adjust concurrent workers (1-10)
• gmail-cli sync incremental - Only sync changes since last sync

Search

• gmail-cli search "query" - Search messages using FTS5 full-text search
• gmail-cli search "query" --limit 100 - Limit number of results
• gmail-cli search "query" --json - Output as JSON for agents

Supports FTS5 syntax:

• Simple: gmail-cli search "invoice"
• Phrase: gmail-cli search '"quarterly report"'
• Boolean OR: gmail-cli search "invoice OR receipt"
• Boolean NOT: gmail-cli search "meeting NOT cancelled"

Read

• gmail-cli read <message-id> - View a message
• gmail-cli read <message-id> --raw - Show raw headers and body
• gmail-cli read <message-id> --json - Output as JSON

Threads

• gmail-cli thread <thread-id> - View all messages in a thread
• gmail-cli thread <thread-id> --json - Output as JSON

Attachments

• gmail-cli attachments list <message-id> - List message attachments
• gmail-cli attachments download <attachment-id> - Download attachment
• gmail-cli attachments download <attachment-id> -o path - Download to specific path

Development

See PLAN.md for the full implementation plan.

Tech Stack

• Python 3.12+
• Typer + rich-toolkit for CLI
• SQLite + FTS5 for storage and search
• Google APIs for Gmail access
• SQLModel for database models