meli/meli.conf.5

.\" meli - meli.conf.5
.\"
.\" 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 September 16, 2019
.Dt MELI.CONF 5
.Os
.Sh NAME
.Nm meli.conf
.Nd configuration file for the Meli Mail User Agent
.Sh SYNOPSIS
.Pa $XDG_CONFIG_HOME/meli/config.toml
.Sh DESCRIPTION
Configuration for meli is written in TOML.
Few things to consider before writing TOML (quoting the spec):
.Pp
.Bl -bullet -compact
.It
TOML is case sensitive.
.It
A TOML file must be a valid UTF-8 encoded Unicode document.
.It
Whitespace means tab (0x09) or space (0x20).
.It
Newline means LF (0x0A) or CRLF (0x0D 0x0A).
.El
.Pp
Refer to TOML documentation for valid TOML syntax.
.sp
Though not part of TOML syntax,
.Nm
can have nested configuration files by using the following
.Xr m4 1
include macro:
.Dl include(\&"/path/to/file\&")
.Sh SECTIONS
The top level sections of the config are:
.Bl -bullet -compact
.It
accounts
.It
shortcuts
.It
notifications
.It
pager
.It
listing
.It
composing
.It
pgp
.It
terminal
.It
log
.El
.Sh EXAMPLES
example configuration
.sp
.Bd -literal
# Setting up a Maildir account
[accounts.account-name]
root_mailbox = "/path/to/root/folder"
format = "Maildir"
index_style = "Compact"
identity="email@address.tld"
subscribed_mailboxes = ["folder", "folder/Sent"] # or [ "*", ] for all mailboxes
display_name = "Name"

# Set mailbox-specific settings
  [accounts.account-name.mailboxes]
  "INBOX" = { alias="Inbox" } #inline table
  "drafts" = { alias="Drafts" } #inline table
  [accounts.account-name.mailboxes."foobar-devel"] # or a regular table
    ignore = true # don't show notifications for this mailbox

# Setting up an mbox account
[accounts.mbox]
root_mailbox = "/var/mail/username"
format = "mbox"
index_style = "Compact"
identity="username@hostname.local"

[pager]
filter = "COLUMNS=72 /usr/local/bin/pygmentize -l email"
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]
[shortcuts.composing]
edit_mail = 'e'

[shortcuts.listing]
new_mail = 'm'
set_seen = 'n'

[terminal]
theme = "light"
.Ed
.Pp
available options are listed below.
.Sy default values are shown in parentheses.
.Sh ACCOUNTS
.Bl -tag -width 36n
.It Ic root_mailbox Ar String
the backend-specific path of the root_mailbox, usually INBOX.
.It Ic format Ar String Op maildir mbox imap notmuch jmap
the format of the mail backend.
.It Ic subscribed_mailboxes Ar [String,]
an array of mailbox paths to display in the UI.
Paths are relative to the root mailbox (eg "INBOX/Sent", not "Sent").
The glob wildcard
.Em \&*
can be used to match every mailbox name and path.
.It Ic identity Ar String
your e-mail address that is inserted in the From: headers of outgoing mail
.It Ic index_style Ar String
set the way mailboxes are displayed
.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 Ic display_name Ar String
(optional) a name which can be combined with your address:
"Name <email@address.tld>"
.It Ic read_only Ar boolean
attempt to not make any changes to this account.
.Pq Em false
.It Ic manual_refresh Ar boolean
(optional) if true, do not monitor account for changes (you can use shortcut listing.refresh)
.Pq Em false
.It Ic refresh_command Ar String
(optional) command to execute when manually refreshing (shortcut listing.refresh)
.Pq Em None
.It Ic cache_type Ar String
(optional) choose which cache backend to use.
Available options are 'none' and 'sqlite3'
.Pq Em "sqlite3"
.It Ic vcard_folder Ar String
(optional) Folder that contains .vcf files.
They are parsed and imported read-only.
.It Ic mailboxes Ar mailbox
(optional) configuration for each mailbox.
Its format is described below in
.Sx mailboxes Ns
\&.
.El
.Sh notmuch only
.Ic root_mailbox
points to the directory which contains the
.Pa .notmuch/
subdirectory.
notmuch mailboxes are virtual, since they are defined by user-given notmuch queries.
Thus you have to explicitly state the mailboxes you want in the
.Ic mailboxes
field and set the
.Ar query
property to each of them.
Example:
.Bd -literal
[accounts.notmuch]
format = "notmuch"
\&...
  [accounts.notmuch.mailboxes]
  "INBOX" = {  query="tag:inbox", subscribe = true }
  "Drafts" = {  query="tag:draft", subscribe = true }
  "Sent" = {  query="from:username@server.tld from:username2@server.tld", subscribe = true }
