meli/meli.1

.\" meli - meli.1
.\"
.\" Copyright 2017-2019 Manos Pitsidianakis
.\"
.\" This file is part of meli.
.\"
.\" meli is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" meli is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with meli. If not, see <http://www.gnu.org/licenses/>.
.\"
.Dd July 29, 2019
.Dt MELI 1
.Os Linux
.Sh NAME
.Nm meli
.Nd Meli Mail User Agent. meli is the Greek word for honey.
.Sh SYNOPSIS
.Nm
.Op Fl -help | h
.Op Fl -version | v
.Op Fl -create-config Op Ar path
.Op Fl -config Ar path
.Sh DESCRIPTION
Experimental terminal mail client
.Bl -tag -width flag -offset indent
.It Fl -help, h
Show help message and exit.
.It Fl -version, v
Show version and exit.
.It Fl -create-config Op Ar path
Create configuration file in
.Pa path
if given, or at
.Pa $XDG_CONFIG_HOME/meli/config
.It Fl -config Ar path
Start meli with given configuration file.
.El
.Sh STARTING WITH meli
When launched for the first time, 
.Nm
will search for its configuration directory,
.Pa $XDG_CONFIG_HOME/meli/ Ns
\&. If it doesn't exist, you will be asked if you want to create one along with a sample configuration. The sample configuration
.Pa $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
.Xr meli.conf 5
for the available configuration options.
.Pp
At any time, you can press
.Cm \&?
to show a searchable list of all available actions and shortcuts, along with every possible setting and command that your version supports.
.Pp
The main visual navigation tool is the left-side sidebar. The menu's visibility can be toggled (default shortcut
.Cm ` Ns
).
.Pp
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).
.Pp
If you're using a light color palette in your terminal, you can set
.Em theme = "light"
in the
.Em terminal
section of your configuration.
.Bd -literal
         ^^      .-=-=-=-.  ^^
     ^^        (`-=-=-=-=-`)         ^^
             (`-=-=-=-=-=-=-`)  ^^         ^^
       ^^   (`-=-=-=-=-=-=-=-`)   ^^
           ( `-=-=-=-(@)-=-=-` )      ^^
           (`-=-=-=-=-=-=-=-=-`)  ^^
           (`-=-=-=-=-=-=-=-=-`)          ^^
           (`-=-=-=-=-=-=-=-=-`)
    ^^     (`-=-=-=-=-=-=-=-=-`)  ^^
       ^^   (`-=-=-=-=-=-=-=-`)          ^^
             (`-=-=-=-=-=-=-`)  ^^
      ^^       (`-=-=-=-=-`)
                `-=-=-=-=-`          ^^
.Ed
.Sh VIEWING MAIL
Open attachments by typing their index in the attachments list and then
.Cm a Ns
\&.
.Ns
.Nm
will attempt to open text inside its pager and other content via
.Cm xdg-open Ns
\&. Press
.Cm m
instead to use the mailcap entry for the MIME type of the attachment, if any. See
.Sx FILES
for the location of the mailcap files and 
.Xr mailcap 5
for their syntax.
.Sh COMPOSING
To send mail, press
.Cm m
while viewing the appropriate account to open a new composing tab. To reply to a mail, press
.Cm R Ns
\&. You can edit some of the header fields from within the view, by selecting with the arrow keys and pressing
.Cm enter
to enter
.Ar INSERT
mode. At any time you can press
.Cm e
to launch your editor (see
.Xr meli.conf 5
.Em COMPOSING
for how to select which editor to launch). Attachments can be handled with the
.Em add-attachment Ns
,
.Em remove-attachment
commands (see below). Finally, pressing
.Ar s
will send your message by piping it into a binary of your choosing (see
.Xr meli.conf 5
.Em COMPOSING Ns
, setting
.Em mailer_cmd Ns
). To save your draft without sending it, issue command
.Cm close
and select 'save as draft'.
.Pp
If there is no Draft or Sent folder, 
.Nm 
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
.Em tmp
directory instead and you will be notified of its location.
.Pp
To open a draft for editing later, select your draft in the mail listing and press
.Cm e Ns
\&.
.Sh SEARCH
Each e-mail storage backend has its default search method.
.Em IMAP
uses the SEARCH command,
.Em notmuch
uses libnotmuch and
.Em Maildir/mbox
have to perform a very slow and I/O bound linear search. Thus it is advised to use a cache on
.Em Maildir/mbox
accounts.  
.Nm Ns
, 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
.Em cache_type
to
.Em sqlite3 
in the configuration file and to create the sqlite3 index issue command
.Ic index Ar ACCOUNT_NAME Ns \&.

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:
.Pp
.D1 subject:helloooo or subject:\&"call for help\&" or \&"You remind me today of a small, Mexican chihuahua.\&"
.Pp
.D1 not ((from:unrealistic and (to:complex or not "query")) or flags:seen,draft)
.Pp
.D1 alladdresses:mailing@list.tld and cc:me@domain.tld
.Pp
Boolean operators are
.Em or Ns
,
.Em and
and
.Em not
.Po
alias: 
.Em !
.Pc
String keywords with spaces must be quoted. Quotes should always be escaped.

.Sy Important Notice about IMAP

To prevent downloading all your messages from your IMAP server, don't set 
.Em cache_type
to
.Em sqlite3 Ns
\&. 
.Nm
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.
.Sh EXECUTE mode
Commands are issued in EXECUTE mode, by default started with the space character and exited with Escape key.
.Pp
the following commands are valid in the mail listing context:
.Bl -tag -width "rename-folder ACCOUNT FOLDER_PATH_SRC FOLDER_PATH_DEST"
.It Ic set Ar plain | threaded | compact | conversations
set the way mailboxes are displayed
.Bl -tag -width "conversations" -compact
.It Cm plain
shows one row per mail, regardless of threading
.It Cm threaded
shows threads as a tree structure, with one row per thread entry
.It Cm conversations
shows one entry per thread
.It Cm compact
shows one row per thread
.El
.It Ic sort Ar subject | date \  Ar asc | desc
sort mail listing
.It Ic subsort Ar subject | date \  Ar asc | desc
sorts only the first level of replies.
.It Ic go Ar n
where
.Ar n
is a mailbox prefixed with the
.Ar n
number in the side menu for the current account
.It Ic toggle_thread_snooze
don't issue notifications for thread under cursor in thread listing
.It Ic filter Ar STRING
filter mailbox with
.Ar STRING
key. Escape exits filter results
.It Ic set read, set unread
.It Ic create-folder Ar ACCOUNT Ar FOLDER_PATH
create folder with given path. be careful with backends and separator sensitivity (eg IMAP)
.It Ic subscribe-folder Ar ACCOUNT Ar FOLDER_PATH
subscribe to folder with given path
.It Ic unsubscribe-folder Ar ACCOUNT Ar FOLDER_PATH
unsubscribe to folder with given path
.It Ic rename-folder Ar ACCOUNT Ar FOLDER_PATH_SRC Ar FOLDER_PATH_DEST
rename folder
.It Ic delete-folder Ar ACCOUNT Ar FOLDER_PATH
delete folder
.El
.Pp
envelope view commands:
.Bl -tag -width "rename-folder ACCOUNT FOLDER_PATH_SRC FOLDER_PATH_DEST"
.It Cm pipe Ar EXECUTABLE Ar ARGS
pipe pager contents to binary
.It Cm list-post
post in list of currently viewed envelope
.It Cm list-unsubscribe
unsubscribe automatically from list of currently viewed envelope
.It Cm list-archive
open list archive with
.Cm xdg-open
.El
.Pp
composing mail commands:
.Bl -tag -width "rename-folder ACCOUNT FOLDER_PATH_SRC FOLDER_PATH_DEST"
.It Ic add-attachment Ar PATH
in composer, add
.Ar PATH
as an attachment
.It Ic remove-attachment Ar INDEX
remove attachment with given index
.It Ic toggle sign
toggle between signing and not signing this message. If the gpg invocation fails then the mail won't be sent.
.El
.Pp
generic commands:
.Bl -tag -width "rename-folder ACCOUNT FOLDER_PATH_SRC FOLDER_PATH_DEST"
.It Cm open-in-tab
opens envelope view in new tab
.It Ic close
closes closeable tabs
.It Cm setenv Ar KEY=VALUE
set environment variable
.Ar KEY
to
.Ar VALUE
.It Cm printenv Ar KEY
print environment variable
.Ar KEY
.El
.Sh SHORTCUTS
Non-complete list of shortcuts and their default values.
.Bl -tag -width "rename-folder ACCOUNT FOLDER_PATH_SRC FOLDER_PATH_DEST"
.It Cm open_thread
\&'\\n'
.It Cm exit_thread
\&'i'
.It Cm create_contact
\&'c'
.It Cm edit_contact
\&'e'
.It Cm prev_page
PageUp,
.It Cm next_page
PageDown
.It Cm prev_folder
\&'K'
.It Cm next_folder
\&'J'
.It Cm prev_account
\&'l'
.It Cm next_account
\&'h'
.It Cm new_mail
\&'m'
.It Cm scroll_up
\&'k'
.It Cm scroll_down
\&'j'
.It Cm page_up
PageUp
.It Cm page_down
PageDown
.It Cm toggle-menu-visibility
\&'`'
.It Cm select
\&'v'
.El
.Bl -tag -width "rename-folder ACCOUNT FOLDER_PATH_SRC FOLDER_PATH_DEST"
.It Cm `
toggles hiding of sidebar in mail listings
.It Cm \&?
opens up a shortcut window that shows available actions in the current component you are using (eg mail listing, contact list, mail composing)
.It Cm m
starts a new mail composer
.It Cm R
replies to the currently viewed mail.
.It Cm u
displays numbers next to urls in the body text of an email and
.Ar n Ns Cm g
opens the
.Ar n Ns
th
url with xdg-open
.It Ar n Ns Cm a
opens the
.Ar n Ns
th
attachment.
.It Ar n Ns Cm m
opens the
.Ar n Ns
th
attachment according to its mailcap entry.
.It Cm v
(un)selects mail entries in mail listings
.El
.Sh EXIT STATUS
.Nm
exits with 0 on a successful run. Other exit statuses are:
.Bl -tag -width 2n
.It 1
catchall for general errors
.El
.Sh ENVIRONMENT
.Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
.It Ev EDITOR
Specifies the editor to use
.It Ev MELI_CONFIG
Override the configuration file
.El
.Sh FILES
.Nm
uses the following parts of the XDG standard:
.Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
.It Ev XDG_CONFIG_HOME
defaults to
.Pa ~/.config/
.It Ev XDG_CACHE_HOME
defaults to
.Pa ~/.cache/
.El
.Pp
and appropriates the following locations:
.Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
.It Pa $XDG_CONFIG_HOME/meli/
User configuration directory.
.It Pa $XDG_CONFIG_HOME/meli/config
User configuration file. See
.Xr meli.conf 5
for its syntax and values.
.It Pa $XDG_CONFIG_HOME/meli/hooks/*
Reserved for event hooks.
.It Pa $XDG_CONFIG_HOME/meli/plugins/*
Reserved for plugin files.
.It Pa $XDG_CACHE_HOME/meli/*
Internal cached data used by meli.
.It Pa $XDG_DATA_HOME/meli/*
Internal data used by meli.
.It Pa $XDG_DATA_HOME/meli/meli.log
Operation log.
.It Pa /tmp/meli/*
Temporary files generated by
.Nm Ns
\&.
.El
.Pp
Mailcap entries are searched for in the following files, in this order:
.Pp
.Bl -enum -compact -offset indent
.It 
.Pa $XDG_CONFIG_HOME/meli/mailcap
.It
.Pa $XDG_CONFIG_HOME/.mailcap
.It
.Pa $HOME/.mailcap
.It
.Pa /etc/mailcap
.It
.Pa /usr/etc/mailcap
.It
.Pa /usr/local/etc/mailcap
.El
.Sh SEE ALSO
.Xr meli.conf 5 ,
.Xr xdg-open 1 ,
.Xr mailcap 5
.Sh CONFORMING TO
XDG Standard
.Aq https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html Ns
, maildir
.Aq https://cr.yp.to/proto/maildir.html Ns
, IMAPv4rev1 RFC3501.
.Sh AUTHORS
Copyright 2017-2019
.An Manos Pitsidianakis Aq 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.)
.Pp
.Aq https://meli.delivery