pimalaya/himalaya

📫 Himalaya

CLI to manage emails

• Features
• Installation
• Configuration
• Usage
• Interfaces
• FAQ
• AI policy
• License
• Social
• Contributing
• Sponsoring

• Shared API for mailboxes, envelopes, flags, messages and attachments
• Protocol-specific APIs exposing each backend's full surface
• IMAP, SMTP, ManageSieve, JMAP, Gmail (REST API), Microsoft Graph (Outlook / Microsoft 365) support
• Maildir ^specs, m2dir ^specs, mbox ^specs, pimdir ^specs support
• Simple auth support for IMAP, SMTP and ManageSieve (anonymous, login, plain, oauthbearer, xoauth2, scram-sha-256)
• HTTP auth support for JMAP: basic, bearer
• TLS support:
  • Rustls with ring crypto
  • Rustls with aws crypto (requires rustls-aws feature)
  • Native TLS (requires native-tls feature)
• Discovery support:
  • PACC ^specs
  • Autoconfiguration (Thunderbird) ^specs
  • SRV DNS lookups ^rfc6186
  • JMAP session resolution ^rfc8620
• SOCKS5, HTTP proxy support, per account or via $ALL_PROXY and $HTTPS_PROXY
• TOML configuration with multi-account support
• JSON output via --json

Himalaya can be installed with the installer:

As root:

curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | sudo sh

As a regular user:

curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | PREFIX=~/.local sh

These commands install the latest binary from the GitHub releases section.

For a more up-to-date version than the latest release, check out the releases GitHub workflow and look for the Artifacts section. These pre-built binaries are built from the master branch.

cargo install --locked --git https://github.com/pimalaya/himalaya.git

With only IMAP+SMTP support:

cargo install --locked --git https://github.com/pimalaya/himalaya.git \
  --no-default-features \
  --features imap,smtp,rustls-ring

From the community repository:

pacman -S himalaya

Or the user repository:

git clone https://aur.archlinux.org/himalaya-git.git
cd himalaya-git
makepkg -isc

Or with yay:

yay -S himalaya-git

brew install himalaya

scoop install himalaya

From the COPR repo:

dnf copr enable atim/himalaya
dnf install himalaya

If you have the Flakes feature enabled:

nix profile install github:pimalaya/himalaya

Or run without installing:

nix run github:pimalaya/himalaya

Requires Rust 1.89 or later:

git clone https://github.com/pimalaya/himalaya
cd himalaya
cargo build --release --locked

The binary lands at target/release/himalaya.

Run himalaya. With no configuration file on disk, the wizard asks for an email address and discovers the services reachable from it, probing PACC, Thunderbird Autoconfiguration, RFC 6186 SRV and RFC 8620 JMAP resolution in parallel.

Picking one prompts the authentication it advertises, tests the connection, then writes the account to disk.

A persistent configuration is loaded from the first valid path among:

• $XDG_CONFIG_HOME/himalaya/config.toml
• $HOME/.config/himalaya/config.toml
• $HOME/.himalayarc

These are the same paths the himalaya-tui TUI looks at: one TOML file backs both binaries. CLI-only fields and TUI-only sections coexist without errors. See config.sample.toml for a documented template.

Override the path with -c <PATH>; multiple paths can be passed at once, separated by :. The first one is the base and the rest are deep-merged on top.

To add or reconfigure an account, run the bare himalaya wizard again and redirect its printed TOML into (or merge it with) your config file. There is no in-place edit subcommand; himalaya account list and himalaya account check inspect and validate the accounts already declared.

Proton does not expose IMAP/SMTP directly: run Proton Bridge, which synchronizes mail locally and serves it on a local IMAP/SMTP endpoint. The password is the one generated by the Bridge, not your Proton account password.

[accounts.proton]

imap.server = "imap://127.0.0.1:1143"
imap.sasl.plain.username = "example@proton.me"
imap.sasl.plain.password.command = "pass show proton-bridge"

smtp.server = "smtp://127.0.0.1:1025"
smtp.sasl.plain.username = "example@proton.me"
smtp.sasl.plain.password.command = "pass show proton-bridge"