.Ed
.Sh IMAP only
IMAP specific options are:
.Bl -tag -width 36n
.It Ic server_hostname Ar String
example:
.Qq mail.example.tld
.It Ic server_username Ar String
.It Ic server_password Ar String
.It Ic server_password_command Ar String
(optional) Use instead of
.Ic server_password
.It Ic server_port Ar number
(optional)
.\" default value
.Pq Em 143
.It Ic use_starttls Ar boolean
(optional) if port is 993 and use_starttls is unspecified, it becomes false by default.
.\" default value
.Pq Em true
.It Ic danger_accept_invalid_certs Ar boolean
(optional) do not validate TLS certificates.
.\" default value
.Pq Em false
.El
.Sh JMAP only
JMAP specific options are:
.Bl -tag -width 36n
.It Ic server_hostname Ar String
example:
.Qq mail.example.tld
.It Ic server_username Ar String
.It Ic server_password Ar String
.It Ic server_port Ar number
(optional)
.\" default value
.Pq Em 443
.It Ic danger_accept_invalid_certs Ar boolean
(optional) do not validate TLS certificates.
.\" default value
.Pq Em false
.El
.Sh mbox only
mbox specific options are:
.Bl -tag -width 36n
.It Ic prefer_mbox_type Ar String
(optional) prefer specific mbox format reader for each message. Default is mboxcl2 format. If the preferred format fails, the message is retried with mboxrd and then if it fails again there's a recover attempt, which discards the invalid message.
Valid values are:
.Bl -bullet -compact
.It
.Ar auto
.It
.Ar mboxo
.It
.Ar mboxrd
.It
.Ar mboxcl
.It
.Ar mboxcl2
.El
.\" default value
.Pq Em auto
.El
to set multiple mailboxes, you have to explicitly state the mailboxes you want in the
.Ic mailboxes
field and set the
.Ar path
property to each of them.
Example:
.Bd -literal
[accounts.mbox]
format = "mbox"
mailboxes."Python mailing list" = { path = "~/.mail/python.mbox", subscribe = true, autoload = true }
.Ed
.Sh mailboxes
.Bl -tag -width 36n
.It Ic alias Ar String
(optional) show a different name for this mailbox in the UI
.It Ic autoload Ar boolean
(optional) load this mailbox on startup
.\" default value
.Pq Em true
.It Ic subscribe Ar boolean
(optional) watch this mailbox for updates
.\" default value
.Pq Em true
.It Ic ignore Ar boolean
(optional) silently insert updates for this mailbox, if any
.\" default value
.Pq Em false
.It Ic usage Ar boolean
(optional) special usage of this mailbox.
Valid values are:
.Bl -bullet -compact
.It
.Ar Normal
.It
.Ar Inbox
.It
.Ar Archive
.It
.Ar Drafts
.It
.Ar Flagged
.It
.Ar Junk
.It
.Ar Sent
.It
.Ar Trash
.El
otherwise usage is inferred from the mailbox title.
.It Ic conf_override Ar boolean
(optional) override global settings for this mailbox.
Available sections to override are
.Em pager, notifications, shortcuts, composing
and the account options
.Em identity and index_style Ns
\&.
Example:
.Bd -literal
[accounts."imap.domain.tld".mailboxes."INBOX"]
  index_style = "plain"
  [accounts."imap.domain.tld".mailboxes."INBOX".pager]
    filter = ""
