Email CLI
Your inbox, from the terminal.
Find invoices, download attachments, file messages into folders and send reports with one command. JSON output for your scripts, and a CLI your AI agent can drive.
$ npm install -g @finopsbricks/fob-email$ fob email emails list \ --fields id,from,subject,attach ID FROM SUBJECT ATT ------------------------------------------------------ 1423 [email protected] Invoice INV-2291 * 1419 [email protected] September statement * 1417 [email protected] Remittance 88213 —
Two ways to drive it
The same commands work for you and for your agent.
You, in the terminal
Tables for reading, JSON for piping. Search by sender, subject or date, download attachments into a folder, and filter lists offline. Deletes ask for --yes.
$ fob email emails download 1423 -o ./invoicesOutput and scripting →Your AI agent
Claude Code, Cursor and Codex already run commands. Point them at fob-email and ask in plain English: "download every invoice that arrived this month".
$ fob email getting-started # the agent's first commandUse with AI agents →What it covers
Any IMAP mailbox that accepts an app password. Outlook and Microsoft 365 need OAuth and aren't supported yet.
| Area | Resources | Writes |
|---|---|---|
| Emails List, search, show and download attachments; mark read or unread, move, delete, send | List, search, show and download attachments; mark read or unread, move, delete, send | |
| Threads Group a folder into conversations and show a whole conversation | Group a folder into conversations and show a whole conversation | Read only |
| Drafts Create, replace, delete and send drafts | Create, replace, delete and send drafts | |
| Folders List, create, rename and delete folders | List, create, rename and delete folders | |
| Local sync Mirror headers into a local database for fast, offline --cached reads | Mirror headers into a local database for fast, offline --cached reads | Read only |
| Accounts Several mailboxes, switch with --account, or configure workers through one environment variable | Several mailboxes, switch with --account, or configure workers through one environment variable | Read only |
Every command and option: command reference →
Set up in four steps
About ten minutes, most of it creating an app password with your email provider.
- 1
Install
npm install -g @finopsbricks/fob-email - 2
Create an app password
In your Google, Yahoo, Apple or Fastmail account's security settings.
- 3
Add the account
fob-email config accounts add personal --imap-host imap.gmail.com … - 4
List your inbox
fob-email emails list --limit 10
Or run fob-email getting-started after installing, for the same steps with links for your provider. Full setup guide →
Questions
Does my mail go through FinOpsBricks?
No. fob-email runs on your machine and talks directly to your mail provider over IMAP and SMTP. Passwords stay in ~/.fob/fob-email/config.yml (mode 0600) and are never sent to us.
Which providers work?
Gmail, Google Workspace (if your admin allows app passwords), Yahoo, iCloud, Fastmail and other IMAP servers that accept a password. Outlook.com and Microsoft 365 don't: they require OAuth sign-in, which fob-email doesn't support yet. Providers →
Does reading mail mark it as read?
No. list, search, show and download leave messages unread. Only emails mark changes that.
Can I stop an AI agent from deleting or sending?
Not with fob-email itself: an account that can read can also move, delete and send. Keep your agent's approval prompts on for those commands, or give the agent a separate mailbox. Use with AI agents →
What does it cost?
Nothing. fob-email is open source under Apache-2.0.
Is it production-ready?
It's in Beta. Reading, searching, downloading and filing work on every supported provider. There's no OAuth, no paging beyond --limit, and no reply or forward yet. Beta limits →
fob-email is not affiliated with or endorsed by Google, Yahoo, Apple, Fastmail or Microsoft. Product names are trademarks of their owners.