Vomit Mail Tool - vmt

vmt is the main tool of the Vomit project. Its aspiration is to let you do (almost) anything with your email without being a MUA. Instead, it is designed to integrate into (CLI-based) workflows that happen to need access to emails.

NOTE: A lot of experimentation is still happening. The functionality described here should work reasonably reliably, but the interfaces (sub-commands, parameters) may change as new features get added.

The central mechanism that vmt employs is providing an interactive search mechanism based on Skim (the Rust equivalent to the somewhat more popular fzf), which lets you pick one or more emails and will produce the filenames of those. These filenames can then e.g. be passed to other tools. It also provides a few built-in commands for common stuff you might want to use other tools for.

The described base functionality is provided by the vmt pick command. It captures your terminal, lets you interactively pick an email, and then writes the email's filename to stdout. Here is an example:

In the simplest case, this could be used to output the file and pipe the contents to something that handles email as input, such as git am. Since this is a common use case, the vmt cat command is provided. Here is an example of applying a patch that was circulated on a mailing list:

Of course email is used for other stuff, like sending attachments. vmt has you covered and offers the vmt att command (which itself has various sub-commands). Here is a little example listing and then saving attachments:

Getting started

vmt requires mails stored in m2dir format. You can use the vmt sync command to sync your IMAP account to a local m2dir.

As there are currently no real MUAs that support m2dir, and the included synchronization is still somewhat experimental, the following setup is recommended:

• Use the MUA of your choice to manage your email in an IMAP account
• Use vmt sync --pull regularly to pull the remote state to the local m2dir

See the installation section for install options and the config file section for the initial configuration.

Addressing resources

Most commands take one or more optional path(s). In vmt, a path can refer to either a mailbox or an email. If a path is omitted, the interactive picker will be executed.

A path can be either "virtual", or an actual file system path. Ab absolute path is always interpreted as file system path. A relative path is first tested for existence. If it does not exist, vmt will check for a config file and try to interpret the provided path as relative to the account root.

Examples using actual file system paths (these work without a config file):

• /home/conrad/.mail/INBOX
• .mail/lists/knot (if $CWD is /home/conrad)

If an account is configured, the following examples would be equivalent to the above ones:

• INBOX
• lists/knot

Commands

NOTE: this section - and the linked man pages - are potentially outdated; they are currently being revised for the 1.0 release.

This is a list of available commands, with links to the respective man pages. The main man page is vmt(1).

• pick Interactively pick mail(s) and print full path to stdout
• ls List mailboxes or emails
• att Work with mail attachments
• cat Output entire mail to stdout
• hdr Work with email headers
• mime Work with MIME parts
• show Show plain text mail body (if present)
• sync Sync local maildir to remote IMAP account

Config file

Per default located at ~/$XDG_CONFIG_HOME/vomit/config.toml, which usually means ~/.config/vomit/config.toml. A configuration file at an arbitrary location can be used by using the global -c <path> flag.

A simple config example:

[<account>]
local = ~/.maildir
# Everything below is only needed if you intend to use `vmt sync`
remote = "imap.example.com:993"
user = "myusername"
pass-cmd = "pass show mail/myaccount"
# or use this:
#password = "s3cr34"

Multiple accounts can be specified, by default vmt will use the first one. To use a different one, the global flag -a <account> can be used.

Like all Vomit tools, vmt uses the shared "vomit-config" configuration file. See its documentation for more details. Note that it supports some configuration options that vmt does not currently use.

Installation

Currently, there is only an AUR package.

You can also run cargo install vmt to install the latest released version. Make sure the executable is in your $PATH ($PATH should include your cargo home dir).

To install the latest version from this repo, you can build with cargo build --release and optionally run cargo install.