Himalaya CLI Email Management Reference

Manage emails from the terminal using the Himalaya CLI email client. This tool operates with IMAP, SMTP, Notmuch, or Sendmail backends and is intended for non-interactive use from scripts or agents.

Prerequisites

Before using any Himalaya commands, you must have:

• The himalaya CLI installed. Verify with himalaya --version.
• A configuration file at ~/.config/himalaya/config.toml.
• IMAP and SMTP credentials configured with passwords stored securely (e.g., via pass, keyring, or an auth command).

Installation

Choose one of the following methods:

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

# macOS via Homebrew
brew install himalaya

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

Configuration

Interactive Wizard

Run the interactive configuration wizard. This requires PTY mode in Hermes:

himalaya account configure

When using Hermes, invoke it as terminal(command="himalaya account configure", pty=true).

Manual Configuration

Create ~/.config/himalaya/config.toml with account settings. Define each account under [accounts.NAME]. Below is a complete example for a personal account:

[accounts.personal]
email = "you@example.com"
display-name = "Your Name"
default = true

backend.type = "imap"
backend.host = "imap.example.com"
backend.port = 993
backend.encryption.type = "tls"
backend.login = "you@example.com"
backend.auth.type = "password"
backend.auth.cmd = "pass show email/imap"  # or use keyring

message.send.backend.type = "smtp"
message.send.backend.host = "smtp.example.com"
message.send.backend.port = 587
message.send.backend.encryption.type = "start-tls"
message.send.backend.login = "you@example.com"
message.send.backend.auth.type = "password"
message.send.backend.auth.cmd = "pass show email/smtp"

# Folder aliases (himalaya v1.2.0+ syntax). Required whenever the
# server's folder names don't match himalaya's canonical names
# (inbox/sent/drafts/trash). Gmail is the common case — see
# `references/configuration.md` for the `[Gmail]/Sent Mail` mapping.
folder.aliases.inbox = "INBOX"
folder.aliases.sent = "Sent"
folder.aliases.drafts = "Drafts"
folder.aliases.trash = "Trash"

Critical folder alias syntax: Use folder.aliases.X (plural dotted keys) directly under [accounts.NAME]. Do NOT use the pre-v1.2.0 [accounts.NAME.folder.alias] sub-section syntax (singular alias) — it is silently ignored. This causes save-to-Sent failures after SMTP delivery and duplicate emails on retry when himalaya message send exits non-zero.

Account Management

List all configured accounts:

himalaya account list

Use a specific account with the --account flag:

himalaya --account work envelope list

Folder Operations

List all folders:

himalaya folder list

Email Operations

Envelope (Email List) Operations

List emails in INBOX:

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 by sender and subject:

himalaya envelope list from john@example.com subject meeting

Message Reading

Read an email as plain text by ID:

himalaya message read 42

Export the full raw MIME of an email:

himalaya message export 42 --full

Replying to Emails

Non-Interactive Reply Using Template

Get the reply template, edit it, and send:

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

Manual Reply with Headers

Build the reply manually and pipe it:

cat << 'EOF' | himalaya template send
From: you@example.com
To: sender@example.com
Subject: Re: Original Subject
In-Reply-To: <original-message-id>

Your reply here.
EOF

Reply to All (Interactive)

This command opens $EDITOR and is not recommended for non-interactive use:

himalaya message reply 42 --all

Forwarding Emails

Get the forward template, modify it, and send:

# Get forward template and pipe with modifications
himalaya template forward 42 | sed 's/^To:.*/To: newrecipient@example.com/' | himalaya template send

Composing and Sending New Emails

Option A: Pipe Message via Stdin

cat << 'EOF' | himalaya template send
From: you@example.com
To: recipient@example.com
Subject: Test Message

Hello from Himalaya!
EOF

Option B: Use Headers Flag

himalaya message write -H "To:recipient@example.com" -H "Subject:Test" "Message body here"

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

Moving and Copying Emails

Move an email to a folder (target folder first, then message ID):

himalaya message move "Archive" 42

Copy an email to a folder:

himalaya message copy "Important" 42

Deleting Emails

himalaya message delete 42

Managing Flags

Add a flag (e.g., mark as seen):

himalaya flag add 42 --flag seen

Remove a flag:

himalaya flag remove 42 --flag seen

Downloading Attachments

Save all attachments from a message to the current directory:

himalaya attachment download 42

Save to a specific directory:

himalaya attachment download 42 --downloads-dir ~/Downloads

Output and Debugging

Structured Output

Use the --output parameter with most commands. Supported values are json and plain:

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

Using --output json is recommended for programmatic processing.

Debugging

Enable debug logging:

RUST_LOG=debug himalaya envelope list

Enable full trace with backtrace:

RUST_LOG=trace RUST_BACKTRACE=1 himalaya envelope list

Parameters Reference

Parameter	Meaning	Required
--account	Specify which account to use (e.g., work)	No (defaults to default account)
--folder	Specify folder name for envelope list	No (defaults to INBOX)
--page	Page number for pagination	No
--page-size	Number of items per page	No
--output	Output format: json or plain	No
--flag	Flag to add or remove (e.g., seen)	Yes for flag commands
--downloads-dir	Directory to save attachments	No
--full	Export full raw MIME	No
--all	Reply to all recipients	No
-H	Header for message write (e.g., To, Subject)	No (but recommended for non-interactive use)

Constraints and Caveats

• This tool requires the external himalaya CLI installed and configured; it is separate from the Hermes Email gateway adapter.
• Configuration file must be at ~/.config/himalaya/config.toml.
• IMAP/SMTP credentials must be configured with password stored securely (e.g., pass, keyring, or command).
• Folder aliases must use folder.aliases.X (plural dotted keys) directly under [accounts.NAME]. Pre-v1.2.0 [accounts.NAME.folder.alias] syntax (singular alias) is silently ignored, causing save-to-Sent failures after SMTP delivery and duplicate emails on retry.
• Message IDs are relative to the current folder; re-list after folder changes.
• Interactive commands (e.g., himalaya account configure, himalaya message write without piped input) require PTY mode in Hermes: terminal(command="...", pty=true).
• For composing rich emails with attachments, use MML syntax (see references/message-composition.md).
• Use --output json for structured output easier to parse programmatically.
• Piping input (cat << EOF | himalaya template send) is recommended for reliability over interactive $EDITOR mode.

Failure Modes

• If folder aliases use pre-v1.2.0 syntax (singular alias), save-to-Sent fails after SMTP delivery succeeds, and himalaya message send exits non-zero. Any retry on that exit code re-runs the entire send including SMTP, producing duplicate emails to recipients.
• If himalaya CLI is not installed or configured, commands will fail with 'command not found' or configuration errors.
• If IMAP/SMTP credentials are incorrect or not stored securely, authentication fails.
• If folder names do not match server's canonical names and aliases are not set, operations on those folders may fail.
• Interactive commands without PTY mode will hang or fail in non-interactive environments.

Help

For general help, run himalaya --help.