Operates IMAP/SMTP mailboxes from the terminal with the Himalaya CLI (list, search, compose, reply, flags, attachments, JSON). Use when reading or sending mail non-interactively via himalaya. Not for Resend/React Email app integration (email) and not a Hermes inbound email gateway.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Operates IMAP/SMTP mailboxes from the terminal with the Himalaya CLI (list, search, compose, reply, flags, attachments, JSON). Use when reading or sending mail non-interactively via himalaya. Not for Resend/React Email app integration (email) and not a Hermes inbound email gateway.
Himalaya is a CLI email client that manages email from the terminal using IMAP, SMTP, Notmuch, or Sendmail backends. This skill is separate from any Hermes Email gateway adapter — it operates a mailbox directly through the external himalaya CLI.
When to Use
You need to read, list, search, move, copy, or delete emails from a terminal session.
You need to compose, reply to, or forward emails non-interactively via piped stdin.
You need to download attachments or manage message flags (seen, flagged, etc.).
You need structured JSON output from an email client for programmatic parsing.
# 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"
Load references/configuration.md when setting up a new account, troubleshooting authentication, or configuring folder aliases for non-standard providers (Gmail, Fastmail, etc.).
2. List Folders
himalaya folder list
3. 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
4. Search Emails
himalaya envelope list from john@example.com subject meeting
5. Read an Email
# Read email by ID (shows plain text)
himalaya message read 42
# Export raw MIME
himalaya message export 42 --full
6. Compose a New Email (Non-Interactive)
Always pipe via stdin from agent environments — this is the reliable path:
cat << 'EOF' | himalaya template send
From: you@example.com
To: recipient@example.com
Subject: Test Message
Hello from Himalaya!
EOF
Alternative with headers flag:
himalaya message write -H "To:recipient@example.com" -H "Subject:Test""Message body here"
Load references/message-composition.md when composing rich emails with attachments, multipart MIME, or advanced MML syntax.
7. Reply to an Email
# 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 with proper headers:
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 for agent use):
himalaya message reply 42 --all
8. Forward an Email
# Get forward template and pipe with modifications
himalaya template forward 42 | sed 's/^To:.*/To: newrecipient@example.com/' | himalaya template send
9. 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
10. Delete an Email
himalaya message delete 42
11. Manage Flags
# Add flag
himalaya flag add 42 --flag seen
# Remove flag
himalaya flag remove 42 --flag seen
12. Attachments
# Save attachments from a message
himalaya attachment download 42
# Save to specific directory
himalaya attachment download 42 --downloads-dir ~/Downloads
13. Multiple Accounts
# List accounts
himalaya account list
# Use a specific account
himalaya --account work envelope list
14. Structured Output
Most commands support --output for structured output — use json for programmatic parsing:
himalaya envelope list --output json
himalaya envelope list --output plain
15. Debugging
# Enable debug logging
RUST_LOG=debug himalaya envelope list
# Full trace with backtrace
RUST_LOG=trace RUST_BACKTRACE=1 himalaya envelope list
Pitfalls
HARD RULE: Folder Alias Syntax (v1.2.0+)
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]):
himalaya message write and himalaya message reply without piped input open $EDITOR. This works with pty=true + background + process tool, but piping via stdin is simpler and more reliable in agent environments. Always prefer cat << 'EOF' | himalaya template send over interactive editor mode.
Message IDs Are Folder-Relative
Message IDs are relative to the current folder. Always re-list envelopes after folder changes before operating on a message by ID.
The wizard requires interactive input — use PTY mode: terminal(command="himalaya account configure", pty=true). In non-interactive agent environments, create config.toml manually instead.
Password Storage
Never hardcode passwords in config.toml. Use pass, system keyring, or a command that outputs the password via backend.auth.cmd.
Verification
Verify installation:
himalaya --version
Expected output: himalaya 1.x.x
Verify configuration is loaded:
himalaya account list
Expected: lists configured accounts with the default account marked.
Verify IMAP connectivity:
himalaya envelope list --page 1 --page-size 5
Expected: shows up to 5 envelopes from INBOX.
Verify SMTP by sending a test to yourself:
cat << 'EOF' | himalaya template send
From: you@example.com
To: you@example.com
Subject: Himalaya Test
This is a test message from Himalaya CLI.
EOF
Expected: command exits 0, message appears in INBOX.
Verify folder aliases (critical for Gmail):
himalaya folder list --output json
Confirm that aliased folders resolve correctly. Then send a test email and verify it appears in the Sent folder — if himalaya message send exits non-zero after successful SMTP delivery, your alias syntax is wrong (see Pitfalls).
Related Skills
Hermes Email Gateway Adapter — for receiving emails addressed to the agent via Hermes' built-in IMAP/SMTP adapter (separate from this CLI skill).