To keep TLS on the local link, export the certificate generated by the Bridge and enable STARTTLS:

imap.starttls = true
imap.tls.cert = "/path/to/exported/cert.pem"

smtp.starttls = true
smtp.tls.cert = "/path/to/exported/cert.pem"

Fastmail needs an app password for IMAP/SMTP, or an API token for its native JMAP endpoint.

[accounts.fastmail]

imap.server = "imaps://imap.fastmail.com"
imap.sasl.plain.username = "example@fastmail.com"
imap.sasl.plain.password.command = "pass show fastmail"

smtp.server = "smtps://smtp.fastmail.com"
smtp.sasl.plain.username = "example@fastmail.com"
smtp.sasl.plain.password.command = "pass show fastmail"

To use JMAP instead, replace the imap/smtp blocks with a single jmap one:

jmap.server = "https://api.fastmail.com/jmap/session"
jmap.auth.bearer.token.command = "pass show fastmail"

Gmail rejects the account password over SASL PLAIN: generate an app password (requires 2-step verification) and feed it through password.command or password.raw.

[accounts.gmail]

imap.server = "imaps://imap.gmail.com:993"
imap.sasl.plain.username = "example@gmail.com"
imap.sasl.plain.password.command = "pass show gmail"

smtp.server = "smtps://smtp.gmail.com:465"
smtp.sasl.plain.username = "example@gmail.com"
smtp.sasl.plain.password.command = "pass show gmail"

mailbox.alias.inbox = "INBOX"
mailbox.alias.sent = "[Gmail]/Sent Mail"
mailbox.alias.drafts = "[Gmail]/Drafts"
mailbox.alias.trash = "[Gmail]/Trash"
mailbox.alias.archive = "[Gmail]/All Mail"

Every Gmail label shows up as a top-level IMAP mailbox, and the special ones live under the [Gmail]/ prefix, so quote them in the shell or reach them through an alias.

[Gmail]/All Mail is the archive holding every message, so aliasing it puts "search everything" one flag away: himalaya envelope search -m archive ....

To use Gmail's native REST API instead of IMAP/SMTP, replace the blocks above with a single OAuth 2.0 bearer token from a helper such as ortie:

gmail.auth.token.command = ["ortie", "token", "show", "-a", "gmail"]

Labels become mailboxes here too, but they carry the API's opaque label ids; address them by name (-m Himalaya-Test) and himalaya resolves the id.

Microsoft has retired basic authentication: use OAuth 2.0 via oauthbearer or xoauth2, with the access token supplied by an external helper such as ortie.

[accounts.outlook]

imap.server = "imaps://outlook.office365.com:993"
imap.sasl.xoauth2.username = "example@outlook.com"
imap.sasl.xoauth2.token.command = ["ortie", "token", "show", "-a", "outlook"]

smtp.server = "smtp://smtp-mail.outlook.com:587"
smtp.starttls = true
smtp.sasl.xoauth2.username = "example@outlook.com"
smtp.sasl.xoauth2.token.command = ["ortie", "token", "show", "-a", "outlook"]

To use the native Microsoft Graph API instead of IMAP/SMTP, replace the blocks above with a single OAuth 2.0 bearer token (sending goes through Graph too, so no SMTP is needed):

msgraph.auth.token.command = ["ortie", "token", "show", "-a", "msgraph"]

Mail folders carry Graph's opaque folder ids; address them by name (-m Archive) or by a well-known name (-m inbox) and himalaya resolves the id.

Standard IMAP and SMTP with your regular account password: no app password required.

[accounts.posteo]

imap.server = "imaps://posteo.de"
imap.sasl.plain.username = "example@posteo.net"
imap.sasl.plain.password.command = "pass show posteo"

smtp.server = "smtps://posteo.de"
smtp.sasl.plain.username = "example@posteo.net"
smtp.sasl.plain.password.command = "pass show posteo"

Per the iCloud Mail support page, the IMAP login is the name of your address, johnappleseed rather than johnappleseed@icloud.com, while the SMTP login is the full address.

A dedicated app-specific password is required.

[accounts.icloud]

imap.server = "imaps://imap.mail.me.com:993"
imap.sasl.plain.username = "johnappleseed"
imap.sasl.plain.password.command = "pass show icloud"

