himalaya-kit 0.4.3

An extension toolkit for reliable multi-step himalaya email automation and agent workflows

himalaya-kit

himalaya-kit is a Python toolkit that complements the himalaya mail CLI for automation and AI-assisted workflows. It combines himalaya primitives into safer multi-step workflows for composing, sending, searching, batch-exporting, and optionally organizing mail.

Project status: Alpha. The core workflows are usable, but command output and public interfaces may still evolve across 0.x releases.

Why this project exists

himalaya already provides a solid foundation for mail access and folder management. himalaya-kit is designed to fill the gaps that often appear in scripted or agent-driven workflows by offering a small, reusable layer on top of himalaya rather than replacing it.

Features

Command	Purpose
status	Inspect config and backend integration without mail authentication
send	Compose and send a new message
reply	Reply to an existing message
forward	Forward a message with optional attachments
search	Search archived mail and online mail by sender or keyword
export	Safely batch-export, validate, index, and resume local .eml backups

Optional workflows:

Command	Purpose
archive	Apply the bundled five-level organization preset
yearly-archive	Optional compatibility workflow for yearly/monthly export-and-delete
skill install	Install the bundled Agent Skill for a project or user
skill status/update/uninstall	Inspect and safely manage a versioned Agent Skill
setup	Install the bundled Skill and diagnose local integration
doctor	Run offline, redacted environment diagnostics

Installation

For a user-level CLI available from every project, use uv (recommended):

uv tool install "himalaya-kit[markdown]"
himalaya-kit setup --user --dry-run
himalaya-kit setup --user
himalaya-kit skill status --user --json
himalaya-kit skill update --user --dry-run
himalaya-kit doctor --json
himalaya-kit doctor --export diagnostic.json

setup is idempotent: it installs a missing Skill, skips the current version, and updates an older unmodified managed copy. Local or unmanaged changes are preserved unless --force is explicit. See PRIVACY.md for the diagnostic data boundary; 0.4.3 contains no telemetry or automatic upload.

pipx install "himalaya-kit[markdown]" is the equivalent fallback. The user Skill target is ~/.agents/skills/himalaya-kit; each Agent tool's discovery configuration remains the user's responsibility.

For a Python project dependency or SDK integration:

python -m pip install "himalaya-kit[markdown]>=0.4,<0.5"

For source development:

git clone https://github.com/xiaolinstar/himalaya-kit.git
cd himalaya-kit
pip install -e .

Complete Chinese guides:

• User guide
• Agent integration and installation guide
• Installable Agent Skill

Quick start

# Check how himalaya-kit is connected (does not authenticate to mail servers)
himalaya-kit status
himalaya-kit status --backend native --json

# Send a message
himalaya-kit send -t "张三 <[e-mail]>" -s "测试" -b "你好"

# Send Markdown mail
echo "# 报告" | himalaya-kit send -t [e-mail] -s "周报" --markdown

# Reply to an existing message
himalaya-kit reply 12345 -b "收到，谢谢"

# Forward a message
himalaya-kit forward 12345 [e-mail] --note "请查收"

# Search mail by sender
himalaya-kit search "Alice"

# Archive mail from the inbox
himalaya-kit archive --days 7

# Preview archive actions without moving mail
himalaya-kit archive --dry-run

# Preview a safe batch export (zero local writes and no server changes)
himalaya-kit export --before 2025-01-01 --dry-run

# Export one full message with native himalaya
himalaya message export --full -d message.eml 12345

himalaya vs himalaya-kit

Use himalaya directly when one native command safely completes the task. Use himalaya-kit when the task needs batching, validation, durable state, recovery, or coordination across multiple himalaya commands.

Goal	Recommended tool	Why
Export one message	himalaya message export	Native primitive is sufficient
Copy or move known message IDs	himalaya message copy/move	Native batch operation is sufficient
Export a date range	himalaya-kit export	Adds pagination, validation, indexing, and recovery
Export then remove server copies	himalaya-kit export --delete-after-export	Enforces export → verify → save index → delete ordering
Apply the five-level inbox model	himalaya-kit archive	Optional bundled workflow, not a universal email model

archive copies messages into priority folders and leaves the originals in place. yearly-archive is retained as a destructive compatibility workflow: after verified local export and index persistence, it marks server copies as deleted. Always run destructive workflows with --dry-run first.

To preserve the legacy workflow for a single month, use himalaya-kit yearly-archive --month YYYY-MM --dry-run. This is an optional compatibility command, not part of the general export API.

