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

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