# Vomit Mail Tool - vmt [![Crates.io](https://img.shields.io/crates/v/vmt.svg)](https://crates.io/crates/vmt) [![builds.sr.ht status](https://builds.sr.ht/~bitfehler/vmt/commits.svg)](https://builds.sr.ht/~bitfehler/vmt/commits?) `vmt` is the main tool of the [Vomit project][4]. Its aspiration is to let you do (almost) anything with your email _without_ being a [MUA][7]. Instead, it is designed to integrate into (CLI-based) workflows that happen to need access to emails. [4]: https://sr.ht/~bitfehler/vomit "Vomit project page on sr.ht" [7]: https://en.wikipedia.org/wiki/Email_client "MUA on Wikipedia" **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][1] (the Rust equivalent to the somewhat more popular [fzf][2]), 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. [1]: https://github.com/lotabout/skim "Skim Github project" [2]: https://github.com/junegunn/fzf "fzf Github project" 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](https://bitfehler.net/pick.gif)](https://bitfehler.net/pick.gif) 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](https://bitfehler.net/patch.gif)](https://bitfehler.net/patch.gif) 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](https://bitfehler.net/save.gif)](https://bitfehler.net/save.gif) ## Getting started `vmt` requires mails stored in [m2dir][3] 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](#installation) section for install options and the [config file](#config-file) section for the initial configuration. [3]: https://sr.ht/~bitfehler/m2dir/ "M2dir project page on sr.ht" ## 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)][vmt]. * [pick][pick] Interactively pick mail(s) and print full path to stdout * [ls][ls] List mailboxes or emails * [att][att] Work with mail attachments * [cat][cat] Output entire mail to stdout * [hdr][hdr] Work with email headers * [mime][mime] Work with MIME parts * [show][show] Show plain text mail body (if present) * [sync][sync] Sync local maildir to remote IMAP account [vmt]: https://bitfehler.net/man/vmt.1.html [pick]: https://bitfehler.net/man/vmt-pick.1.html [ls]: https://bitfehler.net/man/vmt-ls.1.html [att]: https://bitfehler.net/man/vmt-att.1.html [cat]: https://bitfehler.net/man/vmt-cat.1.html [hdr]: https://bitfehler.net/man/vmt-hdr.1.html [mime]: https://bitfehler.net/man/vmt-mime.1.html [show]: https://bitfehler.net/man/vmt-show.1.html [sync]: https://bitfehler.net/man/vmt-sync.1.html ## 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 ` 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 ` can be used. Like all Vomit tools, vmt uses the shared "vomit-config" configuration file. See [its documentation][5] for more details. Note that it supports some configuration options that `vmt` does not currently use. [5]: https://docs.rs/vomit-config "vomit-config documentation" ## Installation Currently, there is only an [AUR package][6]. 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`. [6]: https://aur.archlinux.org/packages/vomit "vomit AUR package"