Himalaya

Operational Steps

1. 确认输入参数完整
2. 执行核心操作（参考本目录下的 scripts/ 或 references/）
3. 验证输出符合契约
4. 保存结果并报告

Pitfalls

-

-

Verification

-

-

-

-

1. 2. 3.

IO_CONTRACT

• input: command: str, args: list[str] — 用户请求描述、上下文信息
• output: output: str — 命令行输出

对应原则：P2（机械原子暴露输入输出规范）

Himalaya Email CLI

Himalaya is a CLI email client that lets you manage emails from the terminal using IMAP, SMTP, Notmuch, or Sendmail backends.

References

• references/configuration.md (config file setup + IMAP/SMTP authentication)
• references/message-composition.md (MML syntax for composing emails)

Prerequisites

1. Himalaya CLI installed (himalaya --version to verify)
2. A configuration file at ~/.config/himalaya/config.toml
3. IMAP/SMTP credentials configured (password stored securely)

Installation

# Pre-built binary (Linux/macOS — recommended)
curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | PREFIX=~/.local sh

# macOS via Homebrew
brew install himalaya

# Or via cargo (any platform with Rust)
cargo install himalaya --locked

Configuration Setup

Run the interactive wizard to set up an account:

himalaya account configure

Or create ~/.config/himalaya/config.toml manually:

[accounts.personal]
email = "you@example.com"
display-name = "Your Name"
default = true

backend.type = "imap"
backend.host = "imap.example.com"
backend.port = 993
backend.encryption.type = "tls"
backend.login = "you@example.com"
backend.auth.type = "password"
backend.auth.cmd = "pass show email/imap"  # or use keyring

message.send.backend.type = "smtp"
message.send.backend.host = "smtp.example.com"
message.send.backend.port = 587
message.send.backend.encryption.type = "start-tls"
message.send.backend.login = "you@example.com"
message.send.backend.auth.type = "password"
message.send.backend.auth.cmd = "pass show email/smtp"

# 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"

Heads up on the alias syntax. 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]).

Hermes Integration Notes

• Reading, listing, searching, moving, deleting all work directly through the terminal tool
• Composing/replying/forwarding — piped input (cat << EOF | himalaya template send) is recommended for reliability. Interactive $EDITOR mode works with pty=true + background + process tool, but requires knowing the editor and its commands
• Use --output json for structured output that's easier to parse programmatically
• The himalaya account configure wizard requires interactive input — use PTY mode: terminal(command="himalaya account configure", pty=true)

Common Operations

List Folders

himalaya folder list

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

Search Emails

himalaya envelope list from john@example.com subject meeting

Read an Email

Read email by ID (shows plain text):

himalaya message read 42

Export raw MIME:

himalaya message export 42 --full

Reply to an Email

To reply non-interactively from Hermes, read the original message, compose a reply, and pipe it:

# 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:

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):

himalaya message reply 42 --all

Forward an Email

# Get forward template and pipe with modifications
himalaya template forward 42 | sed 's/^To:.*/To: newrecipient@example.com/' | himalaya template send

Write a New Email

Non-interactive (use this from Hermes) — pipe the message via stdin:

cat << 'EOF' | himalaya template send
From: you@example.com
To: recipient@example.com
Subject: Test Message

Hello from Himalaya!
EOF

Or with headers flag:

himalaya message write -H "To:recipient@example.com" -H "Subject:Test" "Message body here"

Note: himalaya message write without piped input opens $EDITOR. This works with pty=true + background mode, but piping is simpler and more reliable.

Move/Copy Emails

Move to folder:

himalaya message move 42 "Archive"

Copy to folder:

himalaya message copy 42 "Important"

Delete an Email

himalaya message delete 42

Manage Flags

Add flag:

himalaya flag add 42 --flag seen

Remove flag:

himalaya flag remove 42 --flag seen

Multiple Accounts

List accounts:

