🐝 My patches for macos etc...
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.

599 lines
15 KiB

2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 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@example.com and cc:me@example.com
  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
  364. .Cm \&:
  365. 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 COMMAND 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. query.
  406. Escape exits search results.
  407. .It Cm select Ar STRING
  408. select threads matching
  409. .Ar STRING
  410. query.
  411. .It Cm set seen, set unseen
  412. Set seen status of message.
  413. .It Cm import Ar FILEPATH Ar MAILBOX_PATH
  414. Import mail from file into given mailbox.
  415. .It Cm copyto, moveto Ar MAILBOX_PATH
  416. Copy or move to other mailbox.
  417. .It Cm copyto, moveto Ar ACCOUNT Ar MAILBOX_PATH
  418. Copy or move to another account's mailbox.
  419. .It Cm delete
  420. Delete selected threads.
  421. .It Cm export-mbox Ar FILEPATH
  422. Export selected threads to mboxcl2 file.
  423. .It Cm create-mailbox Ar ACCOUNT Ar MAILBOX_PATH
  424. create mailbox with given path.
  425. Be careful with backends and separator sensitivity (eg IMAP)
  426. .It Cm subscribe-mailbox Ar ACCOUNT Ar MAILBOX_PATH
  427. subscribe to mailbox with given path
  428. .It Cm unsubscribe-mailbox Ar ACCOUNT Ar MAILBOX_PATH
  429. unsubscribe to mailbox with given path
  430. .It Cm rename-mailbox Ar ACCOUNT Ar MAILBOX_PATH_SRC Ar MAILBOX_PATH_DEST
  431. rename mailbox
  432. .It Cm delete-mailbox Ar ACCOUNT Ar MAILBOX_PATH
  433. deletes mailbox in the mail backend.
  434. This action is unreversible.
  435. .El
  436. .Ss Mail view commands
  437. .Bl -tag -width 36n
  438. .It Cm pipe Ar EXECUTABLE Ar ARGS
  439. pipe pager contents to binary
  440. .It Cm list-post
  441. post in list of viewed envelope
  442. .It Cm list-unsubscribe
  443. unsubscribe automatically from list of viewed envelope
  444. .It Cm list-archive
  445. open list archive with
  446. .Cm xdg-open
  447. .El
  448. .Ss composing mail commands
  449. .Bl -tag -width 36n
  450. .It Cm add-attachment Ar PATH
  451. in composer, add
  452. .Ar PATH
  453. as an attachment
  454. .It Cm add-attachment < Ar CMD Ar ARGS
  455. in composer, pipe
  456. .Ar CMD Ar ARGS
  457. output into an attachment
  458. .It Cm add-attachment-file-picker
  459. Launch command defined in the configuration value
  460. .Ic file_picker_command
  461. in
  462. .Xr meli.conf 5 TERMINAL
  463. .It Cm add-attachment-file-picker < Ar CMD Ar ARGS
  464. Launch command
  465. .Ar CMD Ar ARGS Ns
  466. \&.
  467. The command should print file paths in stderr, separated by NULL bytes.
  468. .It Cm remove-attachment Ar INDEX
  469. remove attachment with given index
  470. .It Cm toggle sign
  471. toggle between signing and not signing this message.
  472. If the gpg invocation fails then the mail won't be sent.
  473. See
  474. .Xr meli.conf 5 PGP
  475. for PGP configuration.
  476. .It Cm save-draft
  477. saves a copy of the draft in the Draft folder
  478. .El
  479. .Ss generic commands
  480. .Bl -tag -width 36n
  481. .It Cm open-in-tab
  482. opens envelope view in new tab
  483. .It Cm close
  484. closes closeable tabs
  485. .It Cm setenv Ar KEY=VALUE
  486. set environment variable
  487. .Ar KEY
  488. to
  489. .Ar VALUE
  490. .It Cm printenv Ar KEY
  491. print environment variable
  492. .Ar KEY
  493. .It Cm quit
  494. Quits
  495. .Nm Ns
  496. \&.
  497. .It Cm reload-config
  498. Reloads configuration but only if account configuration is unchanged.
  499. Useful if you want to reload some settings without restarting
  500. .Nm Ns
  501. \&.
  502. .El
  503. .Sh SHORTCUTS
  504. See
  505. .Xr meli.conf 5 SHORTCUTS
  506. for shortcuts and their default values.
  507. .Sh EXIT STATUS
  508. .Nm
  509. exits with 0 on a successful run.
  510. Other exit statuses are:
  511. .Bl -tag -width 5n
  512. .It 1
  513. catchall for general errors
  514. .It 101
  515. process panic
  516. .El
  517. .Sh ENVIRONMENT
  518. .Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
  519. .It Ev EDITOR
  520. Specifies the editor to use
  521. .It Ev MELI_CONFIG
  522. Override the configuration file
  523. .It Ev NO_COLOR
  524. When present (regardless of its value), prevents the addition of ANSI color.
  525. The configuration value
  526. .Ic use_color
  527. overrides this.
  528. .El
  529. .Sh FILES
  530. .Nm
  531. uses the following parts of the XDG standard:
  532. .Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
  533. .It Ev XDG_CONFIG_HOME
  534. defaults to
  535. .Pa ~/.config/
  536. .It Ev XDG_CACHE_HOME
  537. defaults to
  538. .Pa ~/.cache/
  539. .El
  540. .Pp
  541. and appropriates the following locations:
  542. .Bl -tag -width "$XDG_CONFIG_HOME/meli/plugins/*" -offset indent
  543. .It Pa $XDG_CONFIG_HOME/meli/
  544. User configuration directory
  545. .It Pa $XDG_CONFIG_HOME/meli/config.toml
  546. User configuration file, see
  547. .Xr meli.conf 5
  548. for its syntax and values.
  549. .It Pa $XDG_CONFIG_HOME/meli/hooks/*
  550. Reserved for event hooks.
  551. .It Pa $XDG_CONFIG_HOME/meli/plugins/*
  552. Reserved for plugin files.
  553. .It Pa $XDG_CACHE_HOME/meli/*
  554. Internal cached data used by meli.
  555. .It Pa $XDG_DATA_HOME/meli/*
  556. Internal data used by meli.
  557. .It Pa $XDG_DATA_HOME/meli/meli.log
  558. Operation log.
  559. .It Pa /tmp/meli/*
  560. Temporary files generated by
  561. .Nm Ns
  562. \&.
  563. .El
  564. .Pp
  565. Mailcap entries are searched for in the following files, in this order:
  566. .Pp
  567. .Bl -enum -compact -offset indent
  568. .It
  569. .Pa $XDG_CONFIG_HOME/meli/mailcap
  570. .It
  571. .Pa $XDG_CONFIG_HOME/.mailcap
  572. .It
  573. .Pa $HOME/.mailcap
  574. .It
  575. .Pa /etc/mailcap
  576. .It
  577. .Pa /usr/etc/mailcap
  578. .It
  579. .Pa /usr/local/etc/mailcap
  580. .El
  581. .Sh SEE ALSO
  582. .Xr meli.conf 5 ,
  583. .Xr meli-themes 5 ,
  584. .Xr xdg-open 1 ,
  585. .Xr mailcap 5
  586. .Sh CONFORMING TO
  587. XDG Standard
  588. .Aq https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html Ns
  589. , maildir
  590. .Aq https://cr.yp.to/proto/maildir.html Ns
  591. , IMAPv4rev1 RFC3501, The JSON Meta Application Protocol (JMAP) RFC8620, The JSON Meta Application Protocol (JMAP) for Mail RFC8621.
  592. .Sh AUTHORS
  593. Copyright 2017-2019
  594. .An Manos Pitsidianakis Aq epilys@nessuent.xyz
  595. Released under the GPL, version 3 or greater.
  596. This software carries no warranty of any kind.
  597. (See COPYING for full copyright and warranty notices.)
  598. .Pp
  599. .Aq https://meli.delivery