himalaya

name	himalaya
description	CLI to manage emails via IMAP/SMTP. Use himalaya to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
version	1.0.0
author	community
license	MIT
metadata	{"hermes":{"tags":["Email","IMAP","SMTP","CLI","Communication"],"homepage":"https://github.com/pimalaya/himalaya"}}
prerequisites	{"commands":["himalaya"]}

Himalaya Email CLI

Himalaya is a CLI email client that lets you manage emails from the terminal using IMAP, SMTP, Notmuch, or Sendmail backends.

References

• references/configuration.md (config file setup + IMAP/SMTP authentication)
• references/message-composition.md (MML syntax for composing emails)
• references/cron-workflow.md (cron job email automation patterns)

Prerequisites

1. Himalaya CLI installed (himalaya --version to verify)
2. A configuration file at ~/.config/himalaya/config.toml
3. IMAP/SMTP credentials configured (password stored securely)

Installation

# macOS via Homebrew (recommended on macOS)
brew install himalaya

# Pre-built binary (Linux/macOS)
curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | PREFIX=~/.local sh

# Or via cargo (any platform with Rust)
cargo install himalaya --locked

Configuration Setup

Gmail Quick Start (with macOS Keychain — recommended for macOS users)

This uses Gmail App Passwords (no Google Cloud project needed). User must first:

1. Enable 2-Step Verification at https://myaccount.google.com/security
2. Generate an App Password at https://myaccount.google.com/apppasswords (select Mail + Mac)
3. Provide the 16-char password

Store the password in macOS Keychain (one entry for IMAP, one for SMTP):

security add-generic-password -a "[e-mail]" -s "himalaya-imap" -w "THE_16_CHAR_APP_PASSWORD"
security add-generic-password -a "[e-mail]" -s "himalaya-smtp" -w "THE_16_CHAR_APP_PASSWORD"

Then create ~/.config/himalaya/config.toml:

[accounts.personal]
email = "[e-mail]"
display-name = "Your Name"
default = true

backend.type = "imap"
backend.host = "imap.gmail.com"
backend.port = 993
backend.encryption.type = "tls"
backend.login = "[e-mail]"
backend.auth.type = "password"
backend.auth.cmd = "security find-generic-password -a [e-mail] -s himalaya-imap -w"

[accounts.personal.message.send]
backend.type = "smtp"
backend.host = "smtp.gmail.com"
backend.port = 587
backend.encryption.type = "start-tls"
backend.login = "[e-mail]"
backend.auth.type = "password"
backend.auth.cmd = "security find-generic-password -a [e-mail] -s himalaya-smtp -w"

Verify:

himalaya envelope list --page 1 --page-size 5

Note: If listing fails with peer closed connection without sending TLS close_notify, wait a moment and retry — Gmail's IMAP sometimes needs a brief cooldown after initial auth.

Gmail Folder Aliases (recommended)

Gmail uses non-standard folder names ([Gmail]/Sent Mail instead of Sent). Without alias mapping, every send will error trying to save to the Sent folder. Add this to ~/.config/himalaya/config.toml:

[accounts.personal.folder.alias]
sent = "[Gmail]/Sent Mail"
drafts = "[Gmail]/Drafts"
trash = "[Gmail]/Trash"

Sending via template send or message send (Gmail detail)

Two commands work for non-interactive sending:

• cat << EOF | himalaya template send — original pattern
• echo "$MSG" | himalaya message send — alternative, same SMTP behavior

Both try to save a copy to the IMAP Sent folder. If Gmail returns Folder doesn't exist (Failure), the email is still sent successfully — Gmail auto-saves sent mail on the server side. Fix this permanently with the folder aliases above.

Generic (non-Gmail) setup

Run the interactive wizard:

himalaya account configure

Or create ~/.config/himalaya/config.toml manually:

[accounts.personal]
email = "[e-mail]"
display-name = "Your Name"
default = true

backend.type = "imap"
backend.host = "imap.example.com"
backend.port = 993
backend.encryption.type = "tls"
backend.login = "[e-mail]"
backend.auth.type = "password"
backend.auth.cmd = "pass show email/imap"  # or use keyring

[accounts.personal.message.send]
backend.type = "smtp"
backend.host = "smtp.example.com"
backend.port = 587
backend.encryption.type = "start-tls"
backend.login = "[e-mail]"
backend.auth.type = "password"
backend.auth.cmd = "pass show email/smtp"

