How to use the Himalaya Email CLI agent skill

What the himalaya skill lets your agent do

An agent skill is a folder of instructions and supporting files that an AI agent can load when a task matches it. The himalaya skill covers email. Once it is installed and an account is configured, the agent can run Himalaya commands on your computer to list folders, list and search messages, read messages, draft and send emails, reply or forward, move, copy or delete messages, manage flags, and download attachments.

Himalaya is a CLI email client that works with IMAP, SMTP, Notmuch or Sendmail backends. The skill is built around IMAP for reading and SMTP for sending, which is how most standard email accounts are reached.

Install Himalaya and the himalaya skill

The skill needs the himalaya command-line tool installed first. The skill's metadata lists Homebrew as an install option, so on a machine with brew you can install it with the formula name himalaya. Check that it works by running himalaya --version.

To add the skill itself, download the ZIP from our page and unzip it into one of these locations: ~/.claude/skills/ for all your projects, or a .claude/skills/ folder inside a specific project. Alternatively, in the Claude apps go to Settings, then Capabilities, then Skills, and upload the ZIP there.

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Configure your email account

Himalaya needs a configuration file at ~/.config/himalaya/config.toml that describes your account. The skill points to an interactive wizard, which you can run yourself if you prefer not to edit files by hand. You can also create the file manually. The example below uses one account with IMAP for reading and SMTP for sending. Replace the host names, port and login with your provider's details.

For passwords, the skill recommends storing them securely with pass, your system keyring, or a command that prints the password, using backend.auth.cmd. The reference file also shows a raw password option, but it describes that only as for testing and not recommended. Avoid putting a real password directly in the file.

• Use the wizard or a hand-written config.toml at ~/.config/himalaya/config.toml
• IMAP (reading): typically port 993 with tls encryption
• SMTP (sending): typically port 587 with start-tls encryption
• Password: use pass, a keyring, or backend.auth.cmd rather than raw text

Trigger the skill with natural requests

You do not need special syntax. Describe the email task in plain language, and the agent will match it to this skill when it fits. Be specific about the folder, the sender, the subject and what you want done, so the agent does not guess. Ask it to confirm before sending if you want a review step.

Message IDs are relative to the current folder, so if you change folders the agent should list emails again before acting on an ID.

• 'Summarise my unread messages in INBOX from this week.'
• 'Find emails from john@example.com about the meeting and list their subjects.'
• 'Draft a reply to message 42 declining politely, show it to me, and wait for my approval.'
• 'Move the newsletters in Archive and save the PDF attachment from message 17 to ~/Downloads.'

Common operations the agent can run

These are the Himalaya commands the skill documents. The agent chooses among them based on your request. You can run the same commands yourself to check what it will do. Use --folder to pick a folder, --page and --page-size for pagination, and --account to pick an account when you have several.

To compose, the skill shows opening your $EDITOR interactively, or sending a message piped in with a template. Rich emails with attachments use MML (MIME Meta Language), described in the message composition reference.

• List folders and emails: folder list, envelope list
• Read: message read 42, or export raw MIME with message export 42 --full
• Reply: message reply 42, or reply-all with --all
• Forward, move, copy and delete: message forward, message move, message copy, message delete
• Flags: flag add 42 --flag seen and flag remove 42 --flag seen
• Attachments: attachment download 42 --dir ~/Downloads
• Multiple accounts: account list, and --account work

Safety: scripts and network access

This skill runs scripts and uses the network. Himalaya connects to your mail server over IMAP and SMTP, and the agent executes commands on your machine. The skill can send messages directly, and it has full read and delete access to whatever account is configured. A mistaken instruction, or instructions hidden inside an email the agent reads, could cause it to send or delete mail on your behalf.

Keep the agent supervised for sending and deleting. Use a dedicated or low-sensitivity account if you can, and avoid shared mailboxes. Store credentials with pass, a keyring or a password command so they are not kept in plain text.

• Ask for a draft and approve it before any send
• Do not use the skill on shared or high-sensitivity mailboxes without care
• Keep passwords out of config.toml where possible

Tips and debugging

Run himalaya --help or himalaya <command> --help to see detailed usage for any command. If something fails, enable debug logging with RUST_LOG=debug, or use a full trace with a backtrace. Use --output json when you want structured output the agent can parse more easily, or --output plain for simpler text.

• Confirm the setup first with himalaya --version and himalaya folder list
• Use --output json for structured results
• Keep the config file path at ~/.config/himalaya/config.toml