.Ed
.El
.Sh COMPOSING
.Bl -tag -width 36n
.It Ic mailer_cmd Ar String
command to pipe new mail to, exit code must be 0 for success.
.It Ic editor_cmd Ar 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.
.It Ic embed Ar boolean
(optional) embed editor within meli
.\" default value
.Pq Em false
.It Ic format_flowed Ar boolean
(optional) set format=flowed [RFC3676] in text/plain attachments.
.\" default value
.Pq Em true
.It Ic default_header_values Ar hash table String[String]
Default header values used when creating a new draft.
.El
.Sh SHORTCUTS
Shortcuts can take the following values:
.Qq Em Backspace
.Qq Em Left
.Qq Em Right
.Qq Em Up
.Qq Em Down
.Qq Em Home
.Qq Em End
.Qq Em PageUp
.Qq Em PageDown
.Qq Em Delete
.Qq Em Insert
.Qq Em Enter
.Qq Em Tab
.Qq Em Esc
.Qq Em F1..F12
.Qq Em M-char
.Qq Em C-char
and
.Qq Em char Ns
, where char is a single character string.
.sp
The headings before each list indicate the map key of the shortcut list.
For example for the first list titled
.Em general
the configuration is typed as follows:
.Bd -literal
[shortcuts.general]
next_tab = 'T'
.Ed
.sp
and for
.Em compact-listing Ns
:
.Bd -literal
[shortcuts.compact-listing]
open_thread = "Enter"
exit_thread = 'i'
.Ed
.sp
.Pp
.Em general
.Bl -tag -width 36n
.It Ic next_tab
Go to next tab.
.\" default value
.Pq Em T
.It Ic go_to_tab
Go to the
.Em n Ns
th tab
.Pq Em cannot be redefined
.El
.sp
.Em listing
.Bl -tag -width 36n
.It Ic prev_page
Go to previous page.
.\" default value
.Pq Em PageUp
.It Ic next_page
Go to next page.
.\" default value
.Pq Em PageDown
.It Ic prev_mailbox
Go to previous mailbox.
.\" default value
.Pq Em K
.It Ic next_mailbox
Go to next mailbox.
.\" default value
.Pq Em J
.It Ic prev_account
Go to previous account.
.\" default value
.Pq Em l
.It Ic next_account
Go to next account.
.\" default value
.Pq Em h
.It Ic new_mail
Start new mail draft in new tab
.\" default value
.Pq Em m
.It Ic set_seen
Set thread as seen.
.\" default value
.Pq Em n
.It Ic refresh
Manually request a mailbox refresh.
.\" default value
.Pq Em F5
.It Ic search
Search within list of e-mails.
.\" default value
.Pq Em /
.It Ic toggle_menu_visibility
Toggle visibility of side menu in mail list.
.\" default value
.Pq Em `
.El
.sp
.Em compact-listing
.Bl -tag -width 36n
.It Ic exit_thread
Exit thread view
.\" default value
.Pq Em i
.It Ic open_thread
Open thread.
.\" default value
.Pq Em Enter
.It Ic select_entry
Select thread entry.
.\" default value
.Pq Em v
.El
.sp
.Em pager
.Bl -tag -width 36n
.It Ic scroll_up
Scroll up pager.
.\" default value
.Pq Em k
.It Ic scroll_down
Scroll down pager.
.\" default value
.Pq Em j
.It Ic page_up
Go to previous pager page
.\" default value
.Pq Em PageUp
.It Ic page_down
Go to next pager pag
.\" default value
.Pq Em PageDown
.El
.sp
.Em contact-list
.Bl -tag -width 36n
.It Ic create_contact
Create new contact.
.\" default value
.Pq Em c
.It Ic edit_contact
Edit contact under cursor
.\" default value
.Pq Em e
.It Ic mail_contact
Mail contact under cursor
.\" default value
.Pq Em m
.It Ic toggle_menu_visibility
Toggle visibility of side menu in mail list.
.\" default value
.Pq Em `
.El
.sp
.sp
.Em composing
.Bl -tag -width 36n
.It Ic send_mail
Deliver draft to mailer
.\" default value
.Pq Em s
.It Ic edit_mail
Edit mail.
.\" default value
.Pq Em e
.El
.sp
.Em envelope-view
.Pp
To "select" an attachment, type its index (you will see the typed result in the command buffer on your bottom right of the status line) and then issue the corresponding command.
.Bl -tag -width 36n
.It Ic add_addresses_to_contacts Ns
Select addresses from envelope to add to contacts.
.\" default value
.Pq Em c
.It Ic view_raw_source
View raw envelope source in a pager.
.\" default value
.Pq Em M-r
.It Ic reply
Reply to envelope.
.\" default value
.Pq Em R
.It Ic edit
Open envelope in composer.
.\" default value
.Pq Em e
.It Ic return_to_normal_view
Return to envelope if viewing raw source or attachment.
.\" default value
.Pq Em r
.It Ic open_attachment
Opens selected attachment with
.Cm xdg-open
.\" default value
.Pq Em a
.It Ic open_mailcap
Opens selected attachment according to its mailcap entry.
See
.Xr meli.1 FILES
for the mailcap file locations.
.\" default value
.Pq Em m
.It Ic go_to_url
Go to url of given index
.\" default value
.Pq Em g
.It Ic toggle_url_mode
Toggles url open mode.
When active, it prepends an index next to each url that you can select by typing and open by issuing
.Ic go_to_url
.\" default value
.Pq Em u
.It Ic toggle_expand_headers
Expand extra headers (References and others)
.\" default value
.Pq Em h
.El
.sp
.Em thread-view
.Bl -tag -width 36n
.It Ic reverse_thread_order
Reverse thread order.
.\" default value
.Pq Em r
.It Ic toggle_mailview
Toggle mail view visibility.
.\" default value
.Pq Em p
.It Ic toggle_threadview
Toggle thread view visibility.
.\" default value
.Pq Em t
.It Ic collapse_subtree
Collapse thread branches.
.\" default value
.Pq Em h
.It Ic prev_page
Go to previous page.
.\" default value
.Pq Em PageUp
.It Ic next_page
Go to next page.
.\" default value
.Pq Em PageDown
.El
.sp
.Sh NOTIFICATIONS
.Bl -tag -width 36n
.It Ic enable Ar boolean
enable freedesktop-spec notifications.
this is usually what you want
.\" default value
.Pq Em true
.It Ic script Ar String
(optional) script to pass notifications to, with title as 1st arg and body as 2nd
.\" default value
.Pq Em none
.It Ic xbiff_file_path Ar String
(optional) file that gets its size updated when new mail arrives
.Pq Em none
.\" default value
.It Ic play_sound Ar boolean
(optional) play theme sound in notifications if possible
.Pq Em false
.\" default value
.It Ic sound_file Ar String
(optional) play sound file in notifications if possible
.\" default value
.Pq Em none
.El
.Sh PAGER
.Bl -tag -width 36n
.It Ic pager_context Ar num
(optional) number of context lines when going to next page.
(Unimplemented)
.\" default value
.Pq Em 0
.It Ic headers_sticky Ar boolean
(optional) always show headers when scrolling.
.\" default value
.Pq Em true
.It Ic html_filter Ar String
(optional) pipe html attachments through this filter before display
.\" default value
.Pq Em none
.It Ic filter Ar String
(optional) a command to pipe mail output through for viewing in pager.
.\" default value
.Pq Em none
.It Ic format_flowed Ar bool
(optional) respect format=flowed
.\" default value
.Pq Em true
.It Ic split_long_lines Ar bool
(optional) Split long lines that would overflow on the x axis.
.\" default value
.Pq Em true
.It Ic minimum_width Ar num
(optional) Minimum text width in columns.
.\" default value
.Pq Em 80
.It Ic auto_choose_multipart_alternative Ar boolean,
(optional) Choose `text/html` alternative if `text/plain` is empty in `multipart/alternative` attachments.
.\" default value
.Pq Em true
.El
.Sh LISTING
.Bl -tag -width 36n
.It Ic context_lines Ar num
(optional) number of context lines when going to next page.
(Unimplemented)
.\" default value
.Pq Em 0
.It Ic datetime_fmt Ar String
(optional) datetime formatting passed verbatim to strftime(3).
.\" default value
.Pq Em \&%Y-\&%m-\&%d \&%T
.It Ic recent_dates Ar Boolean
(optional) Show recent dates as `X {minutes,hours,days} ago`, up to 7 days.
.\" default value
.Pq Em true
.It Ic filter Ar Query
(optional) Show only envelopes matching this query (for query syntax see
.Xr meli 1 )
.\" default value
.Pq Em None
.Pp
Example:
.Bd -literal
filter = "not flags:seen" # show only unseen messages
.Ed
.El
.Sh TAGS
.Bl -tag -width 36n
.It Ic colours Ar hash table String[Color]
(optional) set UI colors for tags
.It Ic ignore_tags Ar Array String
(optional) hide tags (not the tagged messages themselves)
.El
.sp
example configuration:
.sp
.Bd -literal
[tags]
# valid inputs: #HHHHHH, #ABC -> #AABBCC, XTERM_NAME, 0-255 byte
colors = { signed="#Ff6600", replied="DeepSkyBlue4", draft="#f00", replied="8" }
[accounts.dummy]
\&...
  [accounts.dummy.mailboxes]
  # per mailbox override:
  "INBOX" = {  tags.ignore_tags=["inbox", ] }