Safe batch export

# Strictly before the given date; defaults to INBOX
himalaya-kit export --before 2025-01-01 --dry-run

# Export a calendar year from multiple folders
himalaya-kit export --year 2025 \
  --folder INBOX --folder Sent \
  --output ~/email-archive/work

# Export an open/closed date range using strict boundaries
himalaya-kit export --after 2024-01-01 --before 2025-01-01

# Machine-readable plan for an Agent
himalaya-kit export --year 2025 --dry-run --json

# Destructive option: only delete after verified export and durable index save
himalaya-kit export --before 2025-01-01 --delete-after-export

Exports use himalaya's native envelope list and message export commands. himalaya-kit adds atomic file writes, basic .eml validation, collision-resistant names, an atomic archive-index.json, and repeat-run recovery. --dry-run does not create the output directory or modify server state.

Human-facing runs emit stable line-oriented logs as folders are scanned and messages complete, followed by a summary. --json suppresses those text logs and writes one complete JSON result to stdout for Agents and scripts. Dynamic terminal progress bars are intentionally not used.

Requirements

• Python 3.10+
• The himalaya CLI installed and configured
• A himalaya config file at ~/.config/himalaya/config.toml

Internationalization (i18n)

himalaya-kit supports Chinese (default) and English interfaces. You can switch languages in three ways:

1. Command-line argument

himalaya-kit --lang en send --help
himalaya-kit --lang zh send --help

2. Environment variable

export HIMALAYA_KIT_LANG=en
himalaya-kit send --help

3. Config file

[himalaya_kit]
lang = "en_US"

Supported language codes:

• zh_CN or zh - Chinese (default)
• en_US or en - English

Configuration

himalaya-kit reuses the existing himalaya account configuration and does not require a separate mail setup. A typical configuration looks like this:

[accounts.work]
default = true
email = "[e-mail]"
display-name = "Your Name"
# ... SMTP/IMAP settings

Optional extensions can be added under the [himalaya_kit] section:

[himalaya_kit]
backup-root = "~/email-archive"

my-email = "[e-mail]"
priority-contacts = ["[e-mail]"]
system-accounts = ["[e-mail]"]
internal-domains = ["company.com"]
timezone = "Asia/Shanghai"

notification-keywords = ["notification", "alert", "通知", "提醒"]

priority-folders = [
    "Priority-1-Urgent",
    "Priority-2-Internal",
    "Priority-3-External",
    "Priority-4-CC",
    "Priority-5-Notifications",
]

[himalaya_kit.contacts]
provider = "json"   # none | json | ai-todo
file = "~/.config/himalaya/contacts.json"

See examples/config.example.toml and examples/contacts.example.json for full examples.

Contacts: himalaya has no built-in address book. Use a local JSON file (default provider when configured) or optionally plug in ai-todo as an external contact source. Contacts with "tags": ["priority"] are merged into high-priority classification alongside priority-contacts.

Backward compatibility: leader-emails is still read and merged into priority-contacts.

Environment variables:

Variable	Description
HIMALAYA_KIT_BACKUP_ROOT	Override the archive backup directory

Python API

himalaya-kit 0.3 introduces a stable, Python-first SDK. The CLI calls the same client API, while himalaya command execution is isolated behind a replaceable backend:

from datetime import date

from himalaya_kit import ExportSelection, HimalayaKit, SendRequest

kit = HimalayaKit(account="work")

# Local integration only: no IMAP/SMTP authentication.
print(kit.status().to_dict())

# A dry run builds the complete message without resolving SMTP credentials.
preview = kit.send(
    SendRequest(
        to="[e-mail]",
        subject="Weekly update",
        body="Hello from Python",
    ),
    dry_run=True,
)
print(preview.preview)

# Structured result suitable for scripts and Agents.
result = kit.export(
    ExportSelection(before=date(2025, 1, 1)),
    dry_run=True,
)
print(result.to_dict())

The default HimalayaCliBackend keeps full compatibility with himalaya. The optional NativePythonBackend uses Python's standard-library IMAP/SMTP clients while continuing to read the same himalaya account configuration:

from himalaya_kit import HimalayaKit, NativePythonBackend

kit = HimalayaKit(account="work", backend=NativePythonBackend())

For CLI comparison and gradual migration, add --backend native to status or export. This backend is experimental and its scope is frozen to status and safe export; reply, forward, search, and optional organization workflows continue to use himalaya primitives.

Development

Run the test suite with:

pytest -q

License

Apache License 2.0