@shbernal/buzon
v0.0.6
Published
CLI and agent skill for a self-hosted cloudflare_temp_email instance: tiered addresses, codes and links, a local registry, and deploys.
Downloads
1,193
Maintainers
Readme
Install • Quickstart • Commands • Agent skill • How it works • Docs
buzon is a CLI for a self-hosted cloudflare_temp_email instance, a mail server that runs on a Cloudflare Worker with D1. It creates addresses on your domain, waits for the verification code or magic link, and keeps a local record of which address belongs to which account.
- Three tiers in the address name:
stefor one code,mtefor a few weeks,ltefor a real account. The instance deletes expired ones by itself. wait --codeandwait --linkprint just the code or the link, ready for a script or an agent.- A local registry of every address with its site and note, so "which address did I use for GitHub?" has an answer.
- A first install in one command, then deploys and upgrades of the upstream release, with every database patch shown and confirmed.
- An agent skill that tells an AI agent when to pick each tier and how to get a code.
Why
Public temp-mail services are blocked by most sign-up forms, and their inboxes are readable by anyone who guesses the name. A catch-all on your own domain avoids both, but turns into a pile of addresses nobody remembers. buzon puts a lifetime on each address, cleans up the short ones, and records the long ones.
Install
With Bun:
bun add -g @shbernal/buzonOr as a standalone binary, with no Bun needed, for linux-x64, linux-arm64, darwin-x64 or
darwin-arm64 from the latest release:
curl -fsSL https://github.com/shbernal/buzon/releases/latest/download/buzon-linux-x64.tar.gz | tar -xz -C ~/.local/binbuzon reads its passwords from BUZON_SITE_PASSWORD and BUZON_ADMIN_PASSWORD, or else from
the keyring: the Secret Service through secret-tool on Linux, the Keychain on macOS.
Shell completion covers commands, flags, and the addresses and sites in the registry:
buzon completion bash > ~/.local/share/bash-completion/completions/buzon
buzon completion zsh > "${fpath[1]}/_buzon"
buzon completion fish > ~/.config/fish/completions/buzon.fishNo instance yet? docs/deploying.md goes from a domain on Cloudflare to a
running one, mostly through buzon init --deploy.
Quickstart
Store the instance's site password in the keyring, on Linux:
secret-tool store --label="buzon site-password" service buzon key site-passwordOn macOS:
security add-generic-password -s buzon -a site-password -wElsewhere, export
BUZON_SITE_PASSWORDinstead.Point buzon at the instance. It checks that the instance answers, serves the domain and accepts the password before writing anything:
buzon init --url https://mail.example.com --domain example.comCreate a one-shot address and use it on a sign-up form:
buzon new steWait for the code, then delete the address:
buzon wait ste-2610-9qa --code --since 10mbuzon delete ste-2610-9qa
For an account you will come back to, keep the address and say what it is for:
buzon new lte --site github --note "GitHub account for side projects"Commands
| Command | Does |
| -------------------------------- | ---------------------------------------------------------- |
| new <ste\|mte\|lte> | Create an address, with --site and --note |
| new custom <name> | Create an address with a name you choose, such as jane |
| wait <address> | Wait for new mail and print its --code, --link or text |
| read <address> | Print the latest mail, --all, or one --id |
| list, show <address> | Registry entries, filtered by --tier or --site |
| note, delete, adopt | Edit, remove, or take in an address made elsewhere |
| route <address> | Give an address on a routed domain its routing rule |
| init --deploy | First install: database, schema, secrets and release |
| secrets push | Put the passwords and the JWT secret on the Worker |
| deploy, upgrade, export-db | Ship a release, move to a newer one, dump the database |
Every command takes --json. buzon --help lists every command and flag.
Agent skill
skills/buzon teaches an agent to pick the tier, get a code or link,
and find an address again later. Install it with:
npx skills add shbernal/buzonA test fails the build when the skill names a command or flag the CLI does not have.
How it works
Cloudflare Email Routing hands every message for your domain to the Worker, which stores it in D1.
A daily cron deletes expired ste and mte addresses by the tier in their name.
buzon talks to the Worker over its HTTPS API, and keeps the registry of sites and notes on your
machine only.
