meli/meli.1

565 lines
14 KiB
Groff
Raw Permalink Normal View History

2019-07-04 07:38:25 +03:00
.\" meli - meli.1
2019-07-29 20:23:22 +03:00
.\"
2019-07-04 07:38:25 +03:00
.\" Copyright 2017-2019 Manos Pitsidianakis
2019-07-29 20:23:22 +03:00
.\"
2019-07-04 07:38:25 +03:00
.\" This file is part of meli.
2019-07-29 20:23:22 +03:00
.\"
2019-07-04 07:38:25 +03:00
.\" 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.
2019-07-29 20:23:22 +03:00
.\"
2019-07-04 07:38:25 +03:00
.\" 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.
2019-07-29 20:23:22 +03:00
.\"
2019-07-04 07:38:25 +03:00
.\" You should have received a copy of the GNU General Public License
.\" along with meli. If not, see <http://www.gnu.org/licenses/>.
2019-07-29 20:23:22 +03:00
.\"
.Dd July 29, 2019
2019-07-04 07:38:25 +03:00
.Dt MELI 1
2019-11-22 13:12:44 +02:00
.Os
2019-07-04 07:38:25 +03:00
.Sh NAME
2019-07-29 20:23:22 +03:00
.Nm meli
2019-11-22 13:12:44 +02:00
.Nd Meli Mail User Agent. meli is the Greek word for honey
2019-07-04 07:38:25 +03:00
.Sh SYNOPSIS
2019-11-11 22:20:16 +02:00
.Nm
2019-07-29 20:23:22 +03:00
.Op Fl -help | h
2019-08-01 12:44:30 +03:00
.Op Fl -version | v
2019-07-29 20:23:22 +03:00
.Op Fl -config Ar path
.Bl -tag -width flag -offset indent
2020-01-28 18:43:14 +02:00
.It Fl -help | h
2019-07-29 20:23:22 +03:00
Show help message and exit.
2020-01-28 18:43:14 +02:00
.It Fl -version | v
2019-08-01 12:44:30 +03:00
Show version and exit.
2020-06-07 18:02:20 +03:00
.It Fl -config Ar path
Start meli with given configuration file.
.It Cm create-config Op Ar path
2019-07-29 20:23:22 +03:00
Create configuration file in
.Pa path
if given, or at
2020-01-28 00:32:40 +02:00
.Pa $XDG_CONFIG_HOME/meli/config.toml
2020-06-07 18:02:20 +03:00
.It Cm test-config Op Ar path
Test a configuration file for syntax issues or missing options.
2020-06-07 18:02:20 +03:00
.It Cm man Op Ar page
Print documentation page and exit (Piping to a pager is recommended.)
.It Cm print-default-theme
2020-01-28 00:32:40 +02:00
Print default theme keys and values in TOML syntax, to be used as a blueprint.
2020-06-07 18:02:20 +03:00
.It Cm print-loaded-themes
2020-01-28 00:32:40 +02:00
Print all loaded themes in TOML syntax.
.It Cm view
View mail from input file.
2019-07-29 20:23:22 +03:00
.El
2020-01-28 18:43:14 +02:00
.Sh DESCRIPTION
.Nm
is a terminal mail client aiming for extensive and user-frendly configurability.
.Bd -literal
^^ .-=-=-=-. ^^
^^ (`-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-`) ^^ ^^
^^ (`-=-=-=-=-=-=-=-`) ^^
( `-=-=-=-(@)-=-=-` ) ^^
(`-=-=-=-=-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-=-=-`)
^^ (`-=-=-=-=-=-=-=-=-`) ^^
^^ (`-=-=-=-=-=-=-=-`) ^^
(`-=-=-=-=-=-=-`) ^^
^^ (`-=-=-=-=-`)
`-=-=-=-=-` ^^
2020-01-28 18:43:14 +02:00
.Ed
2019-07-04 07:38:25 +03:00
.Sh STARTING WITH meli
2019-11-22 13:12:44 +02:00
When launched for the first time,
2019-11-11 22:20:16 +02:00
.Nm
will search for its configuration directory,
2019-07-29 20:23:22 +03:00
.Pa $XDG_CONFIG_HOME/meli/ Ns
2020-01-28 18:43:14 +02:00
\&.
If it doesn't exist, you will be asked if you want to create one and presented with a sample configuration file
.Pq Pa $XDG_CONFIG_HOME/meli/config.toml
that includes the basic settings required for setting up accounts allowing you to copy and edit right away.
2020-01-28 18:43:14 +02:00
See
.Xr meli.conf 5
for the available configuration options.
2019-07-04 07:38:25 +03:00
.Pp
2019-11-22 13:12:44 +02:00
At any time, you may press
2019-07-29 20:23:22 +03:00
.Cm \&?
for a searchable list of all available actions and shortcuts, along with every possible setting and command that your version supports.
2019-07-04 07:38:25 +03:00
.Pp
The main visual navigation tool, the left-side sidebar may be toggled with
2020-01-28 18:43:14 +02:00
.Cm `
(shortcuts.listing:
2019-11-27 01:43:03 +02:00
.Ic toggle_menu_visibility Ns
2019-07-29 20:23:22 +03:00
).
2019-07-04 07:38:25 +03:00
.Pp
Each mailbox may be viewed in 4 modes:
Plain views each mail individually, Threaded shows their thread relationship visually, Conversations collapses each thread of emails into a single entry, Compact shows one row per thread.
2019-10-06 10:58:47 +03:00
.Pp
If you're using a light color palette in your terminal, you should set
2019-10-06 10:58:47 +03:00
.Em theme = "light"
in the
.Em terminal
section of your configuration.
2020-01-28 18:43:14 +02:00
See
.Xr meli-themes 5
for complete documentation on user themes.
2019-11-11 22:20:16 +02:00
.Sh VIEWING MAIL
Open attachments by typing their index in the attachments list and then
.Cm a
.Po
shortcut
.Ic open_attachment
.Pc .
2019-11-11 22:20:16 +02:00
.Nm
will attempt to open text inside its pager, and other content via
2019-11-11 22:20:16 +02:00
.Cm xdg-open Ns
2020-01-28 18:43:14 +02:00
\&.
Press
2019-11-11 22:20:16 +02:00
.Cm m
.Po
shortcut
.Ic open_mailcap
.Pc
2020-01-28 18:43:14 +02:00
instead to use the mailcap entry for the MIME type of the attachment, if any.
See
2019-11-11 22:20:16 +02:00
.Sx FILES
2019-11-22 13:12:44 +02:00
for the location of the mailcap files and
2019-11-11 22:20:16 +02:00
.Xr mailcap 5
for their syntax.
You can save individual attachments with the
.Em COMMAND
.Cm save-attachment Ar INDEX Ar path-to-file
where
.Ar INDEX
is the attachment's index in the listing.
If the zeroth 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.
2019-11-27 17:40:00 +02:00
.Sh SEARCH
Each e-mail storage backend has a default search method assigned.
2019-11-27 17:40:00 +02:00
.Em IMAP
uses the SEARCH command,
.Em notmuch
uses libnotmuch and
.Em Maildir/mbox
performs a slow linear search.
It is advised to use a search backend on
2019-11-27 17:40:00 +02:00
.Em Maildir/mbox
accounts.
.Nm Ns
, if built with sqlite3, includes the ability to perform full text search on the following fields:
.Em From ,
.Em To ,
.Em Cc ,
.Em Bcc ,
.Em In-Reply-To ,
.Em References ,
.Em Subject
and
.Em Date .
2020-01-28 18:43:14 +02:00
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 search_backend
2019-11-27 17:40:00 +02:00
to
.Em sqlite3
in the configuration file and to create the sqlite3 index issue command
.Cm index Ar ACCOUNT_NAME Ns \&.
2020-01-28 18:43:14 +02:00
.sp
2019-11-27 17:40:00 +02:00
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
2020-01-28 18:43:14 +02:00
String keywords with spaces must be quoted.
Quotes should always be escaped.
2019-11-27 17:40:00 +02:00
.sp
2019-12-13 00:13:54 +02:00
.Sy Important Notice about IMAP/JMAP
2019-11-27 17:40:00 +02:00
.sp
2019-12-13 00:13:54 +02:00
To prevent downloading all your messages from your IMAP/JMAP server, don't set
.Em search_backend
2019-11-27 17:40:00 +02:00
to
.Em sqlite3 Ns
\&.
.Nm
2020-01-28 18:43:14 +02:00
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.
.Ss QUERY ABNF SYNTAX
.Bl -bullet
.It
.Li query = \&"(\&" query \&")\&" | from | to | cc | bcc | alladdresses | subject | flags | has_attachments | query \&"or\&" query | query \&"and\&" query | not query
.It
.Li not = \&"not\&" | \&"!\&"
.It
.Li quoted = ALPHA / SP *(ALPHA / DIGIT / SP)
.It
.Li term = ALPHA *(ALPHA / DIGIT) | DQUOTE quoted DQUOTE
.It
.Li tagname = term
.It
.Li flagval = \&"passed\&" | \&"replied\&" | \&"seen\&" | \&"read\&" | \&"junk\&" | \&"trash\&" | \&"trashed\&" | \&"draft\&" | \&"flagged\&" | tagname
.It
.Li flagterm = flagval | flagval \&",\&" flagterm
.It
.Li from = \&"from:\&" term
.It
.Li to = \&"to:\&" term
.It
.Li cc = \&"cc:\&" term
.It
.Li bcc = \&"bcc:\&" term
.It
.Li alladdresses = \&"alladdresses:\&" term
.It
.Li subject = \&"subject:\&" term
.It
.Li flags = \&"flags:\&" flag | \&"tags:\&" flag | \&"is:\&" flag
.El
2019-12-08 11:26:15 +02:00
.Sh TAGS
.Nm
2020-01-28 18:43:14 +02:00
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
2019-12-08 11:26:15 +02:00
.Cm tag add TAG
and
.Cm tag remove TAG
(see
.Xr meli.conf 5 TAGS Ns
, settings
.Ic colors
and
.Ic ignore_tags
for how to set tag colors and tag visiblity)
.Sh COMPOSING
.Ss Opening the message Composer tab
To create a new mail message, press
.Cm m
(shortcut
.Ic new_mail Ns
) while viewing a mailbox.
2020-01-28 18:43:14 +02:00
To reply to a mail, press
.Cm R
.Po
shortcut
.Ic reply
.Pc .
Both these actions open the mail composer view in a new tab.
.Ss Editing text
.Bl -bullet -compact
.It
Edit the header fields by selecting with the arrow keys and pressing
.Cm enter
to enter
.Em INSERT
mode and
.Cm Esc
key to exit.
.It
2020-01-28 18:43:14 +02:00
At any time you may press
.Cm e
(shortcut
.Ic edit_mail Ns
) to launch your editor (see
2019-11-27 01:43:03 +02:00
.Xr meli.conf 5 COMPOSING Ns
, setting
.Ic editor_command
2020-01-28 18:43:14 +02:00
for how to select which editor to launch).
.It
Your editor can be used in
.Nm Ns
\&'s embed terminal emulator by setting
.Ic embed
to
.Em true
in your composing settings.
.It
When launched, your editor captures all input until it exits or stops.
.It
To stop your editor and return to
.Nm
press Ctrl-z and to resume editing press the
.Ic edit_mail
command again
.Po
default
.Em e
.Pc .
.El
.Ss Attachments
2020-01-28 18:43:14 +02:00
Attachments may be handled with the
.Cm add-attachment Ns
,
.Cm remove-attachment
2020-01-28 18:43:14 +02:00
commands (see below).
.Ss Sending
2020-01-28 18:43:14 +02:00
Finally, pressing
2019-11-22 13:12:44 +02:00
.Cm s
(shortcut
.Ic send_mail Ns
) will send your message according to your settings
2020-07-15 15:19:27 +03:00
.Po
see
2019-11-22 13:12:44 +02:00
.Xr meli.conf 5 COMPOSING Ns
, setting
2020-07-15 15:19:27 +03:00
.Ic send_mail
.Pc Ns
\&.
With no Draft or Sent mailbox,
2019-11-22 13:12:44 +02:00
.Nm
tries first saving mail in your INBOX and then at any other mailbox.
2020-01-28 18:43:14 +02:00
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.
.Ss Drafts
To save your draft without sending it, issue
.Em COMMAND
.Cm close
and select 'save as draft'.
2020-01-28 18:43:14 +02:00
.sp
To open a draft for further editing, select your draft in the mail listing and press
.Ic edit_mail Ns
\&.
2019-11-27 17:40:00 +02:00
.Sh CONTACTS
.Nm
supports two kinds of contact backends:
2020-01-28 18:43:14 +02:00
.sp
2019-11-27 17:40:00 +02:00
.Bl -enum -compact -offset indent
.It
an internal format that gets saved under
.Pa $XDG_DATA_HOME/meli/account_name/addressbook Ns
2019-11-22 13:12:44 +02:00
\&.
2019-11-27 17:40:00 +02:00
.It
vCard files (v3, v4) through the
.Ic vcard_folder
2020-01-28 18:43:14 +02:00
option in the account section.
The path defined as
2019-11-27 17:40:00 +02:00
.Ic vcard_folder
2020-01-28 18:43:14 +02:00
can hold multiple vCards per file.
They are loaded read only.
2019-11-27 17:40:00 +02:00
.El
2020-01-28 18:43:14 +02:00
.sp
2019-11-27 17:40:00 +02:00
See
.Xr meli.conf 5 ACCOUNTS
for the complete account configuration values.
.Sh MODES
.Bl -tag -compact -width 8n
.It NORMAL
is the default mode
.It COMMAND
commands are issued in
.Em COMMAND
mode, by default started with Space and exited with
.Cm Esc
key.
.It EMBED
is the mode of the embed terminal emulator
.It INSERT
captures all input as text input, and is exited with
.Cm Esc
key.
.El
.Ss COMMAND Mode
.Ss Mail listing commands
2019-11-22 13:12:44 +02:00
.Bl -tag -width 36n
.It Cm set Ar plain | threaded | compact | conversations
2019-07-29 20:23:22 +03:00
set the way mailboxes are displayed
2019-11-22 13:12:44 +02:00
.El
.TS
allbox tab(:);
lb l.
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
.TE
.Bl -tag -width 36n
.It Cm sort Ar subject | date \ Ar asc | desc
2019-07-29 20:23:22 +03:00
sort mail listing
2019-11-22 13:12:44 +02:00
.It Cm subsort Ar subject | date \ Ar asc | desc
2019-07-29 20:23:22 +03:00
sorts only the first level of replies.
2019-11-22 13:12:44 +02:00
.It Cm go Ar n
2019-07-29 20:23:22 +03:00
where
.Ar n
is a mailbox prefixed with the
.Ar n
number in the side menu for the current account
2019-11-22 13:12:44 +02:00
.It Cm toggle_thread_snooze
2019-07-29 20:23:22 +03:00
don't issue notifications for thread under cursor in thread listing
2020-02-26 18:36:52 +02:00
.It Cm search Ar STRING
search mailbox with
2019-07-29 20:23:22 +03:00
.Ar STRING
2020-01-28 18:43:14 +02:00
key.
2020-02-26 18:36:52 +02:00
Escape exits search results
2019-11-22 13:12:44 +02:00
.It Cm set read, set unread
Set read status of message.
.It Cm create-mailbox Ar ACCOUNT Ar MAILBOX_PATH
create mailbox with given path.
2020-01-28 18:43:14 +02:00
Be careful with backends and separator sensitivity (eg IMAP)
.It Cm subscribe-mailbox Ar ACCOUNT Ar MAILBOX_PATH
subscribe to mailbox with given path
.It Cm unsubscribe-mailbox Ar ACCOUNT Ar MAILBOX_PATH
unsubscribe to mailbox with given path
.It Cm rename-mailbox Ar ACCOUNT Ar MAILBOX_PATH_SRC Ar MAILBOX_PATH_DEST
rename mailbox
.It Cm delete-mailbox Ar ACCOUNT Ar MAILBOX_PATH
deletes mailbox in the mail backend.
This action is unreversible.
.El
.Ss Mail view commands
2019-11-22 13:12:44 +02:00
.Bl -tag -width 36n
.It Cm pipe Ar EXECUTABLE Ar ARGS
pipe pager contents to binary
2019-07-29 20:23:22 +03:00
.It Cm list-post
2019-11-22 13:12:44 +02:00
post in list of viewed envelope
2019-07-29 20:23:22 +03:00
.It Cm list-unsubscribe
2019-11-22 13:12:44 +02:00
unsubscribe automatically from list of viewed envelope
2019-07-29 20:23:22 +03:00
.It Cm list-archive
open list archive with
.Cm xdg-open
.El
.Ss composing mail commands
2019-11-22 13:12:44 +02:00
.Bl -tag -width 36n
.It Cm add-attachment Ar PATH
in composer, add
.Ar PATH
as an attachment
.It Cm add-attachment < Ar CMD Ar ARGS
in composer, pipe
.Ar CMD Ar ARGS
output into an attachment
2019-11-22 13:12:44 +02:00
.It Cm remove-attachment Ar INDEX
remove attachment with given index
2019-11-22 13:12:44 +02:00
.It Cm toggle sign
2020-01-28 18:43:14 +02:00
toggle between signing and not signing this message.
If the gpg invocation fails then the mail won't be sent.
See
.Xr meli.conf 5 PGP
for PGP configuration.
2020-06-23 19:25:01 +03:00
.It Cm save-draft
saves a copy of the draft in the Draft folder
.El
.Ss generic commands
2019-11-22 13:12:44 +02:00
.Bl -tag -width 36n
.It Cm open-in-tab
opens envelope view in new tab
2019-11-22 13:12:44 +02:00
.It Cm close
closes closeable tabs
2019-07-29 20:23:22 +03:00
.It Cm setenv Ar KEY=VALUE
set environment variable
.Ar KEY
to
.Ar VALUE
.It Cm printenv Ar KEY
2019-07-29 20:23:22 +03:00
print environment variable
.Ar KEY
2019-07-04 07:38:25 +03:00
.El
.Sh SHORTCUTS
See
.Xr meli.conf 5 SHORTCUTS
for shortcuts and their default values.
2019-07-04 07:38:25 +03:00
.Sh EXIT STATUS
2019-07-29 20:23:22 +03:00
.Nm
2020-01-28 18:43:14 +02:00
exits with 0 on a successful run.
Other exit statuses are:
.Bl -tag -width 5n
2019-07-29 20:23:22 +03:00
.It 1
catchall for general errors
.It 101
process panic
2019-07-29 20:23:22 +03:00
.El
2019-07-04 07:38:25 +03:00
.Sh ENVIRONMENT
.Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
2019-07-29 20:23:22 +03:00
.It Ev EDITOR
Specifies the editor to use
.It Ev MELI_CONFIG
Override the configuration file
.It Ev NO_COLOR
2020-01-28 18:43:14 +02:00
When present (regardless of its value), prevents the addition of ANSI color.
The configuration value
.Ic use_color
overrides this.
2019-07-04 07:38:25 +03:00
.El
.Sh FILES
2019-11-11 22:20:16 +02:00
.Nm
uses the following parts of the XDG standard:
.Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
2019-07-29 20:23:22 +03:00
.It Ev XDG_CONFIG_HOME
defaults to
.Pa ~/.config/
.It Ev XDG_CACHE_HOME
defaults to
.Pa ~/.cache/
2019-07-04 07:38:25 +03:00
.El
2019-07-29 20:23:22 +03:00
.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
2020-01-28 00:32:40 +02:00
.It Pa $XDG_CONFIG_HOME/meli/config.toml
User configuration file, see
.Xr meli.conf 5
for its syntax and values.
2019-07-29 20:23:22 +03:00
.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.
2019-07-29 20:23:22 +03:00
.It Pa /tmp/meli/*
2019-11-11 22:20:16 +02:00
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
2019-11-22 13:12:44 +02:00
.It
2019-11-11 22:20:16 +02:00
.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
2019-07-04 07:38:25 +03:00
.El
2019-07-29 20:23:22 +03:00
.Sh SEE ALSO
2019-11-11 22:20:16 +02:00
.Xr meli.conf 5 ,
2020-01-28 00:32:40 +02:00
.Xr meli-themes 5 ,
.Xr xdg-open 1 ,
2019-11-11 22:20:16 +02:00
.Xr mailcap 5
2019-07-29 20:23:22 +03:00
.Sh CONFORMING TO
XDG Standard
.Aq https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html Ns
, maildir
2019-11-11 22:20:16 +02:00
.Aq https://cr.yp.to/proto/maildir.html Ns
2019-12-13 00:13:54 +02:00
, IMAPv4rev1 RFC3501, The JSON Meta Application Protocol (JMAP) RFC8620, The JSON Meta Application Protocol (JMAP) for Mail RFC8621.
2019-07-04 07:38:25 +03:00
.Sh AUTHORS
2019-07-29 20:23:22 +03:00
Copyright 2017-2019
.An Manos Pitsidianakis Aq epilys@nessuent.xyz
2020-01-28 18:43:14 +02:00
Released under the GPL, version 3 or greater.
This software carries no warranty of any kind.
(See COPYING for full copyright and warranty notices.)
2019-07-04 07:38:25 +03:00
.Pp
2019-07-29 20:23:22 +03:00
.Aq https://meli.delivery