Himalaya

Himalaya — CLI Email Client

Quick Start

# List recent envelopes (INBOX)
himalaya envelope list -a hyperspace

# Read a message
himalaya message read -a hyperspace 4658

# Send a message (raw RFC 5322)
cat <<'EOF' | himalaya message send -a hyperspace
From: [email protected]
To: [email protected]
Subject: Test Subject

Message body here.
EOF

# Check account health
himalaya account doctor hyperspace

Core Patterns

1. Account Configuration

Config file: ~/.config/himalaya/config.toml

Each account requires IMAP backend + SMTP send backend. See references/config-reference.md for full schema.

[accounts.hyperspace]
default = true
display-name = "Seyi"
email = "[email protected]"
message.send.save-copy = false          # Disable if server's IMAP APPEND is quirky

[accounts.hyperspace.backend]
type = "imap"
host = "mail.hyperspace.ng"
port = 993
login = "[email protected]"

[accounts.hyperspace.backend.auth]
type = "password"
raw = "YOUR_PASSWORD"

[accounts.hyperspace.backend.encryption]
type = "tls"
starttls = false

[accounts.hyperspace.message.send.backend]
type = "smtp"
host = "mail.hyperspace.ng"
port = 465
login = "[email protected]"

[accounts.hyperspace.message.send.backend.auth]
type = "password"
raw = "YOUR_PASSWORD"

[accounts.hyperspace.message.send.backend.encryption]
type = "tls"
starttls = false

[accounts.hyperspace.folder.alias]
drafts = "Drafts"
trash = "Trash"
junk = "Junk"

2. Listing Envelopes

# Default folder (INBOX), page size 10
himalaya envelope list -a hyperspace

# Specific folder
himalaya envelope list -a hyperspace --folder Sent

# Page through results
himalaya envelope list -a hyperspace --page-size 20

# JSON output for scripting
himalaya envelope list -a hyperspace -o json

3. Reading Messages

# Read full message (headers + body)
himalaya message read -a hyperspace 4658

# Read only body text
himalaya message read -a hyperspace 4658 --no-headers

# JSON output
himalaya message read -a hyperspace 4658 -o json

4. Sending Messages

Himalaya accepts raw RFC 5322 format. It does NOT have --to, --subject flags.

# Simple plain text
cat <<'EOF' | himalaya message send -a hyperspace
From: [email protected]
To: [email protected]
Subject: Hello

Body text here.
EOF

# HTML email
cat <<'EOF' | himalaya message send -a hyperspace
From: [email protected]
To: [email protected]
Subject: HTML Email
Content-Type: text/html; charset=utf-8

<h1>Hello</h1><p>This is <b>HTML</b>.</p>
EOF

# CC and Reply-To
cat <<'EOF' | himalaya message send -a hyperspace
From: [email protected]
To: [email protected]
Cc: [email protected]
Reply-To: [email protected]
Subject: With CC and Reply-To

Body text.
EOF

5. Managing Flags

# Mark as read (add Seen flag)
himalaya flag add -a hyperspace 4658 seen

# Mark as unread (remove Seen flag)
himalaya flag remove -a hyperspace 4658 seen

# Star a message
himalaya flag add -a hyperspace 4658 flagged

# Delete a message (add Deleted flag + expunge)
himalaya flag add -a hyperspace 4658 deleted

6. Folder Operations

# List all folders
himalaya folder list -a hyperspace

# Create a new folder
himalaya folder add -a hyperspace "Archive"

# Delete a folder
himalaya folder delete -a hyperspace "Archive"

Important Notes

• message send takes raw RFC 5322 on stdin — no --to, --subject, or --body flags.
• save-copy = false — set this if the server's IMAP APPEND to Sent folder causes "unexpected tag" errors (common with cPanel/Dovecot).
• Password auth type is password, not passwd or plain.
• Encryption types: tls (IMAPS/SMTPS on dedicated port) or starttls (STARTTLS on plain port).
• Auth mechanisms: password (auto-selects PLAIN/LOGIN) or oauth2 (for Gmail/Outlook).
• Use -o json for scripting; -o plain (default) for human output.
• Use --debug or --trace for troubleshooting connection issues.

References

• references/cli-reference.md — Complete command reference for all himalaya subcommands
• references/config-reference.md — Full TOML configuration schema, multi-account setup, OAuth2, and keyring
• references/common-workflows.md — Search/filter, attachments, threading, batch operations, and scripting patterns