2023-01-04
vmt - CLI tool for composable interactions with email
vmt <COMMAND> [OPTIONS]
The goal of vmt 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.
This approach demands that the messages are available in Maildir++ format, so that each message is stored in a separate file. The vmt-sync(1) command can be used to create such a message store from an IMAP source.
The central mechanism that vmt employs is providing an interactive search mechanism which lets you pick one or more emails and will produce the filenames of those. This is implemented in the vmt-pick(1) command. These filenames can then e.g. be passed to other tools. However, vmt also provides a few built-in commands for common stuff you might want to use other tools for, such as vmt-cat(1).
See the Vomit project page at https://sr.ht/~bitfehler/vomit for a more detailed explanation along with some animated examples.
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" (see below), or an actual file system path. As a special case, vomit extends the concept of both to allow addressing a specific MIME part. Such a path will not be understood by other tools.
Here are some examples using actual file system paths:
Vomit 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 contents. It essentially uses the IMAP mailbox names, but always with / as the hierarchy delimiter. It also uses message IDs as identifier for emails:
Note that usually the user is not supposed to know a path like this. Certain vmt commands can be used to determine a path, other commands (vmt or external) can then be used to work with them.
-a, --account ACCOUNT
The account to operate on (default: first account in config)
-c, --config CONFIG
Set a custom config file location
-h, --help
Print help information
-v, --verbose
Increase verbosity (can be used multiple times)
-V, --version
Print version information
vmt-att(1)
Work with mail attachments
vmt-cat(1)
Output entire mail to stdout
vmt-hdr(1)
Work with email headers
vmt-help(1)
Print this message or the help of the given subcommand(s)
vmt-ls(1)
List mailboxes or emails
vmt-mime(1)
Work with MIME parts
vmt-pick(1)
Interactively pick mail(s) and print full path to stdout
vmt-show(1)
Show plain text mail body (if present)
vmt-sync(1)
Sync local maildir to remote IMAP account
vmt uses the unified configuration file of the Vomit project.
On startup vmt will look for a file at $XDG_CONFIG_HOME/vomit/config.toml. If unset, $XDG_CONFIG_HOME defaults to ~/.config/.
[example]
local = "~/.maildir"
remote = "imap.example.net"
user = "conrad"
pass-cmd = "pass show mail/example.com"
# Or hardcode it:
#password = 'secr3t'
More details about the configuration can be found in the documentation of the vomit-config library at https://docs.rs/vomit-config.
Maintained by Conrad Hoffmann <ch@bitfehler.net>. vmt is part of the Vomit project. You can find more information and source code at https://sr.ht/~bitfehler/vomit. Bugs/patches can be submitted by email to the vomit mailing list at ~bitfehler/vomit@lists.sr.ht (see https://lists.sr.ht/~bitfehler/vomit for more information).