himalaya account list

Use a specific account:

himalaya --account work envelope list

Attachments

Save attachments from a message:

himalaya attachment download 42

Save to specific directory:

himalaya attachment download 42 --dir ~/Downloads

Output Formats

Most commands support --output for structured output:

himalaya envelope list --output json
himalaya envelope list --output plain

Debugging

Enable debug logging:

RUST_LOG=debug himalaya envelope list

Full trace with backtrace:

RUST_LOG=trace RUST_BACKTRACE=1 himalaya envelope list

Tips

• Use himalaya --help or himalaya <command> --help for detailed usage.
• Message IDs are relative to the current folder; re-list after folder changes.
• For composing rich emails with attachments, use MML syntax (see references/message-composition.md).
• Store passwords securely using pass, system keyring, or a command that outputs the password.

验证清单 · VERIFICATION

• himalaya --version 可用，且 ~/.config/himalaya/config.toml 存在并配置了 IMAP/SMTP 凭据（密码经 pass/keyring，非明文）
• 发送/回复/转发走管道输入（cat << EOF | himalaya template send），未依赖 $EDITOR 交互模式（交互向导用 pty=true）
• 程序化解析邮件列表/状态时添加了 --output json 参数
• Gmail 等非标准文件夹名的服务器使用了 folder.aliases.X（复数点分键）语法，未使用 v1.2.0 已废弃的 alias 子节
• 发送命令退出码非零时，先检查是否因别名配置错误导致保存失败，未盲目重试 SMTP（防止产生重复邮件）
• 异常场景下使用 RUST_LOG=debug / RUST_LOG=trace 定位问题，且失败时有明确的错误信息

约束规则 · RULES

1. 输入约束: 参数类型、范围、格式必须校验
2. 输出约束: 返回值结构、编码、命名必须一致
3. 异常约束: 错误信息必须包含上下文和恢复建议
4. 安全约束: 不执行未验证的任意代码，不暴露内部状态

Golden 集合 · GOLDEN SET

• Golden Input: 标准输入样本（覆盖正常路径）
• Golden Output: 预期输出（精确匹配或格式校验）
• Golden Error: 预期错误信息（覆盖失败路径）

Golden 集合是测试的单一真理来源。所有改进必须通过 golden 测试。

违反规则的操作视为不安全，必须拒绝或隔离。

每项验证必须可执行、可记录、可复现。验证失败时记录原因和修复。

Himalaya

Genes (策略基因)

紧凑策略表示。条件→策略。需要深度时参考完整文档。

• [HIMA-001] 服务器文件夹名称与标准名称不匹配 (如 Gmail) → 必须使用 folder.aliases.X (复数点分键) 语法配置别名，避免 v1.2.0+ 静默忽略旧语法导致发送失败
• [HIMA-002] 非交互式环境 (Agent/脚本) 需要发送邮件或回复 → 优先使用 cat << EOF | himalaya template send 管道输入，避免依赖 $EDITOR 交互模式
• [HIMA-003] 需要程序化解析邮件列表或状态 → 始终添加 --output json 参数以获取结构化数据，而非解析纯文本输出
• [HIMA-004] 执行 himalaya account configure 等需要交互输入的向导 → 必须启用 PTY 模式 (pty=true) 运行终端命令，否则无法捕获交互输入
• [HIMA-005] 邮件发送命令返回非零退出码且涉及重试逻辑 → 检查是否因文件夹别名配置错误导致保存失败，严禁盲目重试 SMTP 发送以防止产生重复邮件
• [HIMA-006] 需要安全存储 IMAP/SMTP 密码 → 在配置中使用 backend.auth.cmd 指向 pass、系统 keyring 或输出密码的命令，避免明文存储
• [HIMA-007] 调试连接或逻辑错误 → 设置 RUST_LOG=debug 或 RUST_LOG=trace 环境变量以获取详细的日志和回溯信息