MELI(1)

📦
version 0.8.13 · 3 versions
, in alpine 3.24, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

🍯 meli(1) — General Commands Manual 🍯

okay bestie, welcome to meli, the terminal e-mail client 💖 (fun fact no cap: μέλι is the Greek word for honey 🐝🍯, so yes, the whole thing is themed and it's adorable).

✨ NAME ✨

meli — terminal e-mail client. μέλι is the Greek word for honey 🐝

🎀 SYNOPSIS 🎀

meli [--help | -h] [--version | -v] [--config path]

and then the lil subcommands, each one giving main character energy in its own way:

  • --help, -h — show the help message and dip out. 👋
  • --version, -v — show the version and dip out. 💅
  • --config path — start meli with the configuration file you point at.
  • create-config [path] — make a configuration file in path if you gave one, otherwise at $XDG_CONFIG_HOME/meli/config.toml. And if path is -, the result gets printed straight to the standard output stream. ✨
  • test-config [path] — vibe-check a config for syntax issues or missing options. It reads from path if given, or from $XDG_CONFIG_HOME/meli/config.toml. If path is -, it reads the config from the standard input stream. 🧐
  • man [page] — print a documentation page and exit (lowkey recommended to pipe it into a pager).
  • install-man [path] — install the manual pages to the first location given by MANPATH or manpath(1), unless you hand it the directory as an argument.
  • compiled-with — print the compile time feature flags of this binary. 👑
  • edit-config — edit configuration files with EDITOR or VISUAL.
  • help — prints help information, or the help of the given subcommand(s).
  • print-app-directories — print every directory that meli creates and uses. 🗂️
  • print-config-path — print the location of the configuration file that will be loaded on normal app startup.
  • print-default-theme — print the default theme keys and values in TOML syntax, so you can use it as a blueprint. 🎨
  • print-loaded-themes — print all loaded themes in TOML syntax.
  • print-log-path — print the log file location. 📄
  • view — view mail from an input file.

🌈 DESCRIPTION 🌈

meli is a terminal mail client aiming for extensive and user-friendly configurability. fr fr, that's the whole assignment. 💖

     ^^      .-=-=-=-.  ^^
 ^^        (`-=-=-=-=-`)         ^^
         (`-=-=-=-=-=-=-`)  ^^         ^^
   ^^   (`-=-=-=-=-=-=-=-`)   ^^
       ( `-=-=-=-(@)-=-=-` )      ^^
       (`-=-=-=-=-=-=-=-=-`)  ^^
       (`-=-=-=-=-=-=-=-=-`)          ^^
       (`-=-=-=-=-=-=-=-=-`)
^^     (`-=-=-=-=-=-=-=-=-`)  ^^
   ^^   (`-=-=-=-=-=-=-=-`)          ^^
         (`-=-=-=-=-=-=-`)  ^^
  ^^       (`-=-=-=-=-`)
            `-=-=-=-=-`          ^^

(it's a bee. it's giving 🐝. we love her.)

🌸 STARTING WITH meli 🌸

First launch energy 🫶: meli goes looking for its configuration directory, $XDG_CONFIG_HOME/meli/. If it's not there, you get asked whether you wanna create one, and you're handed a sample configuration file ($XDG_CONFIG_HOME/meli/config.toml) that has the basic settings you need for setting up accounts — so you can literally copy and edit right away. The available configuration options live in meli.conf(5).

At literally any time, you can press ⟨?⟩ (shortcuts.general.toggle_help) for a searchable list of all available actions and shortcuts, plus every possible setting and command that your version supports. 🔍

The main visual navigation tool, the left-side sidebar, can be toggled with ⟨⟩ (shortcuts.listing.toggle_menu_visibility`).

Each mailbox can be viewed in 4 modes:

  • Plain — views each mail individually,
  • Threaded — shows their thread relationship visually,
  • Conversations — collapses each thread of e-mails into a single entry,
  • Compact — shows one row per thread.

If you're using a light color palette in your terminal, you should set theme = light in the terminal section of your configuration. Full docs on user themes are in meli-themes(5). 🌈

And for a more detailed tutorial on using meli, see meli(7). 💜

⚡ SHORTCUTS ⚡

See meli.conf(5) SHORTCUTS for shortcuts and their default values. iykyk. 💅

💌 VIEWING MAIL 💌

Open attachments by typing their index in the attachments list and then ⟨a⟩ (shortcuts.envelope_view.open_attachment). meli will attempt to open text inside its pager, and other content via xdg-open. Press ⟨m⟩ (shortcuts.envelope_view.open_mailcap) instead to use the mailcap entry for the MIME type of the attachment, if any. See “FILES” for the location of the mailcap files and mailcap(5) for their syntax. You can save individual attachments with the following command:

save-attachment INDEX path-to-file
  • INDEX is the attachment's index in the listing.
  • If the path provided is a directory, the attachment is saved with its filename set to the filename in the attachment, if any.
  • If the 0th index is provided, the entire message is saved.
  • If the path provided is a directory, the message is saved as an eml file with its filename set to the messages message-id.

You can pipe individual attachments to binaries with the following command:

pipe-attachment INDEX binary ARGS

Example usage with the less(1) pager:

pipe-attachment 0 less

If the binary does not wait for your input before exiting, you will probably not see its output since you will return back to the user interface immediately. You can write a wrapper script that pipes your binary's output to

less

or

less -r

if you want to preserve the ANSI escape codes in the pager's output. 🎀

Every e-mail storage backend gets a default search method assigned. IMAP uses the SEARCH command, notmuch uses libnotmuch and Maildir/mbox performs a slow linear search 😭. It is advised to use a search backend on Maildir/mbox accounts. meli, if built with sqlite3, includes the ability to perform full text search on the following fields: From, To, Cc, Bcc, In-Reply-To, References, Subject and Date. The message body (in plain text human readable form) and the flags can also be queried. To enable sqlite3 indexing for an account set search_backend to sqlite3 in the configuration file and to create the sqlite3 index issue command:

reindex ACCOUNT_NAME

To search in the message body type your keywords without any special formatting. To search in specific fields, prepend your search keyword with "field:" like so:

subject:helloooo or subject:"call for help" or "You remind me
today of a small, Mexican chihuahua."

not ((from:unrealistic and (to:complex or not query )) or
flags:seen,draft)

alladdresses:mailing@example.com and cc:me@example.com

Boolean operators are or, and and not (alias: !). String keywords with spaces must be quoted. Quotes should always be escaped. 🙈

🚨 Important Notice about IMAP/JMAP 🚨

To prevent downloading all your messages from your IMAP/JMAP server, don't set search_backend to sqlite3. meli will relay your queries to the IMAP server. Expect a delay between query and response. Sqlite3 on the contrary at reasonable mailbox sizes should have a non noticeable delay. ⏳

📜 QUERY ABNF SYNTAX 📜

  • query = "(" query ")" | from | to | cc | bcc | message_id | in_reply_to | references | header | all_addresses | subject | flags | has_attachment | query "or" query | query "and" query | not query
  • not = "not" | "!"
  • has_attachment = "has:attachment" | "has:attachments"
  • quoted = ALPHA / SP *(ALPHA / DIGIT / SP)
  • term = ALPHA *(ALPHA / DIGIT) | DQUOTE quoted DQUOTE
  • tagname = term
  • flagval = "passed" | "replied" | "seen" | "read" | "junk" | "trash" | "trashed" | "draft" | "flagged" | tagname
  • flagterm = flagval | flagval "," flagterm
  • flags = "flag:" flag | "flags:" flag | "tag:" flag | "tags:" flag | "is:" flag
  • from = "from:" term
  • to = "to:" term
  • cc = "cc:" term
  • bcc = "bcc:" term
  • message_id = "message-id:" term | "msg-id:" term
  • in_reply_to = "in-reply-to:" term
  • references = "references:" term
  • header = "header:" field_name "," field_value
  • field_name = term
  • field_value = term
  • all_addresses = "all-addresses:" term
  • subject = "subject:" term

🚩 FLAGS 🚩

meli supports the basic maildir flags: passed, replied, seen, trashed, draft and flagged. Flags can be searched with the ‘flags:’ prefix in a search query, and can be modified by

flag set FLAG

and

flag unset FLAG

🏷️ TAGS 🏷️

meli supports tagging in notmuch and IMAP/JMAP backends. Tags can be searched with the ‘tags:’ or ‘flags:’ prefix in a search query, and can be modified by

tag add TAG

and

tag remove TAG

(see meli.conf(5) TAGS, settings colors and ignore_tags for how to set tag colors and tag visibility) 🎨

✍️ COMPOSING ✍️

📝 Opening the message Composer tab 📝

To create a new mail message, press ⟨m⟩ (shortcuts.listing.new_mail) while viewing a mailbox. To reply to a mail, press ⟨R⟩ (shortcuts.envelope_view.reply). Both these actions open the mail composer view in a new tab. slay. 💅

⌨️ Editing text ⌨️

  • Edit the header fields by selecting with the arrow keys and pressing ⟨Enter⟩ (shortcuts.general.focus_in_text_field) to enter INSERT mode and Esc key to exit.
  • At any time you may press ⟨e⟩ (shortcuts.composing.edit) to launch your editor (see meli.conf(5) COMPOSING, setting editor_command for how to select which editor to launch).
  • Your editor can be used in meli's embed terminal emulator by setting embed to true in your composing settings (You can return to meli at any time by pressing ⟨Ctrl-Z⟩)
  • When launched, your editor captures all input until it exits or stops.
  • To stop your editor and return to meli press ⟨Ctrl-z⟩ and to resume editing press the edit command again.

📎 Attachments 📎

Attachments may be handled with the add-attachment, remove-attachment commands (see below).

🚀 Sending 🚀

Finally, pressing ⟨s⟩ (shortcuts.composing.send_mail) will send your message according to your settings (see meli.conf(5) ACCOUNTS, setting name send_mail). With no Draft or Sent mailbox, meli tries first saving mail in your INBOX and then at any other mailbox. On complete failure to save your draft or sent message it will be saved in your tmp directory instead and you will be notified of its location. 😭

🗒️ Drafts 🗒️

To save your draft without sending it, issue COMMAND close and select 'save as draft'.

To open a draft for further editing, select your draft in the mail listing and press edit. 🦋

💌 CONTACTS 💌

okay so meli is lowkey a social butterfly and supports three whole kinds of contact backends, pick your fighter:

  1. an internal format that gets saved under $XDG_DATA_HOME/meli/account_name/contacts.
  2. vCard files (v3, v4) through the vcard_folder option in the account section. The path defined as vcard_folder can hold multiple vCards per file. They are loaded read only — so no writing back, bestie, look don't touch.
  3. a mutt(1) compatible alias file in the option mutt_alias_file.

if you wanna see the full account contact configuration values, go check meli.conf(5) ACCOUNTS. it's giving ✨documentation✨.

🎭 MODES 🎭

  • NORMAL — is the default mode, the main character, the one you start in.
  • COMMAND — commands are issued in COMMAND mode, by default started with ⟨:⟩ (shortcuts.general.enter_command_mode) and exited with the ⟨Esc⟩ key.
  • EMBED — is the mode of the embed terminal emulator.
  • INSERT — captures all input as text input, and is exited with the Esc key.

🕹️ COMMAND 🕹️

📬 Mail listing commands 📬

  • set plain | threaded | compact | conversations — set the way mailboxes are displayed. here's the tea on each one:
    • conversations — shows one entry per thread.
    • compact — shows one row per thread.
    • threaded — shows threads as a tree structure.
    • plain — shows one row per mail, regardless of threading.
  • sort [subject | date] asc | desc — sort mail listing.
  • subsort [subject | date] asc | desc — sorts only the first level of replies.
  • go n — where n is a mailbox prefixed with the n number in the side menu for the current account.
  • toggle thread_snooze — don't issue notifications for thread under cursor in thread listing.
  • search STRING — search mailbox with STRING query. Escape exits search results.
  • select STRING — select threads matching STRING query.
  • clear-selection — Clear current selection.
  • set seen | unseen — Set seen status of message.
  • import FILEPATH MAILBOX_PATH — Import mail from file into given mailbox.
  • copyto, moveto MAILBOX_PATH — Copy or move to other mailbox.
  • copyto, moveto ACCOUNT MAILBOX_PATH — Copy or move to another account's mailbox.
  • delete — Delete selected entries.
  • export-mbox FILEPATH — Export selected threads to mboxcl2 file.
  • create-mailbox ACCOUNT MAILBOX_PATH — create mailbox with given path. Be careful with backends and separator sensitivity (eg IMAP) 👀.
  • subscribe-mailbox ACCOUNT MAILBOX_PATH — subscribe to mailbox with given path.
  • unsubscribe-mailbox ACCOUNT MAILBOX_PATH — unsubscribe to mailbox with given path.
  • rename-mailbox ACCOUNT MAILBOX_PATH_SRC MAILBOX_PATH_DEST — rename mailbox.
  • delete-mailbox ACCOUNT MAILBOX_PATH — deletes mailbox in the mail backend. This action is irreversible. like no undo, no takebacks, it's gone fr fr.

👀 Mail view commands 👀

  • pipe EXECUTABLE [ARGS] — pipe pager contents to binary.
  • filter EXECUTABLE [ARGS] — filter and display pager contents through command.
  • filter — select a filter from pager.named_filters configuration value (See meli.conf(5) PAGER for its syntax).
  • list-post — post in list of viewed envelope.
  • list-unsubscribe — unsubscribe automatically from list of viewed envelope.
  • list-archive — open list archive with xdg-open.

✍️ Composing mail commands ✍️

  • mailto MAILTO_ADDRESS — Opens a composer tab with initial values parsed from the mailto: address.
  • add-attachment PATH — in composer, add PATH as an attachment.
  • add-attachment < CMD ARGS — in composer, pipe CMD ARGS output into an attachment.
  • add-attachment-file-picker — Launch command defined in the configuration value file_picker_command in meli.conf(5) TERMINAL.
  • add-attachment-file-picker < CMD ARGS — Launch command CMD ARGS. The command should print file paths in stdout, separated by NUL bytes. Example usage with fzf(1):
add-attachment-file-picker < fzf --print0
  • remove-attachment INDEX — remove attachment with given index.
  • toggle sign — toggle between signing and not signing this message. If the gpg invocation fails then the mail won't be sent. See meli.conf(5) PGP for PGP configuration.
  • save-draft — saves a copy of the draft in the Draft folder.

🛠️ Generic commands 🛠️

  • open-in-tab — opens envelope view in new tab.
  • close — closes closeable tabs.
  • setenv KEY=VALUE — set environment variable KEY to VALUE.
  • printenv KEY — print environment variable KEY.
  • quit — Quits meli. bye bestie 🫶.
  • reload-config — Reloads configuration but only if account configuration is unchanged. Useful if you want to reload some settings without restarting meli.
  • manage-jobs — Inspect background jobs.
  • manage-mailboxes — Inspect all mailboxes of an account, subscribed or not. Pressing the ⟨Enter⟩ (shortcuts.general.open_entry) shortcut allows you to rename, move, toggle subscription and delete the mailbox under the cursor.

🚪 EXIT STATUS 🚪

meli exits with 0 on a successful run. Other exit statuses are:

  • 1 — catchall for general errors.
  • 101 — process panic 💀.

🌍 ENVIRONMENT 🌍

  • EDITOR — Specifies the editor to use.
  • MELI_CONFIG — Override the configuration file.
  • NO_COLOR — When defined (regardless of its value), prevents the addition of ANSI color. The configuration value use_color overrides this.

📂 FILES 📂

meli uses the following parts of the XDG standard:

  • XDG_CONFIG_HOME — defaults to ~/.config/.
  • XDG_CACHE_HOME — defaults to ~/.cache/.

and appropriates the following locations:

  • $XDG_CONFIG_HOME/meli/ — User configuration directory.
  • $XDG_CONFIG_HOME/meli/config.toml — User configuration file, see meli.conf(5) for its syntax and values.
  • $XDG_CACHE_HOME/meli/* — Internal cached data used by meli.
  • $XDG_DATA_HOME/meli/* — Internal data used by meli.
  • $XDG_DATA_HOME/meli/meli.log — Operation log.
  • /tmp/meli/* — Temporary files generated by meli.

Mailcap entries are searched for in the following files, in this order:

  1. $XDG_CONFIG_HOME/meli/mailcap
  2. $XDG_CONFIG_HOME/.mailcap
  3. $HOME/.mailcap
  4. /etc/mailcap
  5. /usr/etc/mailcap
  6. /usr/local/etc/mailcap

🌈 STANDARDS ✨

ok bestie, here's the lore — everything meli is built on top of, fr fr. These are the specs, RFCs and vibes it respects 💖

🔎 SEE ALSO 👀

the whole friend group 💞 go read these next:

💅 AUTHORS 👑

Copyright 2017–2024 Manos Pitsidianakis <manos@pitsidianak.is>

Released under the GPL, version 3 or greater. This software carries no warranty of any kind. (See COPYING for full copyright and warranty notices.)

🫶 no warranty bestie, that's just how it is — read COPYING for the full tea.

and that's the whole page, bestie!! 🌸 ty for reading all the way down, you're literally the main character 💖 go send some emails, you've earned it 🎀

this beauty came from the Debian build, dated March 10, 2024, and it lives in section MELI(1) — no cap ✨👑

📦 where this page comes from