.Ed
.Sh PGP
.Bl -tag -width 36n
.It Ic auto_verify_signatures Ar boolean
auto verify signed e-mail according to RFC3156
.\" default value
.Pq Em true
.It Ic auto_sign Ar boolean
(optional) always sign sent messages
.\" default value
.Pq Em false
.It Ic key Ar String
(optional) key to be used when signing/encrypting (not functional yet)
.\" default value
.Pq Em none
.It Ic gpg_binary Ar String
(optional) gpg binary name or file location to use
.\" default value
.Pq Em "gpg2"
.El
.Sh TERMINAL
.Bl -tag -width 36n
.It Ic theme Ar String
(optional) select between these themes: light / dark
.\" default value
.Pq Em dark
.It Ic ascii_drawing Ar boolean
(optional) if true, box drawing will be done with ascii characters.
.\" default value
.Pq Em false
.It Ic use_color Ar boolean
(optional) if false, no ANSI colors are used
.\" default value
.Pq Em true
.It Ic window_title Ar String
(optional) set window title in xterm compatible terminals (empty string means no window title is set)
.\" default value
.Pq Em "meli"
.It Ic themes Ar hash table String[String[Attribute]]
define UI themes.
See
.Xr meli-themes 5
for details.
.Bd -literal
[terminal]
theme = "themeB"

[terminal.themes.themeA]
"mail.view.body" = {fg = "HotPink3", bg = "LightSalmon1"}
\&...
[terminal.themes.themeB]
"mail.view.body" = {fg = "CadetBlue", bg = "White"}
\&...
[terminal.themes.themeC]
\&...
.Ed
.El
.Sh LOG
.Bl -tag -width 36n
.It Ic log_file Ar String
(optional) path of the log file
.\" default value
.Pq Pa $XDG_DATA_HOME/meli/meli.log
.It Ic maximum_level Ar String
(optional) maximum level of messages to log. All levels less or equal to the
.Ic maximum_level
will be appended to the log file. Available levels are, in partial order:
.Bl -bullet -compact
.It
.Em OFF
.It
.Em FATAL
.It
.Em ERROR
.It
.Em WARN
.It
.Em INFO
.It
.Em DEBUG
.It
.Em TRACE
.El
This means that to turn logging off, set
.Ic maximum_level
to
.Em OFF Ns
\&.
.\" default value
.Pq Em INFO
.El
.Sh SEE ALSO
.Xr meli 1 ,
.Xr meli-themes 5
.Sh CONFORMING TO
TOML Standard v.0.5.0 https://toml.io/en/v0.5.0
.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