You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

564 lines
14 KiB

3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
  1. .\" meli - meli.1
  2. .\"
  3. .\" Copyright 2017-2019 Manos Pitsidianakis
  4. .\"
  5. .\" This file is part of meli.
  6. .\"
  7. .\" meli is free software: you can redistribute it and/or modify
  8. .\" it under the terms of the GNU General Public License as published by
  9. .\" the Free Software Foundation, either version 3 of the License, or
  10. .\" (at your option) any later version.
  11. .\"
  12. .\" meli is distributed in the hope that it will be useful,
  13. .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  14. .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  15. .\" GNU General Public License for more details.
  16. .\"
  17. .\" You should have received a copy of the GNU General Public License
  18. .\" along with meli. If not, see <http://www.gnu.org/licenses/>.
  19. .\"
  20. .Dd July 29, 2019
  21. .Dt MELI 1
  22. .Os
  23. .Sh NAME
  24. .Nm meli
  25. .Nd Meli Mail User Agent. meli is the Greek word for honey
  26. .Sh SYNOPSIS
  27. .Nm
  28. .Op Fl -help | h
  29. .Op Fl -version | v
  30. .Op Fl -config Ar path
  31. .Bl -tag -width flag -offset indent
  32. .It Fl -help | h
  33. Show help message and exit.
  34. .It Fl -version | v
  35. Show version and exit.
  36. .It Fl -config Ar path
  37. Start meli with given configuration file.
  38. .It Cm create-config Op Ar path
  39. Create configuration file in
  40. .Pa path
  41. if given, or at
  42. .Pa $XDG_CONFIG_HOME/meli/config.toml
  43. .It Cm test-config Op Ar path
  44. Test a configuration file for syntax issues or missing options.
  45. .It Cm man Op Ar page
  46. Print documentation page and exit (Piping to a pager is recommended.)
  47. .It Cm print-default-theme
  48. Print default theme keys and values in TOML syntax, to be used as a blueprint.
  49. .It Cm print-loaded-themes
  50. Print all loaded themes in TOML syntax.
  51. .It Cm view
  52. View mail from input file.
  53. .El
  54. .Sh DESCRIPTION
  55. .Nm
  56. is a terminal mail client aiming for extensive and user-frendly configurability.
  57. .Bd -literal
  58. ^^ .-=-=-=-. ^^
  59. ^^ (`-=-=-=-=-`) ^^
  60. (`-=-=-=-=-=-=-`) ^^ ^^
  61. ^^ (`-=-=-=-=-=-=-=-`) ^^
  62. ( `-=-=-=-(@)-=-=-` ) ^^
  63. (`-=-=-=-=-=-=-=-=-`) ^^
  64. (`-=-=-=-=-=-=-=-=-`) ^^
  65. (`-=-=-=-=-=-=-=-=-`)
  66. ^^ (`-=-=-=-=-=-=-=-=-`) ^^
  67. ^^ (`-=-=-=-=-=-=-=-`) ^^
  68. (`-=-=-=-=-=-=-`) ^^
  69. ^^ (`-=-=-=-=-`)
  70. `-=-=-=-=-` ^^
  71. .Ed
  72. .Sh STARTING WITH meli
  73. When launched for the first time,
  74. .Nm
  75. will search for its configuration directory,
  76. .Pa $XDG_CONFIG_HOME/meli/ Ns
  77. \&.
  78. If it doesn't exist, you will be asked if you want to create one and presented with a sample configuration file
  79. .Pq Pa $XDG_CONFIG_HOME/meli/config.toml
  80. that includes the basic settings required for setting up accounts allowing you to copy and edit right away.
  81. See
  82. .Xr meli.conf 5
  83. for the available configuration options.
  84. .Pp
  85. At any time, you may press
  86. .Cm \&?
  87. for a searchable list of all available actions and shortcuts, along with every possible setting and command that your version supports.
  88. .Pp
  89. The main visual navigation tool, the left-side sidebar may be toggled with
  90. .Cm `
  91. (shortcuts.listing:
  92. .Ic toggle_menu_visibility Ns
  93. ).
  94. .Pp
  95. Each mailbox may be viewed in 4 modes:
  96. 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.
  97. .Pp
  98. If you're using a light color palette in your terminal, you should set
  99. .Em theme = "light"
  100. in the
  101. .Em terminal
  102. section of your configuration.
  103. See
  104. .Xr meli-themes 5
  105. for complete documentation on user themes.
  106. .Sh VIEWING MAIL
  107. Open attachments by typing their index in the attachments list and then
  108. .Cm a
  109. .Po
  110. shortcut
  111. .Ic open_attachment
  112. .Pc .
  113. .Nm
  114. will attempt to open text inside its pager, and other content via
  115. .Cm xdg-open Ns
  116. \&.
  117. Press
  118. .Cm m
  119. .Po
  120. shortcut
  121. .Ic open_mailcap
  122. .Pc
  123. instead to use the mailcap entry for the MIME type of the attachment, if any.
  124. See
  125. .Sx FILES
  126. for the location of the mailcap files and
  127. .Xr mailcap 5
  128. for their syntax.
  129. You can save individual attachments with the
  130. .Em COMMAND
  131. .Cm save-attachment Ar INDEX Ar path-to-file
  132. where
  133. .Ar INDEX
  134. is the attachment's index in the listing.
  135. If the zeroth index is provided, the entire message is saved.
  136. If the path provided is a directory, the message is saved as an eml file with its filename set to the messages message-id.
  137. .Sh SEARCH
  138. Each e-mail storage backend has a default search method assigned.
  139. .Em IMAP
  140. uses the SEARCH command,
  141. .Em notmuch
  142. uses libnotmuch and
  143. .Em Maildir/mbox
  144. performs a slow linear search.
  145. It is advised to use a search backend on
  146. .Em Maildir/mbox
  147. accounts.
  148. .Nm Ns
  149. , if built with sqlite3, includes the ability to perform full text search on the following fields:
  150. .Em From ,
  151. .Em To ,
  152. .Em Cc ,
  153. .Em Bcc ,
  154. .Em In-Reply-To ,
  155. .Em References ,
  156. .Em Subject
  157. and
  158. .Em Date .
  159. The message body (in plain text human readable form) and the flags can also be queried.
  160. To enable sqlite3 indexing for an account set
  161. .Em search_backend
  162. to
  163. .Em sqlite3
  164. in the configuration file and to create the sqlite3 index issue command
  165. .Cm index Ar ACCOUNT_NAME Ns \&.
  166. .sp
  167. To search in the message body type your keywords without any special formatting.
  168. To search in specific fields, prepend your search keyword with "field:" like so:
  169. .Pp
  170. .D1 subject:helloooo or subject:\&"call for help\&" or \&"You remind me today of a small, Mexican chihuahua.\&"
  171. .Pp
  172. .D1 not ((from:unrealistic and (to:complex or not "query")) or flags:seen,draft)
  173. .Pp
  174. .D1 alladdresses:mailing@list.tld and cc:me@domain.tld
  175. .Pp
  176. Boolean operators are
  177. .Em or Ns
  178. ,
  179. .Em and
  180. and
  181. .Em not
  182. .Po
  183. alias:
  184. .Em \&!
  185. .Pc
  186. String keywords with spaces must be quoted.
  187. Quotes should always be escaped.
  188. .sp
  189. .Sy Important Notice about IMAP/JMAP
  190. .sp
  191. To prevent downloading all your messages from your IMAP/JMAP server, don't set
  192. .Em search_backend
  193. to
  194. .Em sqlite3 Ns
  195. \&.
  196. .Nm
  197. will relay your queries to the IMAP server.
  198. Expect a delay between query and response.
  199. Sqlite3 on the contrary at reasonable mailbox sizes should have a non noticable delay.
  200. .Ss QUERY ABNF SYNTAX
  201. .Bl -bullet
  202. .It
  203. .Li query = \&"(\&" query \&")\&" | from | to | cc | bcc | alladdresses | subject | flags | has_attachments | query \&"or\&" query | query \&"and\&" query | not query
  204. .It
  205. .Li not = \&"not\&" | \&"!\&"
  206. .It
  207. .Li quoted = ALPHA / SP *(ALPHA / DIGIT / SP)
  208. .It
  209. .Li term = ALPHA *(ALPHA / DIGIT) | DQUOTE quoted DQUOTE
  210. .It
  211. .Li tagname = term
  212. .It
  213. .Li flagval = \&"passed\&" | \&"replied\&" | \&"seen\&" | \&"read\&" | \&"junk\&" | \&"trash\&" | \&"trashed\&" | \&"draft\&" | \&"flagged\&" | tagname
  214. .It
  215. .Li flagterm = flagval | flagval \&",\&" flagterm
  216. .It
  217. .Li from = \&"from:\&" term
  218. .It
  219. .Li to = \&"to:\&" term
  220. .It
  221. .Li cc = \&"cc:\&" term
  222. .It
  223. .Li bcc = \&"bcc:\&" term
  224. .It
  225. .Li alladdresses = \&"alladdresses:\&" term
  226. .It
  227. .Li subject = \&"subject:\&" term
  228. .It
  229. .Li flags = \&"flags:\&" flag | \&"tags:\&" flag | \&"is:\&" flag
  230. .El
  231. .Sh TAGS
  232. .Nm
  233. supports tagging in notmuch and IMAP/JMAP backends.
  234. Tags can be searched with the `tags:` or `flags:` prefix in a search query, and can be modified by
  235. .Cm tag add TAG
  236. and
  237. .Cm tag remove TAG
  238. (see
  239. .Xr meli.conf 5 TAGS Ns
  240. , settings
  241. .Ic colors
  242. and
  243. .Ic ignore_tags
  244. for how to set tag colors and tag visiblity)
  245. .Sh COMPOSING
  246. .Ss Opening the message Composer tab
  247. To create a new mail message, press
  248. .Cm m
  249. (shortcut
  250. .Ic new_mail Ns
  251. ) while viewing a mailbox.
  252. To reply to a mail, press
  253. .Cm R
  254. .Po
  255. shortcut
  256. .Ic reply
  257. .Pc .
  258. Both these actions open the mail composer view in a new tab.
  259. .Ss Editing text
  260. .Bl -bullet -compact
  261. .It
  262. Edit the header fields by selecting with the arrow keys and pressing
  263. .Cm enter
  264. to enter
  265. .Em INSERT
  266. mode and
  267. .Cm Esc
  268. key to exit.
  269. .It
  270. At any time you may press
  271. .Cm e
  272. (shortcut
  273. .Ic edit_mail Ns
  274. ) to launch your editor (see
  275. .Xr meli.conf 5 COMPOSING Ns
  276. , setting
  277. .Ic editor_command
  278. for how to select which editor to launch).
  279. .It
  280. Your editor can be used in
  281. .Nm Ns
  282. \&'s embed terminal emulator by setting
  283. .Ic embed
  284. to
  285. .Em true
  286. in your composing settings.
  287. .It
  288. When launched, your editor captures all input until it exits or stops.
  289. .It
  290. To stop your editor and return to
  291. .Nm
  292. press Ctrl-z and to resume editing press the
  293. .Ic edit_mail
  294. command again
  295. .Po
  296. default
  297. .Em e
  298. .Pc .
  299. .El
  300. .Ss Attachments
  301. Attachments may be handled with the
  302. .Cm add-attachment Ns
  303. ,
  304. .Cm remove-attachment
  305. commands (see below).
  306. .Ss Sending
  307. Finally, pressing
  308. .Cm s
  309. (shortcut
  310. .Ic send_mail Ns
  311. ) will send your message according to your settings
  312. .Po
  313. see
  314. .Xr meli.conf 5 COMPOSING Ns
  315. , setting
  316. .Ic send_mail
  317. .Pc Ns
  318. \&.
  319. With no Draft or Sent mailbox,
  320. .Nm
  321. tries first saving mail in your INBOX and then at any other mailbox.
  322. On complete failure to save your draft or sent message it will be saved in your
  323. .Em tmp
  324. directory instead and you will be notified of its location.
  325. .Ss Drafts
  326. To save your draft without sending it, issue
  327. .Em COMMAND
  328. .Cm close
  329. and select 'save as draft'.
  330. .sp
  331. To open a draft for further editing, select your draft in the mail listing and press
  332. .Ic edit_mail Ns
  333. \&.
  334. .Sh CONTACTS
  335. .Nm
  336. supports two kinds of contact backends:
  337. .sp
  338. .Bl -enum -compact -offset indent
  339. .It
  340. an internal format that gets saved under
  341. .Pa $XDG_DATA_HOME/meli/account_name/addressbook Ns
  342. \&.
  343. .It
  344. vCard files (v3, v4) through the
  345. .Ic vcard_folder
  346. option in the account section.
  347. The path defined as
  348. .Ic vcard_folder
  349. can hold multiple vCards per file.
  350. They are loaded read only.
  351. .El
  352. .sp
  353. See
  354. .Xr meli.conf 5 ACCOUNTS
  355. for the complete account configuration values.
  356. .Sh MODES
  357. .Bl -tag -compact -width 8n
  358. .It NORMAL
  359. is the default mode
  360. .It COMMAND
  361. commands are issued in
  362. .Em COMMAND
  363. mode, by default started with Space and exited with
  364. .Cm Esc
  365. key.
  366. .It EMBED
  367. is the mode of the embed terminal emulator
  368. .It INSERT
  369. captures all input as text input, and is exited with
  370. .Cm Esc
  371. key.
  372. .El
  373. .Ss COMMAND Mode
  374. .Ss Mail listing commands
  375. .Bl -tag -width 36n
  376. .It Cm set Ar plain | threaded | compact | conversations
  377. set the way mailboxes are displayed
  378. .El
  379. .TS
  380. allbox tab(:);
  381. lb l.
  382. conversations:shows one entry per thread
  383. compact:shows one row per thread
  384. threaded:shows threads as a tree structure
  385. plain:shows one row per mail, regardless of threading
  386. .TE
  387. .Bl -tag -width 36n
  388. .It Cm sort Ar subject | date \ Ar asc | desc
  389. sort mail listing
  390. .It Cm subsort Ar subject | date \ Ar asc | desc
  391. sorts only the first level of replies.
  392. .It Cm go Ar n
  393. where
  394. .Ar n
  395. is a mailbox prefixed with the
  396. .Ar n
  397. number in the side menu for the current account
  398. .It Cm toggle_thread_snooze
  399. don't issue notifications for thread under cursor in thread listing
  400. .It Cm search Ar STRING
  401. search mailbox with
  402. .Ar STRING
  403. key.
  404. Escape exits search results
  405. .It Cm set read, set unread
  406. Set read status of message.
  407. .It Cm create-mailbox Ar ACCOUNT Ar MAILBOX_PATH
  408. create mailbox with given path.
  409. Be careful with backends and separator sensitivity (eg IMAP)
  410. .It Cm subscribe-mailbox Ar ACCOUNT Ar MAILBOX_PATH
  411. subscribe to mailbox with given path
  412. .It Cm unsubscribe-mailbox Ar ACCOUNT Ar MAILBOX_PATH
  413. unsubscribe to mailbox with given path
  414. .It Cm rename-mailbox Ar ACCOUNT Ar MAILBOX_PATH_SRC Ar MAILBOX_PATH_DEST
  415. rename mailbox
  416. .It Cm delete-mailbox Ar ACCOUNT Ar MAILBOX_PATH
  417. deletes mailbox in the mail backend.
  418. This action is unreversible.
  419. .El
  420. .Ss Mail view commands
  421. .Bl -tag -width 36n
  422. .It Cm pipe Ar EXECUTABLE Ar ARGS
  423. pipe pager contents to binary
  424. .It Cm list-post
  425. post in list of viewed envelope
  426. .It Cm list-unsubscribe
  427. unsubscribe automatically from list of viewed envelope
  428. .It Cm list-archive
  429. open list archive with
  430. .Cm xdg-open
  431. .El
  432. .Ss composing mail commands
  433. .Bl -tag -width 36n
  434. .It Cm add-attachment Ar PATH
  435. in composer, add
  436. .Ar PATH
  437. as an attachment
  438. .It Cm add-attachment < Ar CMD Ar ARGS
  439. in composer, pipe
  440. .Ar CMD Ar ARGS
  441. output into an attachment
  442. .It Cm remove-attachment Ar INDEX
  443. remove attachment with given index
  444. .It Cm toggle sign
  445. toggle between signing and not signing this message.
  446. If the gpg invocation fails then the mail won't be sent.
  447. See
  448. .Xr meli.conf 5 PGP
  449. for PGP configuration.
  450. .It Cm save-draft
  451. saves a copy of the draft in the Draft folder
  452. .El
  453. .Ss generic commands
  454. .Bl -tag -width 36n
  455. .It Cm open-in-tab
  456. opens envelope view in new tab
  457. .It Cm close
  458. closes closeable tabs
  459. .It Cm setenv Ar KEY=VALUE
  460. set environment variable
  461. .Ar KEY
  462. to
  463. .Ar VALUE
  464. .It Cm printenv Ar KEY
  465. print environment variable
  466. .Ar KEY
  467. .El
  468. .Sh SHORTCUTS
  469. See
  470. .Xr meli.conf 5 SHORTCUTS
  471. for shortcuts and their default values.
  472. .Sh EXIT STATUS
  473. .Nm
  474. exits with 0 on a successful run.
  475. Other exit statuses are:
  476. .Bl -tag -width 5n
  477. .It 1
  478. catchall for general errors
  479. .It 101
  480. process panic
  481. .El
  482. .Sh ENVIRONMENT
  483. .Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
  484. .It Ev EDITOR
  485. Specifies the editor to use
  486. .It Ev MELI_CONFIG
  487. Override the configuration file
  488. .It Ev NO_COLOR
  489. When present (regardless of its value), prevents the addition of ANSI color.
  490. The configuration value
  491. .Ic use_color
  492. overrides this.
  493. .El
  494. .Sh FILES
  495. .Nm
  496. uses the following parts of the XDG standard:
  497. .Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
  498. .It Ev XDG_CONFIG_HOME
  499. defaults to
  500. .Pa ~/.config/
  501. .It Ev XDG_CACHE_HOME
  502. defaults to
  503. .Pa ~/.cache/
  504. .El
  505. .Pp
  506. and appropriates the following locations:
  507. .Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
  508. .It Pa $XDG_CONFIG_HOME/meli/
  509. User configuration directory
  510. .It Pa $XDG_CONFIG_HOME/meli/config.toml
  511. User configuration file, see
  512. .Xr meli.conf 5
  513. for its syntax and values.
  514. .It Pa $XDG_CONFIG_HOME/meli/hooks/*
  515. Reserved for event hooks.
  516. .It Pa $XDG_CONFIG_HOME/meli/plugins/*
  517. Reserved for plugin files.
  518. .It Pa $XDG_CACHE_HOME/meli/*
  519. Internal cached data used by meli.
  520. .It Pa $XDG_DATA_HOME/meli/*
  521. Internal data used by meli.
  522. .It Pa $XDG_DATA_HOME/meli/meli.log
  523. Operation log.
  524. .It Pa /tmp/meli/*
  525. Temporary files generated by
  526. .Nm Ns
  527. \&.
  528. .El
  529. .Pp
  530. Mailcap entries are searched for in the following files, in this order:
  531. .Pp
  532. .Bl -enum -compact -offset indent
  533. .It
  534. .Pa $XDG_CONFIG_HOME/meli/mailcap
  535. .It
  536. .Pa $XDG_CONFIG_HOME/.mailcap
  537. .It
  538. .Pa $HOME/.mailcap
  539. .It
  540. .Pa /etc/mailcap
  541. .It
  542. .Pa /usr/etc/mailcap
  543. .It
  544. .Pa /usr/local/etc/mailcap
  545. .El
  546. .Sh SEE ALSO
  547. .Xr meli.conf 5 ,
  548. .Xr meli-themes 5 ,
  549. .Xr xdg-open 1 ,
  550. .Xr mailcap 5
  551. .Sh CONFORMING TO
  552. XDG Standard
  553. .Aq https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html Ns
  554. , maildir
  555. .Aq https://cr.yp.to/proto/maildir.html Ns
  556. , IMAPv4rev1 RFC3501, The JSON Meta Application Protocol (JMAP) RFC8620, The JSON Meta Application Protocol (JMAP) for Mail RFC8621.
  557. .Sh AUTHORS
  558. Copyright 2017-2019
  559. .An Manos Pitsidianakis Aq epilys@nessuent.xyz
  560. Released under the GPL, version 3 or greater.
  561. This software carries no warranty of any kind.
  562. (See COPYING for full copyright and warranty notices.)
  563. .Pp
  564. .Aq https://meli.delivery