Kagi Mail CLI client
README.md

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:

  1. In Kagi Mail's settings, open the app passwords page and create one.
  2. 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.

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.