=head1 NAME

lei - an overview of lei

=head1 DESCRIPTION

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

=head1 LEI STORE

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

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

=head2 EXAMPLES

=over

=item $ lei import mboxrd:t.mbox.gz

Import the messages from a gzipped mboxrd into the local storage.

=item $ 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.

=item $ 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.

=back

=head1 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 L<lei-add-external(1)>.
For existing local paths, the external needs to be indexed with
L<public-inbox-index(1)> (in the case of a regular inbox) or
L<public-inbox-extindex(1)> (in the case of an external index).

=head1 SYNCHRONIZATION

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

=head2 EXAMPLES

=over

=item $ lei add-external https://public-inbox.org/meta/

Add a remote external for public-inbox's inbox.

=item $ lei add-external --mirror https://public-inbox.org/meta/ path

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

=back

=head1 SEARCHING

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

=head2 EXAMPLES

=over

=item $ lei q s:lei s:skeleton

Search for messages whose subject includes "lei" and "skeleton".

=item $ 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.

=item $ 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 (C<mutt -f %f>) while results are being fetched
and written.

=item $ lei q kw:flagged L:next

Search for all flagged messages that also have a "next" label.

=item $ 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.

=item $ git show -s HEAD | lei lcat

Display a local message for the public-inbox link contained in a
commit message.

=item $ lei q -f text m:MESSAGE-ID | lei rediff -U5

Feed a message containing a diff to L<lei-rediff(1)> to regenerate its
diff with five context lines.  Unless C<--git-dir> is specified, this
requires the current working directory to be within the associated
code repository.

=back

=head1 PERFORMANCE NOTES

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

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

=head1 BASH COMPLETION

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

=head1 UPGRADING

Since lei runs as a daemon, L<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.

=head1 CAVEATS

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

=head1 CONTACT

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

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

=head1 COPYRIGHT

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

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

=head1 SEE ALSO

L<lei-mail-sync-overview(7)>
