https://github.com/patrick91/gmail-cli
https://github.com/patrick91/gmail-cli
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/patrick91/gmail-cli
- Owner: patrick91
- Created: 2026-01-17T16:59:06.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-27T23:26:47.000Z (5 months ago)
- Last Synced: 2026-03-19T07:50:10.087Z (3 months ago)
- Language: Python
- Size: 128 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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
```bash
pip install -e .
```
## Quick Start
1. **Authenticate with Gmail:**
```bash
gmail-cli auth oauth
```
Follow the wizard to set up OAuth2 credentials from Google Cloud Console.
2. **Sync your Gmail:**
```bash
gmail-cli sync full
```
This will download all your Gmail messages to a local SQLite database.
3. **Search your messages:**
```bash
gmail-cli search "invoice"
```
4. **Read a message:**
```bash
gmail-cli read
```
## 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 ` - View a message
- `gmail-cli read --raw` - Show raw headers and body
- `gmail-cli read --json` - Output as JSON
### Threads
- `gmail-cli thread ` - View all messages in a thread
- `gmail-cli thread --json` - Output as JSON
### Attachments
- `gmail-cli attachments list ` - List message attachments
- `gmail-cli attachments download ` - Download attachment
- `gmail-cli attachments download -o path` - Download to specific path
## Development
See [PLAN.md](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