himalaya

Himalaya Email Workflows

CLI email client for IMAP/Maildir/Notmuch backends.

Command Structure

All commands follow: himalaya <resource> <action>

Resource	Actions
envelope	list, thread
message	read, write, reply, forward, copy, move, delete
folder	list, add, delete, purge, expunge
flag	add, set, remove
attachment	download
template	write, reply, forward, save, send

Quick Reference

Inbox Triage

Important: Flags must come BEFORE the query filter (if any).

# List unread/new messages (use --output json for cleaner parsing)
himalaya envelope list --output json 'not flag Seen'

# List all envelopes (default: INBOX)
himalaya envelope list --output json

# List with specific folder and page
himalaya envelope list -f Archive -p 2

# Read message by ID
himalaya message read 123

# Mark as seen
himalaya flag add 123 seen

# Move to folder (TARGET first, then ID)
himalaya message move Archive 123

Searching (Query DSL)

Himalaya uses its own query DSL, NOT IMAP SEARCH syntax:

# Filter by date
himalaya envelope list after 2025-01-01
himalaya envelope list before 2025-01-15
himalaya envelope list date 2025-01-10

# Filter by sender/recipient
himalaya envelope list from [email protected]
himalaya envelope list to [email protected]

# Filter by content
himalaya envelope list subject urgent
himalaya envelope list body "project update"

# Filter by flag (use 'not flag Seen' for unread)
himalaya envelope list 'not flag Seen'
himalaya envelope list flag flagged

# Combine with operators
himalaya envelope list from [email protected] and subject urgent
himalaya envelope list "from alice or from bob"
himalaya envelope list not flag seen

# Sort results
himalaya envelope list order by date desc
himalaya envelope list subject report order by from asc

Composing

# New message (opens $EDITOR)
himalaya message write

# Reply / Reply-all
himalaya message reply 123
himalaya message reply 123 --all

# Forward
himalaya message forward 456

Attachments (MML Syntax)

Attachments use MML in the message body, not command-line flags:

To: [email protected]
Subject: Files attached

Here is the document.

<#part filename=/path/to/file.pdf><#/part>

Inline image:
<#part disposition=inline filename=/path/to/image.png><#/part>

Organizing

# List folders
himalaya folder list

# Move message(s) - TARGET folder comes first, then IDs
himalaya message move Archive 123 456

# Copy message(s) - TARGET folder comes first, then IDs
himalaya message copy Backup 123

# Delete (marks as deleted)
himalaya message delete 123

# Expunge (permanent delete)
himalaya folder expunge INBOX

Scripting

# JSON output for parsing
himalaya envelope list --output json
himalaya envelope list --output json | jq '.[].id'

# Specific account
himalaya envelope list -a work

# Combine for automation
himalaya envelope list --output json 'not flag Seen' | jq -r '.[].id' | while read id
    himalaya message read $id
end

Common Flags

Flag	Description
-a, --account <NAME>	Use specific account
-f, --folder <NAME>	Target folder (default: INBOX)
-o, --output <FORMAT>	plain or json (prefer json for scripting/AI parsing)
-p, --page <N>	Page number (starts at 1)
-s, --page-size <N>	Results per page

Note: Always use --output json when parsing output programmatically. Plain output includes WARN log messages that interfere with parsing. Flags must come BEFORE any query filter.

Templates (Non-Interactive)

Generate messages without opening $EDITOR:

# Generate template (stdout)
himalaya template write
himalaya template reply 123
himalaya template forward 456

# Pipe and send
echo "To: [email protected]\nSubject: Hi\n\nHello" | himalaya template send

Common Mistakes

Wrong	Right	Why
himalaya list	himalaya envelope list	Need resource prefix
himalaya read 123	himalaya message read 123	Need resource prefix
himalaya write -a file.pdf	MML <#part> in body	No -a flag exists
--query "FROM x"	from x	Himalaya DSL, not IMAP
himalaya search ...	himalaya envelope list ...	No search command
himalaya envelope list 'query' -o json	himalaya envelope list --output json 'query'	Flags must come before query
himalaya message move 123 Folder	himalaya message move Folder 123	Target folder comes first