documentation

Quick start tutorial

Follow the installation instructions in the README.

Launch meli with no arguments, and you will be asked if you want to create a sample configuration.

The sample configuration (by default in ~/.config/meli/config) includes comments with the basic settings required for setting up accounts allowing you to copy and edit right away. See meli.conf(5) for the available configuration options.

The main screen when you launch meli is the INBOX of the first account you have configured.

At any time, you can press ? to show a list of all available actions and shortcuts, along with every possible setting and command that your version supports.

Press T to cycle between tabs or Alt + 19 to choose.

Press q to exit.


meli(1)

NAME

meliMeli Mail User Agent. meli is the Greek word for honey.

SYNOPSIS

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

DESCRIPTION

Experimental terminal mail client
--help, -h
Show help message and exit.
--version, -v
Show version and exit.
--create-config [path]
Create configuration file in path if given, or at $XDG_CONFIG_HOME/meli/config
--config path
Start meli with given configuration file.

STARTING WITH meli

When launched for the first time, meli will search for its configuration directory, $XDG_CONFIG_HOME/meli/. If it doesn't exist, you will be asked if you want to create one along with a sample configuration. The sample configuration $XDG_CONFIG_HOME/meli/config includes comments with the basic settings required for setting up accounts allowing you to copy and edit right away. See meli.conf(5) for the available configuration options.
At any time, you can press ? to show a searchable list of all available actions and shortcuts, along with every possible setting and command that your version supports.
The main visual navigation tool is the left-side sidebar. The menu's visibility can be toggled (default shortcut `).
The view into each folder has 4 modes: plain, threaded, conversations and compact. Plain views each mail indvidually, threaded shows their thread relationship visually, and conversations includes one entry per thread of emails (compact is one row per thread).
If you're using a light color palette in your terminal, you can set theme = light in the terminal section of your configuration.
         ^^      .-=-=-=-.  ^^ 
     ^^        (`-=-=-=-=-`)         ^^ 
             (`-=-=-=-=-=-=-`)  ^^         ^^ 
       ^^   (`-=-=-=-=-=-=-=-`)   ^^ 
           ( `-=-=-=-(@)-=-=-` )      ^^ 
           (`-=-=-=-=-=-=-=-=-`)  ^^ 
           (`-=-=-=-=-=-=-=-=-`)          ^^ 
           (`-=-=-=-=-=-=-=-=-`) 
    ^^     (`-=-=-=-=-=-=-=-=-`)  ^^ 
       ^^   (`-=-=-=-=-=-=-=-`)          ^^ 
             (`-=-=-=-=-=-=-`)  ^^ 
      ^^       (`-=-=-=-=-`) 
                `-=-=-=-=-`          ^^

VIEWING MAIL

Open attachments by typing their index in the attachments list and then a. meli will attempt to open text inside its pager and other content via xdg-open. Press m 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.

COMPOSING

To send mail, press m while viewing the appropriate account to open a new composing tab. To reply to a mail, press R. You can edit some of the header fields from within the view, by selecting with the arrow keys and pressing enter to enter INSERT mode. At any time you can press e to launch your editor (see meli.conf(5) COMPOSING for how to select which editor to launch). Attachments can be handled with the add-attachment, remove-attachment commands (see below). Finally, pressing s will send your message by piping it into a binary of your choosing (see meli.conf(5) COMPOSING, setting mailer_cmd). To save your draft without sending it, issue command close and select 'save as draft'.
If there is no Draft or Sent folder, meli tries first saving mail in your INBOX and then at any other folder. 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.
To open a draft for editing later, select your draft in the mail listing and press e.

SEARCH

Each e-mail storage backend has its default search method. IMAP uses the SEARCH command, notmuch uses libnotmuch and Maildir/mbox have to perform a very slow and I/O bound linear search. Thus it is advised to use a cache 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 cache_type to sqlite3 in the configuration file and to create the sqlite3 index issue command index 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@list.tld and cc:me@domain.tld
Boolean operators are or, and and not (alias: !) String keywords with spaces must be quoted. Quotes should always be escaped.
 
Important Notice about IMAP
 
To prevent downloading all your messages from your IMAP server, don't set cache_type 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 noticable delay.

EXECUTE mode

Commands are issued in EXECUTE mode, by default started with the space character and exited with Escape key.
the following commands are valid in the mail listing context:
set plain | threaded | compact | conversations
set the way mailboxes are displayed
plain
shows one row per mail, regardless of threading
threaded
shows threads as a tree structure, with one row per thread entry
conversations
shows one entry per thread
compact
shows one row per thread
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
filter STRING
filter mailbox with STRING key. Escape exits filter results
set read, set unread
create-folder ACCOUNT FOLDER_PATH
create folder with given path. be careful with backends and separator sensitivity (eg IMAP)
subscribe-folder ACCOUNT FOLDER_PATH
subscribe to folder with given path
unsubscribe-folder ACCOUNT FOLDER_PATH
unsubscribe to folder with given path
rename-folder ACCOUNT FOLDER_PATH_SRC FOLDER_PATH_DEST
rename folder
delete-folder ACCOUNT FOLDER_PATH
delete folder
envelope view commands:
pipe EXECUTABLE ARGS
pipe pager contents to binary
list-post
post in list of currently viewed envelope
list-unsubscribe
unsubscribe automatically from list of currently viewed envelope
list-archive
open list archive with xdg-open
composing mail commands:
add-attachment PATH
in composer, add PATH as an attachment
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.
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

