fm-cli
Website: https://fm-cli.ninepointlabs.com
Fastmail from the terminal: a small Go client for Fastmail's JMAP API with a
full-screen mail app, a set of scriptable commands that print JSON, and a
live watch that follows your mailbox over Fastmail's push connection. It is
the engine behind the Fastmail plugin for Omarchy.
Install
On Omarchy:
omarchy-mise-install github:ninepointlabs/fm-cli fm-cli
With mise elsewhere:
mise use -g github:ninepointlabs/fm-cli@latest
With autonomix-cli:
autonomix-cli add https://github.com/ninepointlabs/fm-cli
Every release also ships
.pkg.tar.zst, .deb and .rpm packages and plain tarballs for Linux and
macOS. From source:
git clone https://github.com/ninepointlabs/fm-cli.git
cd fm-cli
go build -o fm-cli ./cmd/fm-cli
Go 1.26 or newer. No C toolchain needed.
Sign in
fm-cli auth login
This opens Fastmail's consent page in your browser. Approve fm-cli there and
you are done: the tokens go into your system keyring and refresh themselves.
No token to copy. Fastmail lists the authorization under Settings → Privacy &
Security → Connected apps, where you can revoke it.
Prefer an API token? Create one under Settings → Privacy & Security →
Integrations → API Tokens with the Email scope (add Email submission
to send), then:
fm-cli auth login --token # prompts, or reads the token from stdin
Other auth commands:
fm-cli auth status # signed in? as whom? (no network call)
fm-cli auth logout # revoke the authorization and forget it
fm-cli auth token # print a current bearer token for curl or scripts
fm-cli auth dav # store an app password for calendar and contacts
fm-cli setup # sign in only if signed out
Calendar and contacts use CalDAV and CardDAV, which need a Fastmail app
password with Mail, Contacts & Calendars access; fm-cli auth dav stores
it. For headless machines, FM_API_TOKEN, FM_EMAIL and FM_APP_PASSWORD in
the environment stand in for the keyring. FM_DEFAULT_FROM picks the default
sending identity; see Default sending identity.
The terminal app
fm-cli # the app, on its main menu
fm-cli tui --thread <thread-id> # the app, opened on a thread
fm-cli tui --thread <thread-id> --remote # tell a running app to jump there
Folders, threads, reading with links you can click, reply, reply all, forward,
compose in $EDITOR with contact autocomplete and a choice of sending
identity, drafts, flags, archive, move, delete, search, a two-week calendar
agenda, contacts, inline images in terminals that can draw them, and an
offline mode that caches mail in SQLite.
Keys
| Everywhere | |
|---|
0 1 2 3 4 5 | Main menu, Mail, Calendar, Contacts, Settings, About |
j k or arrows | Move |
Enter l | Open |
h Esc | Back |
r | Refresh |
/ | Filter the list; from the main menu, search all mail |
Ctrl+U | Clear the filter |
q | Quit, from the main menu |
| Email list | |
|---|
u | Toggle read/unread |
f | Toggle flag |
e | Archive |
d Backspace | Delete |
c | Compose |
| Reading | |
|---|
Space Ctrl+D / Ctrl+U | Page down / up |
g G | Top, bottom |
R A F | Reply, reply all, forward |
m | Toggle full headers |
b | Open the HTML in your browser |
i | Load and show the images inline |
e | Edit, for drafts |
| Compose and send | |
|---|
↑ ↓ Tab Enter | Pick a contact suggestion; Tab also cycles identities |
y s e n | Send, save as draft, edit body, cancel |
Calendar and contacts: n new, e edit, d delete from the detail view.
About (the last item on the main menu, or 5 from anywhere) shows the
version, Nine Point Labs, the license, what fm-cli does with your data and
the support address, [email protected].
There, l shows the full license, e starts an email to support with the
version details filled in, c copies the address and v the version
details. fm-cli about prints the same from the command line.
Scripting
Every command below takes --json and prints exactly one JSON object:
{"ok": true, "data": …, "summary": "…"} on success, and on stderr
{"ok": false, "error": "…", "code": "auth|usage|network|remote|busy"} on
failure. The full contract, with every field, is in
docs/omarchy-contract.md.
fm-cli account list --json
fm-cli box list --json
fm-cli box view inbox --limit 20 --json # one posting per thread, newest first
fm-cli box view all --json # Inbox plus every unseen thread in every other folder
fm-cli box view all --exclude "Other Services" --exclude Newsletters --json
fm-cli box create Receipts --parent Finance --json
fm-cli box rename "Other Services/Gmail" "Old Gmail" --json
fm-cli box delete Receipts --json # only an empty folder without subfolders
fm-cli box delete Receipts --move-to Archive --json # move its mail out first; --move-to alone means Trash
fm-cli seen <thread-or-email-id> --json
fm-cli unseen <thread-or-email-id> --json
fm-cli watch # a JSON line per change, live
fm-cli watch --box inbox --events new # only new unread mail in the Inbox
This is the beginning of the README. Read the rest at the original. Read the full README ↗
