Vomit Mail Tool - vmt

Crates.io builds.sr.ht status

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:

"vmt pick" 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:

"vmt cat" example

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:

"vmt att" example

Getting started

vmt wants mail stored in Maildir++ format. You can use the vmt sync command to sync your IMAP account to a local maildir, or any other tool that does this.

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

Addressing resources

Most commands take an optional path. In vmt, a path can refer to either a mailbox, an email, or a MIME part (e.g. an attachment). If a path is omitted, the interactive picker will be executed. If a command expects e.g. an email, but only a mailbox is provided, the interactive picker will be executed to pick an email from the specified mailbox.

A path can be either "virtual", or an actual file system path. As a special case, vomit accepts a path that references a specific MIME part. Such a path will not be understood by other tools.

Here are some examples using actual file system paths:

vmt supports using a relative path, using the configured maildir as base. The above examples could be written as:

In addition, a "virtual" path can be used, which is (hopefully) more representative of the mental picture one might have about their mailbox layout. It essentially uses the IMAP mailbox names, but always with / as the hierarchy delimiter. It also uses message IDs as identifier for emails:

Commands

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

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:

``` [] 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.