# Himalaya - CLI Email Client ## Overview ## User Interaction Model **NOT A TRADITIONAL TUI**: Himalaya is fundamentally different from traditional terminal email clients (mutt, aerc, alpine). It does NOT provide an interactive full-screen interface that you stay inside while managing email. Instead, it operates as a **stateless command-line tool** where each action is a separate shell command. **How You Actually Use It:** 1. **Reading Emails**: Run `himalaya envelope list` to see your inbox, get email IDs from the output 2. **Viewing Email Content**: Run `himalaya message read <ID>` to display a specific email in your terminal 3. **Composing New Emails**: Run `himalaya message write` which opens your `$EDITOR` (vim, nano, emacs, etc.) 4. **Replying to Emails**: Run `himalaya message reply <ID>` which opens your editor with reply template 5. **Attaching Files**: Use MML syntax in your editor: `<#part filename=/path/to/file.pdf><#/part>` 6. **Sending**: After composing in editor, save and quit - Himalaya automatically sends the message **Typical Workflow Example:** ```bash # Check inbox himalaya envelope list # Read email #42 himalaya message read 42 # Reply to email #42 (opens your $EDITOR) himalaya message reply 42 # In your editor, write reply and add attachment: # <#part filename=~/Documents/report.pdf><#/part> # Save and quit editor - email sends automatically # Forward an email himalaya message forward 42 # Search for emails himalaya envelope list --query "from:[email protected]" ``` **Key Distinction**: You execute commands, get results, execute more commands - just like using `git`, `curl`, or any CLI tool. This makes it perfect for: - **Shell scripts**: Automate email workflows with standard shell scripting - **Custom interfaces**: Build your own UI (web app, desktop app) that calls Himalaya commands - **Editor integration**: Vim/Emacs plugins that wrap Himalaya commands - **Scheduled tasks**: Cron jobs that check and process emails automatically **Trade-offs**: - **Pro**: Extremely scriptable, lightweight, no locked interface, integrates with Unix pipelines - **Con**: More commands to type for manual email management compared to staying in one TUI interface - **Best for**: Users who value flexibility and automation over convenience of persistent interface Himalaya is a command-line interface (CLI) email client written in Rust, designed as part of the Pimalaya project ecosystem for Personal Information Management. Unlike traditional Terminal User Interfaces (TUI) like mutt or aerc that lock users into an interactive event loop, Himalaya operates as a stateless CLI tool where email is managed through direct shell commands. This architecture makes it particularly well-suited for scripting, automation, and building custom email interfaces. Built on the reusable `email-lib` Rust library, Himalaya provides a simple CLI API that can be invoked from terminal, scripts, or integrated into custom UIs, making it a powerful choice for terminal-focused developers, system administrators, and privacy-conscious users seeking lightweight email management alternatives. ## Key Features - **Multi-backend support**: IMAP, Maildir, Notmuch, SMTP, and Sendmail through modular cargo features - **Stateless CLI design**: Command-based operation ideal for scripting and automation workflows - **Interactive configuration wizard**: Auto-discovery of IMAP/SMTP settings inspired by Thunderbird - **OAuth 2.0 authentication**: Support for Gmail, Outlook, and other providers with PKCE - **PGP encryption**: Multiple options via shell commands, GPG bindings, or native implementation - **MML (MIME Meta Language)**: Simplified composition of complex MIME messages with attachments - **Multi-account management**: Handle multiple email accounts from single configuration file - **JSON output mode**: Seamless integration with other CLI tools and scripts via `--output json` - **Keyring integration**: Secure credential storage using system keyring rather than plaintext - **Cross-platform**: Works on Linux, macOS, Windows, and BSD systems ## Platform Support ## Email Provider Support ### Gmail Configuration **Authentication Options:** 1. **OAuth 2.0 (Recommended)**: Secure authentication without exposing password 2. **App Password**: Legacy method requiring "Less secure app access" **OAuth 2.0 Setup:** ```bash # Run configuration wizard himalaya account configure gmail # Wizard will prompt for: # - Email address: [email protected] # - Display name: Your Name # - Authentication: Select OAuth 2.0 # - Client ID: From Google Cloud Console # - Client Secret: From Google Cloud Console ``` **Creating OAuth Credentials:** 1. Visit [Google Cloud Console](https://console.cloud.google.com/) 2. Create new project or select existing 3. Enable Gmail API 4. Create OAuth 2.0 credentials (Desktop app type) 5. Download client ID and secret 6. Provide to Himalaya configuration wizard **Gmail-Specific Considerations:** - **Folder Names**: Gmail uses `[Gmail]/Sent Mail`, `[Gmail]/All Mail` instead of standard names - **Labels**: Gmail labels map to IMAP folders - **Two-Factor Authentication**: Compatible with OAuth 2.0, incompatible with basic passwords - **IMAP Settings**: Auto-discovered by wizard (imap.gmail.com:993) - **SMTP Settings**: Auto-discovered by wizard (smtp.gmail.com:465 or 587) **Manual Configuration Example:** ```toml [accounts.gmail] default = true email = "[email protected]" display-name = "Your Name" backend = "imap" sender = "smtp" [accounts.gmail.imap] host = "imap.gmail.com" port = 993 encryption = "tls" login = "[email protected]" auth = "oauth2" client-id = "YOUR_CLIENT_ID" client-secret = "YOUR_CLIENT_SECRET" [accounts.gmail.smtp] host = "smtp.gmail.com" port = 587 encryption = "start-tls" login = "[email protected]" auth = "oauth2" client-id = "YOUR_CLIENT_ID" client-secret = "YOUR_CLIENT_SECRET" ``` ### Outlook/Office 365 Configuration **Authentication Options:** 1. **OAuth 2.0 (Recommended)**: Works with Microsoft 365 and Outlook.com accounts 2. **App Password**: For accounts with 2FA enabled **OAuth 2.0 Setup:** ```bash # Run configuration wizard himalaya account configure outlook # Wizard will guide through OAuth setup # Requires Azure AD app registration for OAuth ``` **Creating Azure OAuth App:** 1. Visit [Azure Portal](https://portal.azure.com/) 2. Navigate to "Azure Active Directory" → "App registrations" 3. Create new registration (Desktop app type) 4. Add permissions: Mail.ReadWrite, Mail.Send, offline_access 5. Copy Application (client) ID 6. Create client secret and copy value 7. Provide credentials to Himalaya wizard **Outlook-Specific Settings:** - **IMAP Server**: outlook.office365.com (port 993) - **SMTP Server**: smtp.office365.com (port 587) - **Encryption**: TLS/STARTTLS required - **Modern Auth**: OAuth 2.0 required for most accounts (basic auth deprecated) - **Multiple Accounts**: Supports both personal Outlook.com and organizational Office 365 **Manual Configuration Example:** ```toml [accounts.outlook] email = "[email protected]" display-name = "Your Name" backend = "imap" sender = "smtp" [accounts.outlook.imap] host = "outlook.office365.com" port = 993 encryption = "tls" login = "[email protected]" auth = "oauth2" client-id = "YOUR_AZURE_CLIENT_ID" client-secret = "YOUR_AZURE_CLIENT_SECRET" auth-url = "https://login.microsoftonline.com/common/oauth2/v2.0/authorize" token-url = "https://login.microsoftonline.com/common/oauth2/v2.0/token" [accounts.outlook.smtp] host = "smtp.office365.com" port = 587 encryption = "start-tls" login = "[email protected]" auth = "oauth2" client-id = "YOUR_AZURE_CLIENT_ID" client-secret = "YOUR_AZURE_CLIENT_SECRET" ``` ### iCloud Mail Configuration **Authentication:** - **App-Specific Password**: Required (iCloud does not support OAuth 2.0 for IMAP) - Two-factor authentication must be enabled on Apple ID **Generating iCloud App Password:** 1. Visit [appleid.apple.com](https://appleid.apple.com/) 2. Sign in with your Apple ID 3. Navigate to "Security" section 4. Select "App-Specific Passwords" 5. Generate new password (label it "Himalaya") 6. Copy the generated password (format: xxxx-xxxx-xxxx-xxxx) 7. Use this password in Himalaya configuration **Configuration Setup:** ```bash # Run configuration wizard himalaya account configure icloud # Wizard will prompt for: # - Email: [email protected] (or @me.com, @mac.com) # - App-specific password: The generated password ``` **iCloud-Specific Settings:** - **IMAP Server**: imap.mail.me.com (port 993) - **SMTP Server**: smtp.mail.me.com (port 587) - **Encryption**: TLS required for IMAP, STARTTLS for SMTP - **Email Aliases**: Configure separate accounts for each alias - **Custom Domain**: Works with iCloud+ custom domain emails **Manual Configuration Example:** ```toml [accounts.icloud] email = "[email protected]" display-name = "Your Name" backend = "imap" sender = "smtp" [accounts.icloud.imap] host = "imap.mail.me.com" port = 993 encryption = "tls" login = "[email protected]" passwd = { keyring = "icloud-app-password" } # Stored in system keyring [accounts.icloud.smtp] host = "smtp.mail.me.com" port = 587 encryption = "start-tls" login = "[email protected]" passwd = { keyring = "icloud-app-password" } ``` **Common Configuration Tips:** - **Keyring Storage**: Use `passwd = { keyring = "key-name" }` instead of plaintext passwords - **Testing Connection**: Run `himalaya account sync` to verify configuration - **Multiple Accounts**: Configure all providers in single `~/.config/himalaya/config.toml` - **Auto-Discovery**: Wizard automatically detects most settings, manual config rarely needed - **OAuth Tokens**: Stored securely, auto-refreshed by Himalaya when expired - **Linux**: Native support via package managers (Arch pacman, Fedora/RHEL dnf), Homebrew, Cargo, or pre-built binaries - **macOS**: Available through Homebrew (`brew install himalaya`), Cargo, or pre-built binaries - **Windows**: Installation via Scoop package manager (`scoop install himalaya`), Cargo, or pre-built binaries - **BSD Systems**: Available through Nix package manager or build from source - **Installation Methods**: Homebrew, Cargo (Rust toolchain), Nix, Scoop, system package managers, or installer script for pre-built binaries ## Pricing - **Free and Open Source**: MIT licensed with no cost for personal or commercial use - **Funding Model**: Supported by NLnet Foundation and European Commission grants (NGI Assure 2022, NGI Zero Entrust 2023, NGI Zero Core 2024-ongoing) - **Community Support**: Accepts donations via GitHub Sponsors, Ko-fi, Buy Me a Coffee, Liberapay, PayPal, and thanks.dev - **No Premium Tiers**: All features available to all users without paid upgrades ## Installation **macOS (Recommended):** ```bash brew install himalaya ``` **Linux/macOS (via Cargo):** ```bash cargo install himalaya ``` **Arch Linux:** ```bash pacman -S himalaya # or via AUR ``` **Windows (via Scoop):** ```bash scoop install himalaya ``` **Fedora/RHEL:** ```bash dnf copr enable atim/himalaya dnf install himalaya ``` **From Source:** ```bash git clone https://github.com/pimalaya/himalaya.git cd himalaya cargo build --release ``` **First Run:** Simply execute `himalaya` to launch the interactive configuration wizard with auto-discovery of email provider settings. ## Email Management ### Configuration Approach - **Interactive wizard**: Run `himalaya` on first launch for guided setup with auto-discovery - **Manual editing**: Configuration stored in `~/.config/himalaya/config.toml` - **Auto-discovery**: Checks autoconfig domains, ISPDB, MX/SRV DNS records, and common patterns - **Multi-account**: Single config file manages multiple email accounts - **Provider examples**: Detailed configurations available for Gmail, Outlook, Proton Mail Bridge, iCloud Mail ### Message Composition - Uses `$EDITOR` environment variable for composing emails in preferred text editor - Supports plain text messages and MML (MIME Meta Language) for complex MIME compositions - MML syntax for attachments: `<#part filename=/path/to/file.pdf><#/part>` - Inline images: `<#part disposition=inline filename=/image.png><#/part>` ### Email Protocols - **IMAP**: Full support (requires 'imap' cargo feature) - **SMTP**: Sending via SMTP servers (requires 'smtp' feature) - **Sendmail**: Alternative sending method (requires 'sendmail' feature) - **Maildir**: Local storage format (requires 'maildir' feature) - **Notmuch**: Integration with Notmuch email system (requires 'notmuch' feature) ### Security Features - **Authentication**: Password (raw/cmd/keyring), OAuth 2.0 with PKCE support - **Encryption**: PGP via shell commands, GPG bindings, or native Rust implementation - **Credential Storage**: System keyring integration for secure password management - **Provider Support**: OAuth 2.0 configured for Gmail, Outlook, and other major providers ## CLI Capabilities ### Command Structure Post-v1.0.0 architecture uses domain-based command structure: ```bash himalaya <domain> <action> ``` **Example Commands:** ```bash # Account management himalaya account configure gmail # List emails himalaya envelope list # Send composed message himalaya message send # List folders/mailboxes himalaya folder list # JSON output for scripting himalaya --output json envelope list # Debug mode with logging RUST_LOG=debug himalaya 2>/tmp/himalaya.log ``` ### Modular Architecture - **Cargo features**: Compile only needed functionality to reduce binary size - **email-lib foundation**: Built on reusable Rust library for deeper integrations - **Stateless operation**: No event loop, each command is independent - **Scriptability**: Perfect for cron jobs, automation workflows, and shell scripts - **JSON output**: Flag-based JSON mode for integration with jq and other CLI tools ## Use Cases - **Email Automation**: System administrators scripting email workflows, automated notifications, and scheduled sends - **Custom Interface Development**: Developers building custom email applications using Himalaya as CLI backend or email-lib as Rust library - **Terminal Workflow Integration**: Power users managing multiple accounts entirely from terminal alongside other CLI tools - **Privacy-Focused Management**: Users wanting local email control with PGP encryption, Maildir storage, and no web browser dependency - **Editor Integration**: Vim/Emacs users managing email without leaving their editor environment via dedicated plugins - **Lightweight Mail Client**: Users seeking minimal resource usage alternative to heavy desktop email applications ## Integrations - **Vim Plugin**: `himalaya-vim` for integrated email management within Vim editor - **Emacs Plugin**: `himalaya-emacs` by dantecatalfamo for Emacs integration - **Raycast Extension**: Quick access to Himalaya commands via Raycast launcher on macOS - **REPL Variant**: Experimental `himalaya-repl` for interactive REPL-style email management - **Password Managers**: Compatible with CLI-queryable password managers (pass, 1Password CLI, etc.) - **System Keyring**: Native integration with macOS Keychain, GNOME Keyring, Windows Credential Manager - **Pimalaya Ecosystem**: Part of broader toolset including Neverest (sync) and Mirador (watch) for specialized tasks ## Technical Details - **Language**: Written in Rust for performance, safety, and cross-platform compatibility - **Architecture**: Domain-based command structure introduced in v1.0.0 (December 2024) - **Library**: Built on `email-lib` Rust library, enabling custom application development - **Configuration**: TOML-based config file with sample templates for major providers - **Modular Compilation**: Cargo feature flags allow enabling only needed backends and protocols - **Project Status**: Production-ready (v1.1.0 as of January 11, 2025), actively maintained - **License**: MIT License permitting commercial use - **Version Control**: GitHub repository with 5,000+ stars, 141 forks ## Remarks Himalaya distinguishes itself in the CLI email client landscape through its stateless command-based architecture rather than traditional interactive TUI design, making it exceptionally well-suited for automation, scripting, and custom interface development. Built on the solid foundation of the Rust-based email-lib and backed by European Commission funding, it represents a modern approach to terminal email management that prioritizes flexibility and integration over monolithic feature sets. The tool's modular cargo features, comprehensive OAuth 2.0 support, and JSON output capabilities make it particularly valuable for developers and system administrators who need programmatic email access, while its interactive configuration wizard and editor integration ensure it remains accessible for daily email management tasks. As part of the evolving Pimalaya ecosystem, Himalaya focuses on core email operations while delegating synchronization and watching to specialized companion tools, reflecting a philosophy of doing one thing exceptionally well rather than attempting to be an all-in-one solution.