himalaya

# Himalaya v2 Email CLI Use this skill only with Himalaya major version 2. Its command and configuration syntax differs from v1. ## References - `references/configuration.md` for v2 config paths, accounts, and backends. - `references/message-composition.md` for v2 compose and send flows. ## Install and configure Install a v2 build and verify it before continuing: ```bash himalaya --version ``` Official installation options include Homebrew and the current Git repository: ```bash brew install himalaya cargo install --locked --git https://github.com/pimalaya/himalaya.git ``` If the package manager installs v1, use a v2 release or the Git installation. Run the v2 setup wizard with no subcommand: ```bash himalaya ``` The wizard prints TOML that can be saved or merged into the config. There is no v2 `account configure` command. Check the result with: ```bash himalaya --json account list himalaya --account=work account check ``` ## Command conventions Use v2's global account and backend selectors before the subcommand. Mailbox selectors belong to the leaf command: ```bash himalaya --json --account=work --backend=imap envelope list --mailbox=INBOX ``` - `--json` selects structured output; v2 does not use `--output json`. - `--account` and `--backend` are global selectors. `--mailbox` is a leaf-command option; these can also be written as `-a`, `-b`, and `-m`. - Shared read backends are `imap`, `jmap`, `gmail`, `msgraph`, `maildir`, and `m2dir`. SMTP sends messages; it does not fetch them. - Message IDs are mailbox-relative for some backends. Re-list after moving mail or changing mailboxes. ## Read operations List mailboxes and envelopes: ```bash himalaya --json --account=work --backend=imap mailbox list himalaya --json --account=work --backend=imap \ envelope list --mailbox=INBOX --page=1 --page-size=20 ``` Search with the v2 shared query language: ```bash himalaya --json --account=work --backend=imap \ envelope search --mailbox=INBOX -- \ from alice@example.com and subject meeting order by date desc ``` Read a rendered message or raw RFC 5322/MIME: ```bash himalaya --account=work --backend=imap message read --mailbox=INBOX -- 42 himalaya --account=work --backend=imap message read --mailbox=INBOX --raw -- 42 ``` The shared `envelope search` query language is not implemented by the v2 Gmail or Microsoft Graph backends. Use their protocol-specific APIs when native search is required: ```bash himalaya --json --account=work gmail messages list -q "from:alice is:unread" himalaya --json --account=work msgraph mail-folder list ``` ## Manage messages Use explicit source and destination mailboxes for copy or move operations: ```bash himalaya --account=work --backend=imap message copy --from=INBOX --to=Archives -- 42 himalaya --account=work --backend=imap message move --from=INBOX --to=Archives -- 42 ``` The shared message command in Himalaya v2.0.0 has no delete operation. Use a backend-specific command when deletion is required. Manage flags and attachments: ```bash himalaya --account=work --backend=imap flag add --mailbox=INBOX --flag=seen -- 42 himalaya --account=work --backend=imap flag remove --mailbox=INBOX --flag=seen -- 42 himalaya --account=work --backend=imap attachment list --mailbox=INBOX -- 42 himalaya --account=work --backend=imap attachment download --mailbox=INBOX -- 42 ``` ## Debugging Every command provides v2-specific help. Use logging on stderr when needed: ```bash himalaya envelope search --help himalaya --log=debug --account=work --backend=imap mailbox list himalaya --log=trace --log-file=/tmp/himalaya.log \ --account=work --backend=imap mailbox list ```