smtp.server = "smtp://smtp.mail.me.com:587"
smtp.starttls = true
smtp.sasl.plain.username = "johnappleseed@icloud.com"
smtp.sasl.plain.password.command = "pass show icloud"

mailbox.alias.sent = "Sent Messages"

Every command carries its own --help, the source of truth for its flags and syntax. The snippets below are a taste of the surface.

Backend-agnostic commands run on the account's first configured backend, or the one picked with -b/--backend. -m/--mailbox takes a mailbox id, name, alias or role (inbox, sent, drafts, trash...), and defaults to the inbox.

himalaya mailbox list
himalaya envelope list --page 2
himalaya envelope search from alice and after 2026-01-01 order by date desc
himalaya flag add --flag seen 1 2 3 5
himalaya message read 42
himalaya message copy --from INBOX --to Archives 42
himalaya attachment download 42

envelope search uses himalaya's own cross-backend query DSL; its grammar lives in himalaya envelope search --help.

Each backend also exposes its full native API under its own subgroup, always against that backend (-b/--backend is ignored here):

himalaya imap raw 'a1 SEARCH FROM "alice@example.com"\r\n'
himalaya jmap mailbox query --role drafts
himalaya gmail messages list -q "from:alice is:unread"
himalaya msgraph mail-folders list
himalaya smtp send -f me@example.com -t you@example.com < message.eml
himalaya sieve list
himalaya sieve check --script-file filters.sieve
himalaya sieve put main --script-file filters.sieve
himalaya sieve activate main

ManageSieve uses the optional sieve account block. RFC 5804 registers one port, 4190, and reaches TLS on it through STARTTLS, so a bare server address takes sieve:// with the upgrade on where the IMAP and SMTP ones take their implicit-TLS scheme.

sieves:// is accepted too, for the deployments listening for a handshake straight away. A password or a bearer token is refused on an unencrypted connection unless sieve.allow-cleartext-auth says otherwise.

capability, list, get, put, check, activate, deactivate, rename, delete and raw are available, and put and check accept a script file, inline text or stdin.

message compose / reply / forward cover simple cases through flags. For rich MIME (MML directives, signing, encryption, an editor-driven flow), chain a composer such as mml into message send / message add, or stage a prepared file as a draft:

himalaya message compose --to you@example.org --subject Hello --body Hi --send
mml compose >(himalaya message send)
himalaya message add -m drafts --flag draft < message.eml

See himalaya message send --help and the mml docs for the composer chaining.

Each invocation opens a fresh TCP+TLS+SASL session. To amortize the handshake, pair himalaya with sirup: it serves a pre-authenticated IMAP/SMTP session over a Unix socket that imap.server / smtp.server can point at.

Himalaya CLI is one of several front-ends to the Pimalaya libraries:

• pimalaya/himalaya-tui: official TUI (in active development)
• pimalaya/himalaya-vim: Vim plugin
• dantecatalfamo/himalaya-emacs: Emacs plugin
• jns/himalaya: Raycast extension
• openclaw/openclaw: OpenClaw SKILL
• parisni/dfzf: dfzf integration
• kezhenxu94/himalaya-fzf: interactive fzf front-end

imap.sasl.plain.passwd.raw = "***"
imap.sasl.plain.passwd.command = "pass show example"
imap.sasl.plain.passwd.command = ["pass", "show", "example"]

himalaya --log trace mailbox list

himalaya --log trace mailbox list 2>/tmp/himalaya.log

himalaya --log trace --log-file /tmp/himalaya.log mailbox list

This project is licensed under either of:

• MIT license
• Apache License, Version 2.0

• Chat on Matrix
• News on Mastodon or RSS
• Mail at pimalaya.org@posteo.net

Special thanks to the NLnet foundation and the European Commission that have been financially supporting the project for years:

• 2022 → 2023: NGI Assure
• 2023 → 2024: NGI Zero Entrust
• 2024 → 2026: NGI Zero Core
• 2026 → 2027: NGI Zero Commons Fund

This program is part of Pimalaya, free software funded entirely by grants and donations. If you find it useful, consider sponsoring its development: