Himalaya CLI Expert

This skill makes you an instant expert on the Himalaya command-line email client. Himalaya is a stateless CLI (not a TUI) that lets users manage emails via shell commands.

When this skill applies

Use this skill for ANY task involving:

• Listing, searching, or sorting emails (himalaya envelope list|thread)
• Reading, writing, replying to, or forwarding messages (himalaya message ...)
• Managing flags (himalaya flag ...)
• Managing folders/mailboxes (himalaya folder ...)
• Message templates and attachments (himalaya template ..., himalaya attachment ...)
• Interpreting or constructing Himalaya query DSL strings

Architecture overview

Himalaya CLI is organized around nouns:

himalaya \x3Cnoun> \x3Cverb> [args...]

Key nouns:

• envelope (aliases: envelopes) — email envelopes (metadata, no body)
• message (aliases: msg, msgs, messages) — full email messages
• flag (aliases: flags) — message flags (seen, answered, flagged, deleted…)
• folder (aliases: folders, mailbox, mailboxes, mbox, mboxes) — mailboxes
• template (aliases: tpl, tpls, templates) — message templates
• attachment (aliases: attachments) — message attachments
• account (aliases: accounts) — account configuration

Global flags (available on all commands):

• --config \x3CPATH> — override config file path
• --output json / --output plain — choose output format
• --quiet, --debug, --trace — logging levels

Common per-command flags:

• -a \x3CNAME> / --account \x3CNAME> — target a specific configured account
• -f \x3CNAME> / --folder \x3CNAME> — target a specific folder

Querying emails: envelope commands

The most common operation is listing envelopes. Read the full Query DSL reference (references/query_dsl.md) whenever the user asks anything about search, filter, sort, or list queries.

Essential commands

# List all envelopes in the default folder
himalaya envelope list

# List envelopes in a specific folder, page 2, 20 per page
himalaya envelope list -f Archives.FOSS --page 2 --page-size 20

# Thread view for envelopes matching a query
himalaya envelope thread subject "product requirement"

Query DSL quick reference

A query string has the form:

[filter-query] [order by sort-query]

Filter conditions:

• date \x3Cyyyy-mm-dd> — exact date match
• before \x3Cyyyy-mm-dd> — strictly before date
• after \x3Cyyyy-mm-dd> — strictly after date
• from \x3Cpattern> — sender pattern match
• to \x3Cpattern> — recipient pattern match
• subject \x3Cpattern> — subject pattern match
• body \x3Cpattern> — body text match (slower)
• flag \x3Cflag> — flag match (e.g., seen, deleted)

Operators (precedence: not > and > or):

• not \x3Ccondition>
• \x3Ccondition> and \x3Ccondition>
• \x3Ccondition> or \x3Ccondition>

Sort query:

• order by date [asc|desc]
• order by from [asc|desc]
• order by to [asc|desc]
• order by subject [asc|desc]
• Multiple fields are allowed: order by from asc date desc

Quoting and escaping:

• Use double quotes for values containing spaces: subject "meeting notes"
• Or escape with backslash: subject meeting\ notes
• In shell, the entire query may need to be passed as a single string or joined args.

Query examples (detailed)

# Unread emails, newest first
himalaya envelope list "not flag seen order by date desc"

# From boss or CEO, sorted by date desc
himalaya envelope list "from [email protected] or from [email protected] order by date desc"

# Subject contains "周报" AND body contains "进度"
himalaya envelope list "subject 周报 and body 进度"

# Date range: after March 31 and before April 11, 2025
himalaya envelope list "after 2025-03-31 and before 2025-04-11"

# Complex grouped condition: (subject urgent OR body error) AND from ops
himalaya envelope list '(subject 紧急 or body 报错) and from [email protected]'

# Specific folder + pagination + query
himalaya envelope list -f INBOX --page 2 --page-size 20 'subject "release plan" order by date desc'

Performance tip: Prefer from, to, subject over body because body triggers a server-side full-text scan.

Reference: For the complete Query DSL specification, IMAP mapping, and compatibility notes, read references/query_dsl.md.

Writing and sending emails: message commands

Composing a new message

Himalaya uses your $EDITOR to compose messages from a template.

# Compose a new message interactively
himalaya message write

# Pre-fill headers via CLI arguments
himalaya message write --to "[email protected]" --subject "Sprint review"

# Compose using a saved template
himalaya message write --template /path/to/template.eml

Reply and forward

# Reply to message ID 42
himalaya message reply 42

# Reply-all
himalaya message reply 42 --all

# Forward message ID 42
himalaya message forward 42 --to "[email protected]"

Reading, saving, and exporting

# Read raw message content
himalaya message read 42

# Save message to local .eml file
himalaya message save 42 --path ./message42.eml

# Export message(s)
himalaya message export 42 --path ./exports/

Message template format

A template is a set of headers followed by a blank line and then the body:

From: [email protected]
To: Bob \[email protected]>
Subject: Hello from Himalaya

Hello, world!

Valid headers include: From, To, Cc, Bcc, Reply-To, Subject, Date, Message-ID, In-Reply-To.

Addresses can be:

• Plain: user@domain
• Named: Name \x3Cuser@domain>
• Quoted named: "Name" \x3Cuser@domain>
• Multiple addresses separated by commas.

Attachments

Attachments are handled via the attachment noun or MML syntax in templates.

# Download attachments from message 42
himalaya attachment download 42 --path ./downloads/

MML attachment example inside a template body:

From: [email protected]
To: [email protected]
Subject: Attaching a doc

\x3C#part filename=/path/to/file.pdf>\x3C#/part>

Managing emails: flags and folders

Flags

# Add flag(s) to envelope(s)
himalaya flag add 42,43 flagged answered

# Remove flag(s)
himalaya flag remove 42 flagged

# Set exact flags (replaces existing)
himalaya flag set 42 seen

Common flags: seen, answered, flagged, deleted, draft.

Folders

# List folders
himalaya folder list

# Add a folder
himalaya folder add MyFolder

# Delete a folder
himalaya folder delete MyFolder

# Purge deleted messages from a folder
himalaya folder purge MyFolder

# Expunge a folder
himalaya folder expunge MyFolder

Multi-account workflows

Himalaya supports multiple accounts via TOML config. Target a non-default account with -a:

himalaya envelope list -a work -f INBOX
himalaya message write -a personal --to "[email protected]"

Output format tips

• Use --output json when you need structured data for piping into jq or scripts.
• Use --output plain (default) for human-readable tables and text.

Common gotchas

1. Trailing query args: himalaya envelope list accepts the query as trailing arguments. Shell escaping matters. If the query has spaces, quote the entire query string.
2. Page numbering: --page starts at 1 (not 0).
3. Date boundaries: before 2025-04-01 excludes April 1; after 2025-04-01 also excludes April 1 (Himalaya adjusts internally by adding a day to use SENTSINCE).
4. Config location: Default is ~/.config/himalaya/config.toml. Run himalaya account configure \x3Cname> for the wizard.

External resources

• Repository: https://github.com/pimalaya/himalaya
• Query DSL reference (bundled): references/query_dsl.md