SHORTCUTS

Non-complete list of shortcuts and their default values.
open_thread
'\n'
exit_thread
'i'
create_contact
'c'
edit_contact
'e'
prev_page
PageUp,
next_page
PageDown
prev_folder
'K'
next_folder
'J'
prev_account
'l'
next_account
'h'
new_mail
'm'
scroll_up
'k'
scroll_down
'j'
page_up
PageUp
page_down
PageDown
toggle-menu-visibility
'`'
select
'v'
`
toggles hiding of sidebar in mail listings
?
opens up a shortcut window that shows available actions in the current component you are using (eg mail listing, contact list, mail composing)
m
starts a new mail composer
R
replies to the currently viewed mail.
u
displays numbers next to urls in the body text of an email and ng opens the nth url with xdg-open
na
opens the nth attachment.
nm
opens the nth attachment according to its mailcap entry.
v
(un)selects mail entries in mail listings

EXIT STATUS

meli exits with 0 on a successful run. Other exit statuses are:
1
catchall for general errors

ENVIRONMENT

EDITOR
Specifies the editor to use
MELI_CONFIG
Override the configuration file

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
User configuration file. See meli.conf(5) for its syntax and values.
$XDG_CONFIG_HOME/meli/hooks/*
Reserved for event hooks.
$XDG_CONFIG_HOME/meli/plugins/*
Reserved for plugin files.
$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

CONFORMING TO

XDG Standard ⟨https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html⟩, maildir ⟨https://cr.yp.to/proto/maildir.html⟩, IMAPv4rev1 RFC3501.

AUTHORS

Copyright 2017-2019 Manos Pitsidianakis ⟨epilys@nessuent.xyz⟩ Released under the GPL, version 3 or greater. This software carries no warranty of any kind. (See COPYING for full copyright and warranty notices.)
⟨https://meli.delivery⟩

meli.conf(5) [go back]

NAME

meli.confconfiguration file for the Meli Mail User Agent

SYNOPSIS

$XDG_CONFIG_HOME/meli/config

DESCRIPTION

Configuration for meli is written in TOML. Few things to consider before writing TOML (quoting the spec):
  • TOML is case sensitive.
  • A TOML file must be a valid UTF-8 encoded Unicode document.
  • Whitespace means tab (0x09) or space (0x20).
  • Newline means LF (0x0A) or CRLF (0x0D 0x0A).
Refer to TOML documentation for valid TOML syntax.

SECTIONS

The top level sections of the config are accounts, shortcuts, notifications, pager, composing, pgp, terminal.
example configuration
# Setting up a Maildir account 
[accounts.account-name] 
root_folder = "/path/to/root/folder" 
format = "Maildir" 
index_style = "Compact" 
identity="email@address.tld" 
subscribed_folders = ["folder", "folder/Sent"] 
display_name = "Name" 
 
# Set folder-specific settings 
  [accounts.account-name.folders] 
  "INBOX" = { rename="Inbox" } #inline table 
  "drafts" = { rename="Drafts" } #inline table 
  [accounts.account-name.folders."foobar-devel"] # or a regular table 
    ignore = true # don't show notifications for this folder 
 
# Setting up an mbox account 
[accounts.mbox] 
root_folder = "/var/mail/username" 
format = "mbox" 
index_style = "Compact" 
identity="username@hostname.local" 
 
[pager] 
filter = "/usr/bin/pygmentize" 
html_filter = "w3m -I utf-8 -T text/html" 
 
[notifications] 
script = "notify-send" 
 
[composing] 
# required for sending e-mail 
mailer_cmd = 'msmtp --read-recipients --read-envelope-from' 
editor_cmd = 'vim +/^$' 
 
[shortcuts] 
scroll_up = 'k' 
scroll_down = 'j' 
page_up = PageUp 
page_down = PageDown 
 
[terminal] 
theme = "light"
available options are listed below. default values are shown in parentheses.

ACCOUNTS

root_folder String
the backend-specific path of the root_folder, usually INBOX.
format String [maildir mbox imap notmuch]
the format of the mail backend.
subscribed_folders [String,]
an array of folder paths to display in the UI. Paths are relative to the root folder (eg "INBOX/Sent", not "Sent")
identity String
your e-mail address that is inserted in the From: headers of outgoing mail
index_style String
set the way mailboxes are displayed
plain
shows one row per mail, regardless of threading
threaded
shows threads as a tree structure, with one row per thread entry
conversations
shows one entry per thread
compact
shows one row per thread
display_name String
(optional) a name which can be combined with your address: "Name <email@address.tld>"
read_only boolean
attempt to not make any changes to this account. (false)
cache_type String
choose which cache backend to use. Available options are 'none' and 'sqlite3' (sqlite3)
folders folder_config
(optional) configuration for each folder. Its format is described below in FOLDERS.

notmuch only

root_folder points to the directory which contains the .notmuch/ subdirectory. notmuch folders are virtual, since they are defined by user-given notmuch queries. Thus you have to explicitly state the folders you want in the folders field and set the query property to each of them. Example:
[accounts.notmuch] 
format = "notmuch" 
... 
  [accounts.notmuch.folders] 
  "INBOX" = {  query="tag:inbox", subscribe = true } 
  "Drafts" = {  query="tag:draft", subscribe = true } 
  "Sent" = {  query="from:username@server.tld from:username2@server.tld", subscribe = true }

IMAP only

IMAP specific options are:
server_hostname String
example: “mail.example.tld”
server_username String
server_password String
server_port number
(optional) (143)
use_starttls boolean
(optional) if port is 993 and use_starttls is unspecified, it becomes false by default. (true)
danger_accept_invalid_certs boolean
(optional) do not validate TLS certificates. (false)

FOLDERS

rename String
(optional) show a different name for this folder in the UI
autoload boolean
(optional) load this folder on startup (not functional yet)
subscribe boolean
(optional) watch this folder for updates (true)
ignore boolean
(optional) silently insert updates for this folder, if any (false)
usage boolean
(optional) special usage of this folder. valid values are:
  • Normal
  • Inbox
  • Archive
  • Drafts
  • Flagged
  • Junk
  • Sent
  • Trash
otherwise usage is inferred from the folder title.
conf_override boolean
(optional) override global settings for this folder. available sections to override are pager, notifications, shortcuts, composing and the account options identity and index_style. example:
[accounts."imap.domain.tld".folders."INBOX"] 
  index_style = "plain" 
  [accounts."imap.domain.tld".folders."INBOX".pager] 
    filter = ""

COMPOSING

mailer_cmd String
command to pipe new mail to, exit code must be 0 for success.
editor_cmd String
command to launch editor. Can have arguments. Draft filename is given as the last argument. If it's missing, the environment variable $EDITOR is looked up.
embed boolean
(optional) embed editor within meli (false)

SHORTCUTS

Shortcuts can take the following values: “Backspace” “Left” “Right” “Up” “Down” “Home” “End” “PageUp” “PageDown” “Delete” “Insert” “Esc” and “char”, where char is a single character string.
prev_page
Go to previous page.
next_page
Go to next page.
prev_folder
Go to previous folder.
next_folder
Go to next folder.
prev_account
Go to previous account.
next_account
Go to next account.
new_mail
Start new mail draft in new tab
open_thread
Open thread.
exit_thread
Exit thread view
scroll_up
Scroll up pager.
scroll_down
Scroll down pager.
page_up
Go to previous pager page
page_down
Go to next pager pag
create_contact
Create new contact.
edit_contact
Edit contact under cursor

NOTIFICATIONS

enable boolean
enable freedesktop-spec notifications. this is usually what you want (true)
script String
(optional) script to pass notifications to, with title as 1st arg and body as 2nd (none)
xbiff_file_path String
(optional) file that gets its size updated when new mail arrives (none)
play_sound boolean
(optional) play theme sound in notifications if possible (false)
sound_file String
(optional) play sound file in notifications if possible (none)

PAGER

pager_context num
(optional) number of context lines when going to next page. (0)
headers_sticky boolean
(optional) always show headers when scrolling. (false)
html_filter String
(optional) pipe html attachments through this filter before display (none)
filter String
(optional) a command to pipe mail output through for viewing in pager. (none)

PGP

auto_verify_signatures boolean
auto verify signed e-mail according to RFC3156 (true)
auto_sign boolean
(optional) always sign sent messages (false)
key String
(optional) key to be used when signing/encrypting (not functional yet) (none)
gpg_binary String
(optional) gpg binary name or file location to use (gpg2)

TERMINAL

theme String
(optional) select between these themes: light / dark (dark)
ascii_drawing boolean
(optional) if true, box drawing will be done with ascii characters. (false)
window_title String
(optional) set window title in xterm compatible terminals (empty string means no window title is set) (meli)

SEE ALSO

meli(1)

CONFORMING TO

TOML Standard v.0.5.0 https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.5.0.md

AUTHORS

Copyright 2017-2019 Manos Pitsidianakis ⟨epilys@nessuent.xyz⟩ Released under the GPL, version 3 or greater. This software carries no warranty of any kind. (See COPYING for full copyright and warranty notices.)
⟨https://meli.delivery⟩

[go back]