Python port of gmail-cli: manage multiple Gmail accounts and read recent mail from the terminal.

• Manage multiple Gmail accounts
• OAuth2 (Web client) with browser login
• run read — print recent mail to the terminal
• ui — Textual TUI (list + message body)
• Shared behavior with the Go tool: last-24h query, MIME parsing, optional --raw body

• uv (manages Python and dependencies)
• A Google Cloud project with Gmail API enabled
• OAuth Web client credentials

Install uv if needed:

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

Then sync the project (creates .venv and installs gmail-cli-py):

cd /path/to/gmail-cli-py
uv sync

Run commands via uv run (uses the project venv automatically):

uv run gmail-cli-py --help

To install the CLI on your PATH globally:

uv tool install .
# then: gmail-cli-py --help

1. Open Google Cloud Console
2. Create or select a project and enable the Gmail API
3. Create OAuth client ID → Application type: Web application
   • Authorized JavaScript origins: http://localhost:8080
   • Authorized redirect URIs: http://localhost:8080/callback
4. Copy the Client ID and Client secret

Config and tokens live under ~/.gmail-cli-py/:

uv run gmail-cli-py config set <client-id> <client-secret>
uv run gmail-cli-py config add [email protected]
uv run gmail-cli-py config delete [email protected]

On first read/UI use, your browser opens for OAuth; tokens are cached per account.

# Read up to 20 messages per account (last 24 hours)
uv run gmail-cli-py run read

# Custom count
uv run gmail-cli-py run read --count 20
uv run gmail-cli-py run read -n 5

# Raw decoded body (no HTML-to-text)
uv run gmail-cli-py run read --raw

# Terminal UI (30 messages per account)
uv run gmail-cli-py ui

In the UI: ← / → switch between the list and body panes, q quit.

gmail-cli-py
├── config
│   ├── set <id> <secret>
│   ├── add <email>
│   └── delete <email>
├── run
│   └── read [--count|-n] [--raw]
└── ui

uv sync          # includes dev deps (pytest) via dependency-groups
uv run pytest
uv run gmail-cli-py --help

Pin a Python version (optional):

uv python pin 3.12
uv sync

MIT — see LICENSE.