Himalaya is a low-level CLI: plain text for a human to glance at, JSON for scripts and frontends. For daily mail, pair it with one of the interfaces.
- Features
- Installation
- Configuration
- Usage
- Interfaces
- FAQ
- AI policy
- License
- Social
- Contributing
- Sponsoring
- Unified API for
mailboxes,envelopes,flags,messagesandattachments - Protocol-specific APIs exposing each backend's full surface
- IMAP, SMTP, ManageSieve, JMAP, Gmail (REST API), Microsoft Graph (Outlook / Microsoft 365) support
- Maildir 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-awsfeature) - Native TLS (requires
native-tlsfeature)
- SOCKS5, HTTP proxy support, per account or via
$ALL_PROXYand$HTTPS_PROXY - TOML configuration with multi-account support
- Plain text output: every list one item per line the way
mscanprints a mailbox, under the account it read, records asLabel: valuelines, no border, no colour - JSON output via
--json - REPL via
himalaya repl, running commands over connections kept for the session - MCP server via
himalaya mcp, the unified API as tools, read-only by default
Tip
Himalaya is written in Rust and uses cargo features to gate backend support. The default feature set is declared in Cargo.toml.
The default vendored feature builds SQLite from source; leave it out (--no-default-features --features …) to link the system one.
Himalaya can be installed with the installer:
As root:
curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | sudo shAs a regular user:
curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | PREFIX=~/.local shThese 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.
Note
Such binaries are built with the default cargo features. If you need specific features, please use another installation method.
cargo install --locked --git https://github.com/pimalaya/himalaya.gitWith only IMAP+SMTP support:
cargo install --locked --git https://github.com/pimalaya/himalaya.git \
--no-default-features \
--features imap,smtp,rustls-ringFrom the community repository:
pacman -S himalayaOr the user repository:
git clone https://aur.archlinux.org/himalaya-git.git
cd himalaya-git
makepkg -iscOr with yay:
yay -S himalaya-gitbrew install himalayaNote
Cargo features are not compatible with brew. If you need a different feature set, please use another installation method.
scoop install himalayaFrom the COPR repo:
dnf copr enable atim/himalaya
dnf install himalayaIf you have the Flakes feature enabled:
nix profile install github:pimalaya/himalayaOr run without installing:
nix run github:pimalaya/himalayaRequires Rust 1.89 or later:
git clone https://github.com/pimalaya/himalaya
cd himalaya
cargo build --release --lockedThe binary lands at target/release/himalaya.
Himalaya reads a TOML configuration you write, and never writes one. config.sample.toml holds one account: the options every account shares with their values, then one commented section per backend or provider, yours to uncomment: IMAP and SMTP, ManageSieve, JMAP, Gmail, Microsoft Graph, Microsoft IMAP and SMTP, Fastmail, Maildir, mbox and pimdir. The OAuth 2.0 sections read their token from Ortie, whose sample has the matching sections. Releases and packages ship it as share/doc/himalaya/config.sample.toml.
Run without a configuration at a terminal, Himalaya welcomes you with the commands copying the shipped sample in place, or downloading it when none ships, then the first command to run. Under --json or in a script, it fails naming the path it looked at and the sample.
The imap, smtp and sieve blocks take one SASL mechanism, or none to skip authentication: plain, login and scram-sha-256 with a username and a password, oauthbearer and xoauth2 with a username and a token, anonymous with an optional message. jmap.auth takes basic (username and password), bearer (token) or header, a whole Authorization value. A secret is given as raw or as command, a shell string or an argument list printing it.
display-name, signature, signature-delim, downloads-dir and the message, envelope and mailbox options may also sit at the top level, before any table, as the fallback of every account not setting them: drop the sample's default lines from an account for the top level to apply.
A persistent configuration is loaded from every existing path among the following, each one deep-merged on top of the ones before, so $HOME/.himalayarc overrides the others (a path naming a file already loaded, such as a symlinked rc file, is skipped):
- $XDG_CONFIG_HOME/himalaya/config.toml
- $HOME/.config/himalaya/config.toml
- $HOME/.himalayarc
At most one account may be marked default = true across them: an rc file moving the default sets default = false on the account the other file marks.
These are the same paths the himalaya-tui TUI looks at: one TOML file backs both binaries. The TUI-only keys live under a [tui] table, at the top level and in an account ([accounts.<name>.tui]), which Himalaya leaves to the TUI; any other key Himalaya does not know fails the configuration.
Override those paths with -c <PATH>. Repeat it to merge several files, such as -c public.toml -c private.toml: the first one is the base and the next ones are deep-merged on top. Each -c takes one path, never split, and no environment variable is read.
To add an account, add an [accounts.<name>] table to your config file. himalaya account list and himalaya account check inspect and validate the accounts 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 xoauth2, Exchange refusing oauthbearer, 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 42envelope search uses himalaya's own cross-backend query DSL: date, after, before, from, to, cc, bcc, address (any of the four), subject, body, flag and attachment clauses, joined with and, or and not, grouped with parentheses, then order by. -h lists the clauses and himalaya envelope search --help gives the grammar and how each backend matches text. A clause a backend cannot search is refused with the code search-unsupported rather than dropped (every flag on Microsoft Graph, flag answered and keywords on Gmail, attachment on IMAP).
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
himalaya pimdir search from:alice@example.com has:attachment date:2026-01..2026-03ManageSieve 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.
On a pimdir account, pimdir search, pimdir count, pimdir thread and pimdir tag ask the store's search index in the pimdir query language: words, phrases, field:value terms, and, or, not and parentheses, over the account's mail. The store's sync engine builds the index and refreshes it after each run; Himalaya only reads it, so a message shows once it is synced and indexed, and a line above the results says what they could not see (bodies not downloaded, mail older than what the store holds, the index lagging the store). pimdir tag queues one flag change per matched message for the sync engine to apply.
message compose / reply / forward build a message from flags, then print it, save it with --save or send it with --send; message send / add take a raw message as it is. 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.emlSee 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, there are two options:
himalaya replkeeps one process alive for one account: each stdin line is a command without the binary name (envelope list,message read 42), run over clients that connect the first time a command needs them and stay connected for the session. Quote arguments as in a shell, start a comment with#;quit,exitor EOF ends it. The account, the configuration and--backendare given once, on thereplcommand, a line setting-a,-cor-bbeing refused;--jsonthere switches the whole session to JSON, on a line that line alone. Piped, every line gets one answer on stdout (one JSON value per line under--json, a failure being the error object, the help going to stderr), so a program can drive it. Stdin carries the commands, so a command takes its input as an argument or a file path, never from stdin. SMTP still connects per send, a server dropping an idle SMTP connection after a few minutes, and a command that fails drops its client so the next one connects again.- sirup serves a pre-authenticated IMAP/SMTP session over a Unix socket that
imap.server/smtp.servercan point at, shared by every process: the choice for many short invocations, or several tools at once. Do not point ahimalaya replat a sirup socket yet: sirup serves one client at a time and keeps the upstream alive only while none is attached.
himalaya mcp runs a Model Context Protocol server over stdio for one account, exposing the unified API as tools (mailbox_list, envelope_list, envelope_search, message_read, attachment_list, attachment_download, the composers, and so on). Each tool takes the arguments of its command, spelled as on the command line (mailbox, page-size, message-id, message-ids), and answers the same JSON as --json; an argument a tool does not take is refused, never ignored. Clients connect once for the server's lifetime, as in himalaya repl.
Only the tools that read are listed by default. --allow-write adds the ones that change the store (flags, add, copy, move, delete, saving a composed message, marking a read one seen), and --allow-send the ones that send mail. An agent reading mail can be told by a message to send mail, so think twice before giving it both. Tools never read nor write local files: attachment_download always runs as attachment download --stdout, message parse and the file arguments of the composers are left out, and a message given to message_add or message_send is taken as the message itself, even when it spells a path. attachment_download returns the part's bytes as an embedded resource, and the composers take their attachments inline instead, as attach-data: a list of {filename, mimeType, data, text}, data in base64 or text as is. Either way, an attachment over --max-attachment-size <BYTES> (10 MiB by default) is refused with attachment-too-large. Under --allow-send this lets an agent send any data it holds, not only text.
{
"mcpServers": {
"himalaya": { "command": "himalaya", "args": ["mcp", "--account", "work"] }
}
}Himalaya CLI is one of several front-ends to the Pimalaya libraries:
- pimalaya/himalaya-tui: official TUI (in active development), which links Himalaya as a library and runs its commands in-process. The library is the TUI's alone, pinned by git revision, and carries no semver promise beyond the CLI grammar and its
--jsonoutput. - 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
How different is it from aerc, mutt or alpine?
Aerc, mutt and alpine can be categorized as Terminal User Interfaces (TUI). When the program is executed, your terminal is locked into an event loop and you interact with your emails using keybinds.
Himalaya is a Command-Line Interface (CLI). There is no event loop: you interact with your emails using shell commands, in a stateless way.
A dedicated TUI (himalaya-tui) is in active development on top of the same Pimalaya libraries, and is definitely closer to aerc, mutt and alpine.
How are secrets resolved?
Every *.passwd / *.password / *.token field accepts either a raw literal or a shell command that prints the secret on stdout. The raw form is convenient for testing but should not be used in production:
imap.sasl.plain.passwd.raw = "***"
imap.sasl.plain.passwd.command = "pass show example"
imap.sasl.plain.passwd.command = ["pass", "show", "example"]Native keyring support was removed in v2. Use a third-party keyring CLI (pass, secret-tool, gopass…) as the command.
How is OAuth 2.0 handled?
Himalaya runs no OAuth flow of its own. Use ortie, or any other token broker, to obtain an access token, then plug it in as a command printing that token on stdout.
For JMAP, point jmap.auth.bearer.token.command at the broker. For IMAP and SMTP, route the bearer through a SASL mechanism taking a command-sourced password.
How to debug Himalaya?
Use --log-level <level> (alias --log) where <level> is one of off, error, warn, info, debug, trace:
himalaya --log trace mailbox listThe RUST_LOG environment variable is consulted when --log is not passed, and supports per-target filters (see the env_logger documentation). RUST_BACKTRACE=1 enables full error backtraces.
Logs are written to stderr, so they can be redirected easily to a file:
himalaya --log trace mailbox list 2>/tmp/himalaya.logYou can also send logs straight to a file via --log-file <path>:
himalaya --log trace --log-file /tmp/himalaya.log mailbox listWhat does the exit code mean?
0 is a success and 1 a failure, printed on stdout as the failure object under --json, its code naming it when a caller can act on it. 2 is a command line Himalaya refuses (an unknown flag, a missing argument, a bad value): clap's message goes to stderr, or, with --json, the failure object coded usage-invalid to stdout. 3 means the command printed its result without fully succeeding: a result whose errors is not empty (a flag add or a message move given an id the mailbox does not hold, an envelope listing meeting a message it cannot read), an account check with a failed backend, or a protocol command whose server refused (an IMAP NO or BAD, an SMTP 4xx or 5xx, a ManageSieve NO or BYE).
How to read the text output from a script?
Every list prints one item per line, its cells two spaces apart with no header row, an empty cell as - and the free text (a subject, a name) last, under a header naming the account, what it lists and, for a paged list, the Page: it holds, a blank line away. An envelope list prints the id, four flag columns (* unread, R answered, ! flagged, @ attachment), the date, the senders and the subject; so does every other list of messages. A record prints one Label: value line per field. Nothing is coloured, bordered, truncated or sized to the terminal. For anything sturdier than grep or awk, use --json.
This project is licensed under either of:
- 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:

