mail CLI for people, scripts and agents

mail copies your mailbox into the shared WireCat store on your computer, so you and your AI agents can search it and read it there, offline. It also organises the mailbox on the server: flags, folders, and deletion to Trash, each change one you can undo. It keeps drafts, and sends, replies and forwards over SMTP.

Documentation · Roadmap · WireCat

Quick start

First turn on IMAP in your mailbox and make an app password: the steps for every provider. Then, with a profile name of your choice (personal here) and your own address in place of the synthetic me@example.com:

npm install -g @wirecat/mail-cli
mail personal session start --address me@example.com   # finds the server, shows the steps, asks for the app password.
mail personal account check                            # logs in and lists what the server supports
mail personal sync                                     # reads the last 30 days into the shared store
mail personal status                                   # how far the sync is
mail personal search messages invoice                  # search the stored mail
mail skill install                               # optional: instructions for your AI agent

Now the mail is in the store. messages show with the ref a search hit gives reads that email whole. memo searches it together with your messages and notes: memo search all "invoice".

You need Node.js 22.16 or a later 22.x, or 24 or later. To try it with no install, run npx @wirecat/mail-cli --help. If mail is not found, mail doctor says why.

What you can do

• Sync a mailbox into the shared store. sync reads INBOX and Sent (All Mail on Gmail), or the folders you name, newest first, and skips what is already stored. --since-time 2026-10-01 reads from local midnight of that day.
• Search and read the stored mail. search messages 'from:ann@example.com has:attachment date>30d' uses the query language of every WireCat CLI, with list: for mailing lists; messages show gives an email whole with its attachments' text, conversations list|show its threads. It searches the profile's mailbox only; it also asks the mail server for mail sync has not read yet, and --backend archive keeps to the store. memo searches every mailbox together with your messages and notes.
• Export to mbox or Maildir. messages export 'from:ann@example.com' --output-dir ~/mail-backup reads the original messages from the server into a private folder, one mbox file per folder or a Maildir++ tree for mu and notmuch; it can be resumed and bounded. stats messages top --by list ranks senders, lists and domains.
• Sync a big mailbox in parts. A run stops before its deadline, keeps what it read and tells you to run it again; status shows how far it is.
• Check a mailbox. account check shows what the server supports, folders list the folders with their role an

... View full README on GitHub