hermes-agent/website/docs/user-guide/skills/bundled/email/email-himalaya.md
treatux 2a1ec15a6f docs(website): regenerate the skill docs from the shipped skill tree
website/scripts/generate-skill-docs.py is the documented source of both catalogs
and of the per-skill pages, but nothing compares its output with what is
committed, so the committed copies drifted:

- optional-skills-catalog.md was missing agent-merge-conflict-arbiter and listed
  pr-lens under blockchain (it lives in software-development);
- skills-catalog.md still listed merge-reconciler, which #98539 moved out of the
  bundled set;
- 196 pages and both catalogs carried Windows path separators — in the Path
  column and inside GitHub blob links, where a backslash is a broken URL.

This commit is the generator's output (re-running it on this branch is a no-op),
plus the orphan page #98539 left behind for merge-reconciler: no skill backs it,
its catalog row is gone, and no page links to it.

tests/skills/test_skill_docs_contract.py is the guard: the next skill that ships
without a catalog row, or a page regenerated on Windows, fails there instead of
on the published page.
2026-09-20 12:54:07 -07:00

7.6 KiB

title sidebar_label description
Himalaya — Himalaya CLI: IMAP/SMTP email from terminal Himalaya Himalaya CLI: IMAP/SMTP email from terminal

{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Himalaya

Himalaya CLI: IMAP/SMTP email from terminal.

Skill metadata

Source Bundled (installed by default)
Path skills/email/himalaya
Version 1.1.0
Author community
License MIT
Platforms linux, macos, windows
Tags Email, IMAP, SMTP, CLI, Communication

Reference: full SKILL.md

:::info The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. :::

Himalaya Email CLI

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

This skill is separate from the Hermes Email gateway adapter. The gateway adapter lets people email the agent and uses Hermes' built-in IMAP/SMTP adapter; this skill lets the agent operate a mailbox from terminal tools and requires the external himalaya CLI.

References

  • references/configuration.md (config file setup + IMAP/SMTP authentication)
  • references/message-composition.md (MML syntax for composing emails)

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

# 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

Run the interactive wizard to set up an account:

himalaya account configure

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

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

backend.type = "imap"
backend.host = "imap.example.com"
backend.port = 993
backend.encryption.type = "tls"
backend.login = "[email protected]"
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 = "[email protected]"
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 [email protected] 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: [email protected]
To: [email protected]
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: [email protected]/' | himalaya template send

Write a New Email

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

cat << 'EOF' | himalaya template send
From: [email protected]
To: [email protected]
Subject: Test Message

Hello from Himalaya!
EOF

Or with headers flag:

himalaya message write -H "To:[email protected]" -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 <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.