km #
km is a command-line client for Kagi Mail in the style of
GitHub's gh. It speaks JMAP directly, so it should work with other JMAP servers
(it is developed against Stalwart, which Kagi Mail runs on), but only Kagi Mail is tested.
$ km mail list
# ID FROM SUBJECT DATE
1 bt2a… ● Alice Quarterly plan (3) 2h
2 bt1z… Bob Lunch? Tue
$ km mail view 1
$ km mail reply 1 --body "Sounds good."
Install #
With Go (1.27 or newer):
go install tangled.org/matilde.at/km@latest
From source:
git clone https://tangled.org/matilde.at/km && cd km
make build # produces ./km
install -m755 km ~/.local/bin/
Log in #
Kagi accounts sign in through Kagi, which third-party clients cannot use, so km
uses an app password:
- In Kagi Mail's settings, open the app passwords page and create one.
- Run
km auth login --with-password. It asks for your address, then for the app password at a hidden prompt.
km checks the pair against the server before saving it. Credentials go to the
system keyring (Secret Service or Keychain), or to ~/.config/km/token.json (mode 0600)
when no keyring is available.
km auth status # who you are logged in as
km auth logout # forget the stored credentials (revoke the app password in Kagi too)
From a script: km auth login --with-password -u me@example.com < password-file.
On other servers that allow OAuth, plain km auth login registers km and opens the
server's login page in a browser. KM_TOKEN supplies a bearer token directly, which is
useful in CI.
Commands #
| Command | |
|---|---|
km mail list [query] [-m mailbox] [-L n] [--messages] |
threads in a mailbox, newest first (Inbox by default) |
km mail search <query> |
search every mailbox |
km mail view <id> [--message] [--raw] [--html] [--web] |
read a thread or one message; --web opens it in Kagi Mail |
km mail download <id> [-D dir] [--pattern '*.pdf'] |
save attachments |
km mail send --to … --subject … [--body …|--body-file f] [--attach f] [--draft] |
compose and send |
km mail reply <id> [--all] / km mail forward <id> --to … |
reply and forward |
km mail archive|delete|move|mark <id>… |
triage |
km draft list|edit|send|delete |
drafts |
km mailbox list|create|rename|delete |
mailboxes (create Projects/2026/Q3 makes the whole path) |
km identity list |
sending identities |
km filter list|view|edit|push|activate|delete |
Sieve filters (validated before saving) |
km vacation status|set|off |
vacation auto-reply |
km api <Type/method> [-f k=v] [-F k=json] |
a raw JMAP call; km api --session prints the session |
km alias, km config, km completion <shell> |
conveniences |
km <command> --help has the details and examples.
Ids #
Commands work on threads by default. Add --message to target a single email (the
email ids are shown by km mail view). On a terminal, the most recent listing is
remembered, so you can use its row number (km mail view 2) or a unique prefix of an
id. In scripts, pass full ids: the pipe output of km mail list has them in the first
column.
Search #
Terms are ANDed. Quote values with spaces. A leading - negates a term.
| Term | Meaning |
|---|---|
from: to: cc: bcc: subject: body: |
header or body contains |
in:Archive |
in a mailbox (role, path such as Projects/Alpha, name or id) |
is:unread is:read is:flagged is:draft is:answered |
keywords (thread-wide in thread listings) |
has:attachment |
has an attachment |
after:2026-01-31 before:7d |
received after or before; dates are YYYY-MM-DD, or relative 7d 2w 3m |
larger:2m smaller:100k |
size |
| anything else | full-text search |
km mail search from:alice has:attachment after:3m
km mail list -m Archive -is:read subject:"weekly report"
Composing #
Without --body or --body-file, on a terminal, km opens $EDITOR on a message
with From:, To:, Cc: and Subject: headers. Save and quit to continue; leave it
unchanged or empty to abort. Before sending, it shows a summary and asks for
confirmation (--yes skips this). In a pipe, a body flag is required and nothing is
asked.
Replies set In-Reply-To and References, quote the original and mark it answered.
Forwards re-attach the original's attachments without downloading them.
Output #
On a terminal, output is aligned, coloured and uses relative dates. In a pipe, it is
tab-separated, with full ids and ISO 8601 dates, so it suits cut, awk and friends.
List, view and status commands accept --json fields. Run --json with no fields to
see which ones exist. Then --jq expr filters the result and --template formats it
with Go templates.
km mail list --json id,subject,unread --jq '.[] | select(.unread) | .id'
km mailbox list --json path,unreadThreads --template '{{range .}}{{.path}}: {{.unreadThreads}}{{"\n"}}{{end}}'
Aliases and extensions #
km alias set unread 'mail list is:unread'
km alias set --shell count 'km mail list --json id --jq length'
An executable called km-foo on your PATH runs as km foo, with KM_HOST set.
Files and environment #
~/.config/km/config.yml |
host, editor, pager, aliases (km config) |
~/.local/state/km/last-list.json |
ids of the last listing, for row numbers |
KM_HOST |
server (default mail.kagimail.com) |
KM_TOKEN |
bearer token, bypassing stored credentials |
EDITOR, VISUAL, PAGER, NO_COLOR |
as usual |
Exit codes: 0 ok, 1 error, 2 usage error, 4 not logged in.
Not in v1 #
Contacts, calendars and files; offline cache; push (watch); several accounts at once;
PGP and S/MIME; HTML composition.
Development #
See CONTRIBUTING.md. make test runs the suite against an
in-process fake JMAP server. KM_LIVE=1 go test ./internal/mail -run Live -v runs
read-only checks against your own account.
License #
MIT, see LICENSE.