Hermes Integration Notes

• Reading, listing, searching, moving, deleting all work directly through the terminal tool
• Composing/replying/forwarding — piped input (cat << EOF | himalaya template send) is recommended for reliability. Interactive $EDITOR mode works with pty=true + background + process tool, but requires knowing the editor and its commands
• Use --output json for structured output that's easier to parse programmatically
• Proxy support (confirmed 2026-06-18): himalaya works through HTTP CONNECT proxies (e.g., xray/v2rayN on 127.0.0.1:10808) via system-level proxy environment variables. Despite historical claims that "himalaya has no proxy support", it works reliably as a third fallback when custom SMTP proxy scripts fail. See smtp-via-proxy skill P20 for the full fallback chain.
• The himalaya account configure wizard requires interactive input — use PTY mode: terminal(command="himalaya account configure", pty=true)

Common Operations

List Folders

himalaya folder list

List Emails

List emails in INBOX (default):

himalaya envelope list

List emails in a specific folder:

himalaya envelope list --folder "Sent"

List with pagination:

himalaya envelope list --page 1 --page-size 20

Search Emails

himalaya envelope list from [e-mail] subject meeting

Read an Email

Read email by ID (shows plain text):

himalaya message read 42

Export raw MIME:

himalaya message export 42 --full

Reply to an Email

To reply non-interactively from Hermes, read the original message, compose a reply, and pipe it:

# Get the reply template, edit it, and send
himalaya template reply 42 | sed 's/^$/\nYour reply text here\n/' | himalaya template send

Or build the reply manually:

cat << 'EOF' | himalaya template send
From: [e-mail]
To: [e-mail]
Subject: Re: Original Subject
In-Reply-To: <original-message-id>

Your reply here.
EOF

Reply-all (interactive — needs $EDITOR, use template approach above instead):

himalaya message reply 42 --all

Forward an Email

# Get forward template and pipe with modifications
himalaya template forward 42 | sed 's/^To:.*/To: [e-mail]/' | himalaya template send

Write a New Email

Non-interactive (use this from Hermes) — pipe the message via stdin:

cat << 'EOF' | himalaya template send
From: [e-mail]
To: [e-mail]
Subject: Test Message

Hello from Himalaya!
EOF

Or with headers flag:

himalaya message write -H "To:[e-mail]" -H "Subject:Test" "Message body here"

Note: himalaya message write without piped input opens $EDITOR. This works with pty=true + background mode, but piping is simpler and more reliable.

Move/Copy Emails

Move to folder:

himalaya message move 42 "Archive"

Copy to folder:

himalaya message copy 42 "Important"

Delete an Email

himalaya message delete 42

Manage Flags

Add flag:

himalaya flag add 42 --flag seen

Remove flag:

himalaya flag remove 42 --flag seen

Multiple Accounts

List accounts:

himalaya account list

Use a specific account:

himalaya --account work envelope list

Attachments

Save attachments from a message:

himalaya attachment download 42

Save to specific directory:

himalaya attachment download 42 --dir ~/Downloads

Output Formats

Most commands support --output for structured output:

himalaya envelope list --output json
himalaya envelope list --output plain

Debugging

Enable debug logging:

RUST_LOG=debug himalaya envelope list

Full trace with backtrace:

RUST_LOG=trace RUST_BACKTRACE=1 himalaya envelope list

Known Pitfalls

Pitfall	Description
subject filter timeout (60s)	himalaya envelope list ... subject "query" can timeout at 60s on Gmail IMAP. Workaround: Use himalaya envelope list without subject filter, or use Python imaplib directly for filtered searches.
No SOCKS5 proxy support	himalaya CLI does NOT support SOCKS5 proxy — ignores all_proxy env var. If direct network is blocked, use Python imaplib with PySocks monkey-patch (socks.set_default_proxy(SOCKS5, '127.0.0.1', 10808)).
MIME Q-encoding in headers	IMAP headers use RFC 2047 Q/B encoding for non-ASCII chars (emojis, accented chars). himalaya message read decodes these automatically, but himalaya envelope list output may show raw encoded subjects in the terminal table. Use Python email.header.decode_header() for programmatic subject matching.

Tips

• Use himalaya --help or himalaya <command> --help for detailed usage.
• Message IDs are relative to the current folder; re-list after folder changes.
• For composing rich emails with attachments, use MML syntax (see references/message-composition.md).
• Store passwords securely using pass, system keyring, or a command that outputs the password.