2,199 stars · MIT · v0.12.0 (2026-05-19, ungh; the page summary read this as May 2025 and was wrong by a year) · Track this in Scout
Keeps Gmail filters as one declarative file written in Jsonnet, shows the difference before applying, and pushes the whole set through Google's own interface.
▶Repo detailsthe review · specs · pros & cons · install
What it is
gmailctl is a Go command-line tool that turns a declarative configuration into Gmail filters through Google's own API. The configuration is written in Jsonnet, a small language that allows comments, variables and reusable pieces, so a rule used in ten filters is written once.
What it is good for. Anyone whose inbox is held together by thirty filters built up over five years, none of which they can now explain. Writing them down makes the whole set visible, reviewable and copyable to a second account.
- It shows a difference before applying anything, so you can see which filters will be added, changed or removed.
- The configuration is a file, which means it can go in version control and be restored after a mistake.
- Variables and functions remove the repetition that makes a long filter list unreadable in the Gmail screen.
- The setup is the hard part. You have to create a Google Cloud project, switch on the Gmail API and download credentials before the first command works.
- Jsonnet is another small language to learn. It is not difficult, but it is not JSON either.
- Gmail's own limits still apply, including the cap on how many filters an account may hold.
- lefcha/imapfilter
937 stars, filters mail on any IMAP server using Lua scripts, so it is not tied to Gmail, but it runs the filtering itself rather than handing rules to the provider.
Track this in Scout - pimalaya/himalaya
6,702 stars, a terminal email client rather than a filter manager; the overlap is doing email from the command line.
Track this in Scout - antifuchs/gmail-britta
768 stars, the older Ruby answer to the same problem. Its last code landed 29 October 2022, forty-seven months ago.
Track this in Scout
# with Go installed go install github.com/mbrt/gmailctl/cmd/gmailctl@latest # or on macOS brew install gmailctl gmailctl init # walks you through the Google API setup gmailctl edit # write the rules gmailctl diff # see what would change gmailctl apply # apply it