NAME

       lei - an overview of lei

DESCRIPTION

       lei(1) is a local email interface for public-inbox and personal mail.  This document
       provides some basic examples.

LEI STORE

       lei has writable local storage based on public-inbox-v2-format(5).  Commands will
       automatically initialize the store behind the scenes if needed, but you can call
       lei-init(1) directly if you want to use a store location other than the default
       "$XDG_DATA_HOME/lei/store".

       The lei-import(1) command provides the primary interface for importing messages into the
       local storage.  In addition, other commands, such as lei-q(1) and lei-blob(1), use the
       local store to memoize messages from remotes.

   EXAMPLES
       $ lei import mboxrd:t.mbox.gz
           Import the messages from a gzipped mboxrd into the local storage.

       $ lei blob 59ec517f9
           Show message with the git blob OID of 59ec517f9.  If a message with that OID isn't
           found, check if the current git repository has the blob, trying to reconstruct it from
           a message if needed.

       $ lei blob 59ec517f9 | lei tag -F eml +kw:flagged +L:next
           Set the "flagged" keyword and "next" label on the message with the blob OID of
           59ec517f9.

EXTERNALS

       In addition to the above store, lei can make read-only queries to "externals": inboxes and
       external indices.  An external can be registered by passing a URL or local path to
       lei-add-external(1).  For existing local paths, the external needs to be indexed with
       public-inbox-index(1) (in the case of a regular inbox) or public-inbox-extindex(1) (in the
       case of an external index).

SYNCHRONIZATION

       lei currently has primitive mail synchronization abilities; see lei-mail-sync-overview(7)
       for more details.

   EXAMPLES
       $ lei add-external https://public-inbox.org/meta/
           Add a remote external for public-inbox's inbox.

       $ lei add-external --mirror https://public-inbox.org/meta/ path
           Clone <https://public-inbox.org/meta/> to "path", index it with public-inbox-index(1),
           and add it as a local external.

SEARCHING

       The lei-q(1) command searches the local store and externals.  The search prefixes match
       those available via public-inbox-httpd(1).

   EXAMPLES
       $ lei q s:lei s:skeleton
           Search for messages whose subject includes "lei" and "skeleton".

       $ lei q -t s:lei s:skeleton
           Do the same, but also report unmatched messages that are in the same thread as a
           matched message.

       $ lei q -t -o /tmp/mdir --mua=mutt s:lei s:skeleton
           Write results to a Maildir at "mdir".  Mutt will be invoked to open mfolder ("mutt -f
           %f") while results are being fetched and written.

       $ lei q kw:flagged L:next
           Search for all flagged messages that also have a "next" label.

       $ lei p2q HEAD | lei q -tt -o /tmp/mdir
           Search for messages that have post-image git blob IDs that match those of the current
           repository's HEAD commit, writing them to the Maildir directory "mdir" and flagging
           the messages that were an exact match.

       $ git show -s HEAD | lei lcat
           Display a local message for the public-inbox link contained in a commit message.

       $ lei q -f text m:MESSAGE-ID | lei rediff -U5
           Feed a message containing a diff to lei-rediff(1) to regenerate its diff with five
           context lines.  Unless "--git-dir" is specified, this requires the current working
           directory to be within the associated code repository.

PERFORMANCE NOTES

       Inline::C is required, lei runs as a background daemon to reduce startup costs and can
       provide real-time kqueue(2)/inotify(7) Maildir monitoring.  IO::KQueue (p5-IO-KQueue on
       FreeBSD) and Linux::Inotify2 (liblinux-inotify2-perl and perl-Linux-Inotify2 in .deb and
       .rpm-based distros, respectively) are recommended.

       Socket::MsgHdr is optional (libsocket-msghdr-perl in Debian), and further improves startup
       performance.  Its effect is most felt when using shell completion.

BASH COMPLETION

       Preliminary Bash completion for lei is provided in "contrib/completion/".  Contributions
       adding support for other shells, as well as improvements to the existing Bash completion,
       are welcome.

UPGRADING

       Since lei runs as a daemon, lei-daemon-kill(1) is required to kill the daemon so it can
       load new code.  It will be restarted with the next invocation of any lei command.

CAVEATS

       IMAP and NNTP client performance is poor on high-latency connections.  It will hopefully
       be fixed in 2022.

CONTACT

       Feedback welcome via plain-text mail to <mailto:meta@public-inbox.org>

       The mail archives are hosted at <https://public-inbox.org/meta/> and
       <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>

COPYRIGHT

       Copyright all contributors <mailto:meta@public-inbox.org>

       License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>

SEE ALSO

       lei-mail-sync-overview(7)