--- name: "lei-overview" section: "7" platform: "linux" package: "lei" version: "2.1.0-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/lei-overview" --- # lei-overview(7) an overview of lei ## NAME lei - an overview of lei ## DESCRIPTION [**lei**(1)](/lei/1.md) 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)](/public-inbox-v2-format/5.md). Commands will automatically initialize the store behind the scenes if needed, but you can call [**lei-init**(1)](/lei-init/1.md) directly if you want to use a store location other than the default `"$XDG_DATA_HOME/lei/store"`. The [**lei-import**(1)](/lei-import/1.md) command provides the primary interface for importing messages into the local storage. In addition, other commands, such as [**lei-q**(1)](/lei-q/1.md) and [**lei-blob**(1)](/lei-blob/1.md), 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)](/lei-add-external/1.md). For existing local paths, the external needs to be indexed with [**public-inbox-index**(1)](/public-inbox-index/1.md) (in the case of a regular inbox) or [**public-inbox-extindex**(1)](/public-inbox-extindex/1.md) (in the case of an external index). ## SYNCHRONIZATION lei currently has primitive mail synchronization abilities; see [**lei-mail-sync-overview**(7)](/lei-mail-sync-overview/7.md) 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 \ to `"path"`, index it with [**public-inbox-index**(1)](/public-inbox-index/1.md), and add it as a local external. ## SEARCHING The [**lei-q**(1)](/lei-q/1.md) command searches the local store and externals. The search prefixes match those available via [**public-inbox-httpd**(1)](/public-inbox-httpd/1.md). ### 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)](/lei-rediff/1.md) 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 on BSDs and can speed things up on Linux. lei runs as a background daemon to reduce startup costs and can provide real-time [**kqueue**(2)](/kqueue/2.md)/[**inotify**(7)](/inotify/7.md) 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)](/lei-daemon-kill/1.md) 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 \ The mail archives are hosted at \ and \ ## COPYRIGHT Copyright all contributors \ License: AGPL-3.0+ \ ## SEE ALSO [**lei-mail-sync-overview**(7)](/lei-mail-sync-overview/7.md)