google-gmail-cli

Unofficial filters-first CLI for Gmail. Sign in once in Chrome. Then list, create, and delete message filters.

Built by True Frontier. Not affiliated with Google.

Same pattern as google-keep-cli, google-photos-cli, and google-recorder-cli.

The session stays on your machine, in a local Chrome profile. This tool does not print cookies, and it does not ship a cloud login.

Requirements

• Python 3.10+
• Google Chrome

Install

pipx install git+https://github.com/truefrontier/google-gmail-cli.git

Or from a checkout:

pipx install .

Playwright uses your installed Chrome (channel="chrome"). You do not need playwright install chromium.

Commands

gmail login
gmail filters list
gmail filters list --limit 20
gmail filters list --compact | jq
gmail filters list --select id,matches,do_this --csv
gmail filters create --from "alerts@example.com" --skip-inbox
gmail filters create --query "unsubscribe" --mark-as-read
gmail filters delete <filter_id>

gmail login opens Chrome. Sign in, wait until Gmail loads, and the window closes. The profile is saved at ~/.gmail-cli/chrome-profile/.

If a command says the session expired, run gmail login again.

How it works

After login, the CLI opens Gmail Filters settings (#settings/filters) with your saved Chrome profile and reads the same filter table the web UI shows. Create/delete drive that settings UI (the documented gmail.googleapis.com settings.filters REST calls reject browser cookie auth).

Agent output

Inspired by CLI Printing Press agent UX:

• Piped stdout auto-uses JSON when --format is table (no --json needed)
• --compact for high-gravity fields only
• --select id,matches to project JSON/CSV fields
• --csv for spreadsheet-friendly rows
• --quiet / -q to suppress status lines
• Exit codes: 0 ok, 2 usage, 3 not found, 4 auth, 5 api/runtime

Limits

• Unofficial. Google can change the settings UI.
• Create/delete depend on the Filters settings dialogs; prefer --skip-inbox / --mark-as-read style actions.
• Do not commit ~/.gmail-cli/ (chrome-profile / capture).