3 lei - an overview of lei
7 L<lei(1)> is a local email interface for public-inbox and personal mail.
8 This document provides some basic examples.
12 lei has writable local storage based on L<public-inbox-v2-format(5)>.
13 Commands will automatically initialize the store behind the scenes if
14 needed, but you can call L<lei-init(1)> directly if you want to use a
15 store location other than the default C<$XDG_DATA_HOME/lei/store>.
17 The L<lei-import(1)> command provides the primary interface for
18 importing messages into the local storage. In addition, other
19 commands, such as L<lei-q(1)> and L<lei-blob(1)>, use the local store
20 to memoize messages from remotes.
26 =item $ lei import mboxrd:t.mbox.gz
28 Import the messages from a gzipped mboxrd into the local storage.
30 =item $ lei blob 59ec517f9
32 Show message with the git blob OID of 59ec517f9. If a message with
33 that OID isn't found, check if the current git repository has the
34 blob, trying to reconstruct it from a message if needed.
36 =item $ lei blob 59ec517f9 | lei tag -F eml +kw:flagged +L:next
38 Set the "flagged" keyword and "next" label on the message with the
39 blob OID of 59ec517f9.
45 In addition to the above store, lei can make read-only queries to
46 "externals": inboxes and external indices. An external can be
47 registered by passing a URL or local path to L<lei-add-external(1)>.
48 For existing local paths, the external needs to be indexed with
49 L<public-inbox-index(1)> (in the case of a regular inbox) or
50 L<public-inbox-extindex(1)> (in the case of an external index).
52 =head1 SYNCHRONIZATION
54 lei currently has primitive mail synchronization abilities;
55 see L<lei-mail-sync-overview(7)> for more details.
61 =item $ lei add-external https://public-inbox.org/meta/
63 Add a remote external for public-inbox's inbox.
65 =item $ lei add-external --mirror https://public-inbox.org/meta/ path
67 Clone L<https://public-inbox.org/meta/> to C<path>, index it with
68 L<public-inbox-index(1)>, and add it as a local external.
74 The L<lei-q(1)> command searches the local store and externals. The
75 search prefixes match those available via L<public-inbox-httpd(1)>.
81 =item $ lei q s:lei s:skeleton
83 Search for messages whose subject includes "lei" and "skeleton".
85 =item $ lei q -t s:lei s:skeleton
87 Do the same, but also report unmatched messages that are in the same
88 thread as a matched message.
90 =item $ lei q -t -o /tmp/mdir --mua=mutt s:lei s:skeleton
92 Write results to a Maildir at "mdir". Mutt will be invoked
93 to open mfolder (C<mutt -f %f>) while results are being fetched
96 =item $ lei q kw:flagged L:next
98 Search for all flagged messages that also have a "next" label.
100 =item $ lei p2q HEAD | lei q -tt -o /tmp/mdir
102 Search for messages that have post-image git blob IDs that match those
103 of the current repository's HEAD commit, writing them to the Maildir
104 directory "mdir" and flagging the messages that were an exact match.
106 =item $ git show -s HEAD | lei lcat
108 Display a local message for the public-inbox link contained in a
111 =item $ lei q -f text m:MESSAGE-ID | lei rediff -U5
113 Feed a message containing a diff to L<lei-rediff(1)> to regenerate its
114 diff with five context lines. Unless C<--git-dir> is specified, this
115 requires the current working directory to be within the associated
120 =head1 PERFORMANCE NOTES
122 L<Inline::C> is required, lei runs as a background daemon to reduce
123 startup costs and can provide real-time L<kqueue(2)>/L<inotify(7)>
124 Maildir monitoring. L<IO::KQueue> (p5-IO-KQueue on FreeBSD) and
125 L<Linux::Inotify2> (liblinux-inotify2-perl and perl-Linux-Inotify2 in
126 .deb and .rpm-based distros, respectively) are recommended.
128 L<Socket::MsgHdr> is optional (libsocket-msghdr-perl in Debian),
129 and further improves startup performance. Its effect is most felt
130 when using shell completion.
132 =head1 BASH COMPLETION
134 Preliminary Bash completion for lei is provided in
135 C<contrib/completion/>. Contributions adding support for other
136 shells, as well as improvements to the existing Bash completion, are
141 Since lei runs as a daemon, L<lei-daemon-kill(1)> is required to kill
142 the daemon so it can load new code. It will be restarted with the
143 next invocation of any lei command.
147 IMAP and NNTP client performance is poor on high-latency connections.
148 It will hopefully be fixed in 2022.
152 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
154 The mail archives are hosted at L<https://public-inbox.org/meta/> and
155 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
159 Copyright all contributors L<mailto:meta@public-inbox.org>
161 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
165 L<lei-mail-sync-overview(7)>