Search, inspect, label, and back up Gmail from the terminal with guided OAuth setup, shell-friendly output, and reusable Gmail queries.
gmail-tool is built for fast mailbox exploration and repeatable command-line workflows. It works well for personal Gmail usage, local automation, and Google Workspace environments that need service account access.
- List Gmail labels
- Read full messages by Gmail message ID
- Search Gmail with raw Gmail search operators
- Reuse saved queries from
config.toml - Run actions against either labels or search results:
list,count,delete,backup,label-add --name <label_name>, andlabel-remove --name <label_name> - Export labels and message lists as
jsonorcsv - Filter message results with
--from-date,--to-date, and--starred true|false - Back up matching messages as resumable
.emlfiles - Optionally move successfully backed-up messages to Gmail Bin with
--deleteand--force - Use guided auth helpers including
gmail-tool auth login,gmail-tool auth check,gmail-tool auth paths,gmail-tool auth logout, andgmail-tool auth login --no-browser - Use OAuth desktop flow without requiring
config.toml - Use service account auth for Google Workspace domain-wide delegation
gmail-tool requires Python 3.12+.
python -m pip install gmail-toolVerify the install:
gmail-tool --versionbrew install joelee/oss/gmail-toolVerify the install:
gmail-tool --versionFor normal OAuth usage, config.toml is optional.
- In Google Cloud Console, create a Desktop OAuth client and enable the Gmail API.
- Save the downloaded client JSON to
~/.config/gmail-tool/client_secret.json. - Authenticate and verify access:
gmail-tool auth login
gmail-tool auth check
gmail-tool labelsIf you are on a remote shell or headless machine, use gmail-tool auth login --no-browser.
- Run a real query:
gmail-tool search from:bob@example.com has:attachmentFull credential setup steps are in Google Credentials.
Supported auth modes:
- OAuth desktop flow
- Service account flow for Google Workspace domain-wide delegation
For the normal OAuth desktop flow, config.toml is optional.
Quick start:
- Place your Desktop OAuth client JSON at
~/.config/gmail-tool/client_secret.json - Run
gmail-tool auth login - Run
gmail-tool auth check
Useful helpers:
gmail-tool auth pathsgmail-tool auth logoutgmail-tool auth login --no-browser
Default OAuth file locations when no overrides are set:
- client secret:
${XDG_CONFIG_HOME:-~/.config}/gmail-tool/client_secret.json - token:
${XDG_STATE_HOME:-~/.local/state}/gmail-tool/oauth-token.json
Credential setup instructions are in Google Credentials.
Show the CLI version:
gmail-tool --versionEnable debug output to stderr:
gmail-tool --verbose labelsList labels as JSON:
gmail-tool labels -f jsonAuth diagnostics:
gmail-tool auth checkRead a full message by identifier:
gmail-tool message read <MESSAGE_ID>Move a message to Bin:
gmail-tool message delete <MESSAGE_ID>
gmail-tool message delete <MESSAGE_ID> --forceSearch with a raw Gmail query:
gmail-tool search from:bob@example.com has:attachmentCount search matches:
gmail-tool search -a count from:bob@example.comAdd a label to all search matches:
gmail-tool search -a label-add --name FollowUp from:bob@example.comList built-in search examples:
gmail-tool search --list-query-examplesPrint a Gmail search operator cheat sheet:
gmail-tool search --cheat-sheetRun a saved query from config.toml:
gmail-tool search --saved-query recent_attachmentsBack up matching messages as .eml files:
gmail-tool search -a backup from:bob@example.com
gmail-tool search -a backup --backup-path /tmp/gmail-backups from:bob@example.com
gmail-tool search -a backup --backup-path /tmp/gmail-backups --delete from:bob@example.com
gmail-tool search -a backup --backup-path /tmp/gmail-backups --delete --force from:bob@example.comCount messages in a label:
gmail-tool label INBOX -a countgmail-tool label <LABEL> accepts either an exact Gmail label name such as @Later or an exact label ID such as Label_66.
List messages in a label:
gmail-tool label IMPORTANT -l 10 --starred trueOr export them as CSV:
gmail-tool label IMPORTANT -l 10 -f csvPlain-text list output includes message_id values that can be passed to message read.
The search command returns the same message list structure as label ... list.
Both label and search default to the list action. Use --action or -a to switch to count, delete, backup, label-add --name <name>, or label-remove --name <name>.
List supported actions:
gmail-tool label --list-actions
gmail-tool search --list-actions
gmail-tool search --help-action backup
gmail-tool label --help-action label-addSee config.toml, .env.sample, and Configuration.
All commands accept --config <path> or -c <path>. If omitted, config discovery falls back through environment, XDG, home config, /etc, and the project directory. If no config file is found, built-in OAuth defaults are used.
uv sync --dev
uv run pytest --cov=src/gmail_tool --cov-report=term-missing --cov-report=xml --cov-report=json
./scripts/update-coverage-badge.sh coverage.json
uv run pre-commit run --all-filesCoverage artifacts produced by CI:
coverage.jsoncoverage.xml.github/badges/coverage.json
PyPI publishing is handled by the GitHub Actions Publish workflow on version tags such as v0.2.2.
Release packaging steps are documented in Release Packaging.
Homebrew packaging steps are documented in Homebrew Packaging.
Live Gmail tests are opt-in and use your local .env and config.toml.
Run them with an existing OAuth token:
ENABLE_LIVE_GMAIL_TESTS=true uv run pytest -m live_gmailIf this is your first OAuth run and no token exists yet, allow browser authentication explicitly:
ENABLE_LIVE_GMAIL_TESTS=true ALLOW_GMAIL_OAUTH_BROWSER=true uv run pytest -m live_gmail -sThese tests verify Gmail API access against your real mailbox and are skipped unless explicitly enabled.