Himalaya CLI Email Skill for Hermes Agent: Setup and Usage

Himalaya is a terminal-based email client that works over IMAP and SMTP. This skill lets a Hermes Agent read, send, and manage emails from the command line. You would reach for this when you want the agent to operate a mailbox directly, without routing through a separate gateway adapter.

What it does

Himalaya gives the agent a full email client in the terminal. It can list folders, read messages, search, move, copy, delete, and send emails. The agent can compose replies or new messages by piping text into the tool. All operations work with IMAP for receiving and SMTP for sending. The skill is separate from the Hermes Email gateway adapter, which lets people email the agent. This skill lets the agent itself work with a mailbox.

Before you start

You need three things before using this skill:

The Himalaya CLI installed on the system (himalaya --version to check)
A configuration file at ~/.config/himalaya/config.toml
IMAP and SMTP credentials, with the password stored securely (not in plain text in the config)

Installation

Install the Himalaya CLI using one of these 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 Setup

The easiest way to set up an account is to run the interactive wizard:

himalaya account configure

This wizard requires interactive input. When calling it from Hermes, use PTY mode: terminal(command="himalaya account configure", pty=true).

You can also create the config file manually. Here is a complete example:

[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"

Heads up on the alias syntax. Pre-v1.2.0 docs used a [accounts.NAME.folder.alias] sub-section (singular alias). v1.2.0 silently ignores that form, TOML parses fine, but the alias resolver never reads it, so every lookup falls through to the canonical name. On Gmail this means save-to-Sent fails after SMTP delivery succeeds, and himalaya message send exits non-zero. Any caller (agent, script, user) that retries on that exit code will re-run the entire send, including SMTP, producing duplicate emails to recipients. Always use folder.aliases.X (plural, dotted keys, directly under [accounts.NAME]).

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
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 john@example.com 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: you@example.com
To: sender@example.com
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: newrecipient@example.com/' | himalaya template send

Write a New Email

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

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

Hello from Himalaya!
EOF

Or with 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. This works with pty=true + background mode, but piping is simpler and more reliable.

Move/Copy Emails

Move to folder (target folder comes first, then the message ID):

himalaya message move "Archive" 42

Copy to folder (target folder comes first, then the message ID):

himalaya message copy "Important" 42

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 --downloads-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

Tips

Use himalaya --help or himalaya --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.

When not to use it

If you want people to be able to email the agent directly, use the Hermes Email gateway adapter instead. That adapter uses Hermes' built-in IMAP/SMTP adapter and does not require the external Himalaya CLI. This skill is for when the agent itself needs to operate a mailbox.

Limits and gotchas

The folder alias syntax changed in v1.2.0. The old [accounts.NAME.folder.alias] form is silently ignored. Always use folder.aliases.X (plural, dotted keys) directly under [accounts.NAME]. On Gmail, getting this wrong causes save-to-Sent to fail after SMTP delivery, and any retry logic will send duplicate emails.
Message IDs are relative to the current folder. If you change folders, the IDs change. Re-list after a folder change.
The interactive wizard (himalaya account configure) needs a PTY. From Hermes, use terminal(command="himalaya account configure", pty=true).
Interactive $EDITOR mode for composing works with pty=true + background + process tool, but piping is simpler and more reliable.

What pairs with this

references/configuration.md, detailed config file setup and IMAP/SMTP authentication
references/message-composition.md, MML syntax for composing rich emails with attachments