Skip to main content
List and search IMAP mail, read messages, and compose, reply, forward or send through SMTP. Mirage uses the Himalaya command vocabulary with JSON output and workspace file attachments.

Setup

Configure the account using Email setup. Install the email extra.
No service mount is required. For YAML and multiple accounts, see the CLI overview.

SKILL.md

The SKILL.md an agent reads with himalaya installed.
Available commandsThese commands are registered with this shell; --help after a command or subcommand shows its usage.himalaya

Supported commands

Run himalaya <command> --help for the supported flags and operands. This list is generated from Mirage’s registered command tree.

Usage

Triage and read

Output matches upstream Himalaya. Listings print tables and confirmations print a sentence; add the global --json for JSON, in any position. message read shows the headers and walks the MIME parts, --raw returns RFC 5322 bytes, and --seen marks the message as seen, which reading alone does not. Messages take positional IDs. -m/--mailbox defaults to INBOX. An attachment’s ID is its position among the message’s MIME parts. Listings are newest first, with pages starting at 1 and a default page size of 25. The account’s max_messages (default 200) bounds the search and paging window. Sorted search considers that whole window. Search conditions are date, after, from, to, subject, body and flag. Combine them with and, or, not and parentheses; sort with order by date|from|to|subject [asc|desc]. Date conditions use the message’s Date: header, and after is exclusive. A pattern containing spaces needs literal double quotes inside the shell quotes, as above. A malformed query exits 1 before contacting the server, and the report points at where it stopped.

Compose, reply and send

Without --send, compose/reply/forward print MIME bytes and send nothing. With --json they print the decoded fields instead. Bodies come from --body, --body-file or stdin. message send accepts raw MIME on stdin, or after -- as text or a file path. --attach is repeatable and reads workspace files through the VFS; --from, --to, --cc, --bcc, --subject, --signature and --signature-file control the composed message. message add -m MAILBOX appends raw MIME to a mailbox and reports the new id. Reply uses Reply-To or From, adds reply headers and quotes the source. Forward prefixes the subject with Fwd: and keeps References. Both accept --posting-style top|bottom|none and --quote-headline. There is no reply-all switch; supply the extra recipients through --cc.

Save drafts and sent copies

Sending normally saves a seen copy by IMAP after SMTP succeeds. Mirage uses the server’s \Sent folder, or the config’s sent_folder (sentFolder) when set. save_copy=False (saveCopy: false) disables the default copy. --save MAILBOX overrides both settings for one command; without --send on a composer, it saves a draft and sends nothing. --no-save skips the configured copy. A copy that fails after delivery exits 1 and says the message was already sent, so do not retry it. Saving a draft without sending fails normally if IMAP refuses it.

Behavior

The optional Email VFS exposes the mailbox as files. Reading a message does not mark it seen. The CLI uses its own account config; attachments can come from any readable workspace mount. Server matching rules determine how search patterns match addresses and text. trash_folder (trashFolder in TypeScript) picks the mailbox message delete moves to, as upstream’s mailbox.alias.trash; unset, the server’s \\Trash tag decides. Only the mailbox, envelope, flag, message and attachment commands are present, and -c, -a and -b are not accepted since an install is one account.

License

See compatibility and licenses.