| name | email |
| description | Manage emails via Himalaya CLI. Use when the user wants to read, send, search, or organize emails. Triggers on "email", "inbox", "send email", "check mail", "reply to", "forward", or mentions of Gmail, Outlook, iCloud, Proton Mail. |
Email Management
Manage emails using Himalaya CLI - a powerful command-line email client supporting IMAP, SMTP, Maildir, and Notmuch backends.
Agent Usage (Power User Patterns)
When using this skill as an agent, run commands via execute_command. Prefer these patterns:
-
Always use --output json when you need to parse results (subject, from, id). Example:
himalaya envelope list --folder INBOX --page-size 20 --output json | jq '.[] | {id, subject, from, date}'
-
Non-interactive send: message write opens $EDITOR. For automation, pipe a full RFC-style message to himalaya template send (if available), or use a temp file:
echo -e "To: recipient@example.com\nSubject: Subject\n\nBody text" | himalaya template send
If template send is not available, use himalaya message write --to "recipient" --subject "Subject" and note that it may open an editor—check himalaya --help for your version.
-
Extract message IDs for follow-up actions: himalaya envelope list --output json | jq -r '.[].id'
-
Batch operations: Pass multiple IDs to move/delete: himalaya message move <id1> <id2> <id3> --folder "Archives"
-
Check before acting: Run himalaya account list and himalaya folder list first if the user has multiple accounts or folders.
-
Use --account <name> when the user has multiple accounts (e.g., himalaya --account work envelope list).
Prerequisites Check
Before any email operation, verify Himalaya is installed and configured:
which himalaya
himalaya account list
If not installed → Guide through Installation
If no accounts → Guide through Account Setup
Installation
pre-built binary
curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | PREFIX=~/.local sh
macOS (Homebrew)
brew install himalaya
Arch Linux
pacman -S himalaya
Cargo (Any OS)
cargo install himalaya --locked
Other Methods
Direct user to: https://github.com/pimalaya/himalaya#installation
Account Setup
Recommended approach: Use Himalaya's built-in wizard which auto-discovers settings.
Interactive Setup (Easiest)
himalaya
himalaya account configure <account-name>
The wizard will:
- Ask for email address
- Auto-discover IMAP/SMTP settings
- Prompt for password (stored securely in system keyring)
- Test the connection
Provider-Specific Notes
| Provider | Special Requirements |
|---|
| Gmail | Requires App Password or OAuth 2.0 setup |
| Outlook | Works with password or OAuth 2.0 |
| iCloud | IMAP login is username only (not full email) |
| Proton Mail | Requires Proton Bridge running locally |
💡 Tip: Many providers use the same app-specific password for both email and calendar. Store credentials in pass with consistent naming (e.g., google/app-password, icloud/app-password) to reuse them across both email and calendar skills. For multiple accounts, use a hierarchical structure (e.g., google/personal/app-password, google/work/app-password)—the / creates folders to keep things organized.
For detailed provider configs, see references/providers.md
Common Operations
List Emails
himalaya envelope list
himalaya envelope list --folder "Archives"
himalaya envelope list --account gmail
himalaya envelope list --page 2 --page-size 20
Read Email
himalaya message read <id>
himalaya message read <id> --plain
himalaya message read <id> --headers
Send Email
himalaya message write
himalaya message write --to "recipient@example.com" --subject "Hello"
himalaya message reply <id>
himalaya message reply <id> --all
Search Emails
himalaya envelope list --folder INBOX subject "meeting"
himalaya envelope list --folder INBOX from "boss@company.com"
himalaya envelope list --folder INBOX not flag seen
himalaya envelope list --folder INBOX date 2026-02-09
himalaya envelope list --folder INBOX "from client@example.com and subject invoice and not flag seen"
TODAY=$(date +%Y-%m-%d)
himalaya envelope list --folder INBOX \
| tail -n +3 \
| grep "${TODAY}" \
| wc -l
himalaya envelope list --folder INBOX not flag seen \
| tail -n +3 \
| wc -l
himalaya envelope list --folder INBOX --page 1 --page-size 10
himalaya envelope list --folder INBOX --page 1 --page-size 10 not flag seen
Manage Folders
himalaya folder list
himalaya folder create "Projects/ClientA"
himalaya message move <id> --folder "Archives"
himalaya message copy <id> --folder "Important"
Manage Flags
himalaya flag add <id> seen
himalaya flag remove <id> seen
himalaya flag add <id> flagged
himalaya message delete <id>
Switch Between Accounts
himalaya --account work envelope list
himalaya --account personal message write
Check All Accounts
himalaya account list
for account in $(himalaya account list --output json | jq -r '.[].name'); do
echo "=== $account ==="
himalaya --account "$account" envelope list --page-size 5 not flag seen
done
Output Formats
Himalaya supports JSON output for scripting:
himalaya envelope list --output json
himalaya envelope list --output json | jq '.[].subject'
Troubleshooting
Connection Issues
RUST_LOG=debug himalaya envelope list
himalaya --debug envelope list
Common Errors
| Error | Solution |
|---|
| "Account not found" | Run himalaya account configure <name> |
| "Authentication failed" | Check password/app password, regenerate if needed |
| "Connection refused" | Check IMAP/SMTP host and port settings |
| "Certificate error" | Check TLS settings in config |
Reset Configuration
Config file location: ~/.config/himalaya/config.toml (or $XDG_CONFIG_HOME/himalaya/config.toml)
cat ~/.config/himalaya/config.toml
$EDITOR ~/.config/himalaya/config.toml
himalaya account configure <name>
himalaya --config /path/to/custom/config.toml envelope list
Environment variable override:
export HIMALAYA_CONFIG=~/.config/himalaya/custom-config.toml
himalaya envelope list
Composing Emails
Himalaya uses your $EDITOR for composing. The format is:
To: recipient@example.com
Cc: other@example.com
Subject: Your subject here
Your message body here.
Adding Attachments (MML Syntax)
Searching emails
Himalaya’s search uses a positional query expression, not a --query flag.
Date filters
himalaya envelope list "after 2026-02-10"
himalaya envelope list "before 2026-02-10"
himalaya envelope list "after $(date +%Y-%m-%d)"
Other common filters
himalaya envelope list "from me@example.com"
himalaya envelope list "to someone@example.com"
himalaya envelope list "subject report"
himalaya envelope list "from me@example.com and subject report"
Quick Reference
| Task | Command |
|---|
| Check inbox | himalaya envelope list |
| Read email | himalaya message read <id> |
| Compose new | himalaya message write |
| Reply | himalaya message reply <id> |
| Search | himalaya envelope list "from me@example.com" |
| Mark read | himalaya flag add <id> seen |
| Delete | himalaya message delete <id> |
| Move | himalaya message move --folder SOURCE TARGET <id...> |