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.

566 lines
14 KiB

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