himalaya

1---2name: himalaya3description: "Himalaya CLI: IMAP/SMTP email from terminal."4version: 1.1.05author: community6license: MIT7platforms: [linux, macos, windows]8metadata:9  hermes:10    tags: [Email, IMAP, SMTP, CLI, Communication]11    homepage: https://github.com/pimalaya/himalaya12prerequisites:13  commands: [himalaya]14---15 16# Himalaya Email CLI17 18Himalaya is a CLI email client that lets you manage emails from the terminal using IMAP, SMTP, Notmuch, or Sendmail backends.19 20This skill is separate from the Hermes Email gateway adapter. The gateway21adapter lets people email the agent and uses Hermes' built-in IMAP/SMTP22adapter; this skill lets the agent operate a mailbox from terminal tools and23requires the external `himalaya` CLI.24 25## References26 27- `references/configuration.md` (config file setup + IMAP/SMTP authentication)28- `references/message-composition.md` (MML syntax for composing emails)29 30## Prerequisites31 321. Himalaya CLI installed (`himalaya --version` to verify)332. A configuration file at `~/.config/himalaya/config.toml`343. IMAP/SMTP credentials configured (password stored securely)35 36### Installation37 38```bash39# Pre-built binary (Linux/macOS — recommended)40curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | PREFIX=~/.local sh41 42# macOS via Homebrew43brew install himalaya44 45# Or via cargo (any platform with Rust)46cargo install himalaya --locked47```48 49## Configuration Setup50 51Run the interactive wizard to set up an account:52 53```bash54himalaya account configure55```56 57Or create `~/.config/himalaya/config.toml` manually:58 59```toml60[accounts.personal]61email = "you@example.com"62display-name = "Your Name"63default = true64 65backend.type = "imap"66backend.host = "imap.example.com"67backend.port = 99368backend.encryption.type = "tls"69backend.login = "you@example.com"70backend.auth.type = "password"71backend.auth.cmd = "pass show email/imap"  # or use keyring72 73message.send.backend.type = "smtp"74message.send.backend.host = "smtp.example.com"75message.send.backend.port = 58776message.send.backend.encryption.type = "start-tls"77message.send.backend.login = "you@example.com"78message.send.backend.auth.type = "password"79message.send.backend.auth.cmd = "pass show email/smtp"80 81# Folder aliases (himalaya v1.2.0+ syntax). Required whenever the82# server's folder names don't match himalaya's canonical names83# (inbox/sent/drafts/trash). Gmail is the common case — see84# `references/configuration.md` for the `[Gmail]/Sent Mail` mapping.85folder.aliases.inbox = "INBOX"86folder.aliases.sent = "Sent"87folder.aliases.drafts = "Drafts"88folder.aliases.trash = "Trash"89```90 91> **Heads up on the alias syntax.** Pre-v1.2.0 docs used a92> `[accounts.NAME.folder.alias]` sub-section (singular `alias`).93> v1.2.0 silently ignores that form — TOML parses fine, but the94> alias resolver never reads it, so every lookup falls through to95> the canonical name. On Gmail this means save-to-Sent fails *after*96> SMTP delivery succeeds, and `himalaya message send` exits non-zero.97> Any caller (agent, script, user) that retries on that exit code98> will re-run the entire send — including SMTP — producing duplicate99> emails to recipients. Always use `folder.aliases.X` (plural, dotted100> keys, directly under `[accounts.NAME]`).101 102## Hermes Integration Notes103 104- **Reading, listing, searching, moving, deleting** all work directly through the terminal tool105- **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 commands106- Use `--output json` for structured output that's easier to parse programmatically107- The `himalaya account configure` wizard requires interactive input — use PTY mode: `terminal(command="himalaya account configure", pty=true)`108 109## Common Operations110 111### List Folders112 113```bash114himalaya folder list115```116 117### List Emails118 119List emails in INBOX (default):120 121```bash122himalaya envelope list123```124 125List emails in a specific folder:126 127```bash128himalaya envelope list --folder "Sent"129```130 131List with pagination:132 133```bash134himalaya envelope list --page 1 --page-size 20135```136 137### Search Emails138 139```bash140himalaya envelope list from john@example.com subject meeting141```142 143### Read an Email144 145Read email by ID (shows plain text):146 147```bash148himalaya message read 42149```150 151Export raw MIME:152 153```bash154himalaya message export 42 --full155```156 157### Reply to an Email158 159To reply non-interactively from Hermes, read the original message, compose a reply, and pipe it:160 161```bash162# Get the reply template, edit it, and send163himalaya template reply 42 | sed 's/^$/\nYour reply text here\n/' | himalaya template send164```165 166Or build the reply manually:167 168```bash169cat << 'EOF' | himalaya template send170From: you@example.com171To: sender@example.com172Subject: Re: Original Subject173In-Reply-To: <original-message-id>174 175Your reply here.176EOF177```178 179Reply-all (interactive — needs $EDITOR, use template approach above instead):180 181```bash182himalaya message reply 42 --all183```184 185### Forward an Email186 187```bash188# Get forward template and pipe with modifications189himalaya template forward 42 | sed 's/^To:.*/To: newrecipient@example.com/' | himalaya template send190```191 192### Write a New Email193 194**Non-interactive (use this from Hermes)** — pipe the message via stdin:195 196```bash197cat << 'EOF' | himalaya template send198From: you@example.com199To: recipient@example.com200Subject: Test Message201 202Hello from Himalaya!203EOF204```205 206Or with headers flag:207 208```bash209himalaya message write -H "To:recipient@example.com" -H "Subject:Test" "Message body here"210```211 212Note: `himalaya message write` without piped input opens `$EDITOR`. This works with `pty=true` + background mode, but piping is simpler and more reliable.213 214### Move/Copy Emails215 216Move to folder (target folder comes first, then the message ID):217 218```bash219himalaya message move "Archive" 42220```221 222Copy to folder (target folder comes first, then the message ID):223 224```bash225himalaya message copy "Important" 42226```227 228### Delete an Email229 230```bash231himalaya message delete 42232```233 234### Manage Flags235 236Add flag:237 238```bash239himalaya flag add 42 --flag seen240```241 242Remove flag:243 244```bash245himalaya flag remove 42 --flag seen246```247 248## Multiple Accounts249 250List accounts:251 252```bash253himalaya account list254```255 256Use a specific account:257 258```bash259himalaya --account work envelope list260```261 262## Attachments263 264Save attachments from a message:265 266```bash267himalaya attachment download 42268```269 270Save to specific directory:271 272```bash273himalaya attachment download 42 --downloads-dir ~/Downloads274```275 276## Output Formats277 278Most commands support `--output` for structured output:279 280```bash281himalaya envelope list --output json282himalaya envelope list --output plain283```284 285## Debugging286 287Enable debug logging:288 289```bash290RUST_LOG=debug himalaya envelope list291```292 293Full trace with backtrace:294 295```bash296RUST_LOG=trace RUST_BACKTRACE=1 himalaya envelope list297```298 299## Tips300 301- Use `himalaya --help` or `himalaya <command> --help` for detailed usage.302- Message IDs are relative to the current folder; re-list after folder changes.303- For composing rich emails with attachments, use MML syntax (see `references/message-composition.md`).304- Store passwords securely using `pass`, system keyring, or a command that outputs the password.305