LEI-OVERVIEW(7)

📦
version 2.1.0 · 5 versions
, in arch rolling, nixos 26.05, nixpkgs unstable

💅 lei-overview — okay bestie, let's talk about lei

so this page is from the public-inbox user manual and it's literally your starter pack for lei, iykyk 🫶

✨ NAME ✨

lei — an overview of lei (yes that's the whole name section, she's brief and iconic)

🌸 DESCRIPTION 🌸

okay so lei(1) is a local email interface for public-inbox and your personal mail. That's the whole vibe. This doc is just here to hand you some basic examples so you can get going 💖

🎀 LEI STORE 🎀

lei has writable local storage, and it's based on public-inbox-v2-format(5). No cap.

Commands will automatically initialize the store behind the scenes if it's needed — like, it just does it for you, you don't have to ask. But if you want your store somewhere other than the default "$XDG_DATA_HOME/lei/store", you can call lei-init(1) directly. Main character energy fr fr.

lei-import(1) is the primary interface for importing messages into the local storage. And on top of that, other commands — like lei-q(1) and lei-blob(1) — use the local store to memoize messages from remotes. Slay.

⭐ EXAMPLES ⭐

  • $ lei import mboxrd:t.mbox.gz — Import the messages from a gzipped mboxrd into the local storage. Easy.
  • $ lei blob 59ec517f9 — Show the message with the git blob OID of 59ec517f9. And if a message with that OID isn't found? Check if the current git repository has the blob, and it'll try to reconstruct it from a message if needed. Resourceful queen 💅
  • $ 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. Look at her go 😭

🦋 EXTERNALS 🦋

so besides that store up there, lei can also make read-only queries to "externals" — which is the cute word for inboxes and external indices.

You register an external by passing a URL or a local path to lei-add-external(1). And for existing local paths? The external needs to be indexed with public-inbox-index(1) (if it's a regular inbox) or public-inbox-extindex(1) (if it's an external index). Don't skip that step bestie, it's giving necessary 🔥

🌈 SYNCHRONIZATION 🌈

ngl, lei currently has primitive mail synchronization abilities — like, it works, it's just baby steps. See lei-mail-sync-overview(7) for more details 🧚

💜 EXAMPLES 💜

🔥 SEARCHING 🔥

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

🍓 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. Thread-aware queen 👑
  • $ 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. Multitasking icon.
  • $ lei q kw:flagged L:next — Search for all flagged messages that also have a "next" label. Filtered and fabulous ✨
  • $ lei p2q HEAD | lei q -tt -o /tmp/mdir — Search for messages that have post-image git blob IDs matching those of the current repository's HEAD commit, write them to the Maildir directory "mdir", and flag the messages that were an exact match. That's a pipeline, bestie 💅
  • $ git show -s HEAD | lei lcat — Display a local message for the public-inbox link contained in a commit message. Cute.
  • $ 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. ⚠️ heads up: unless --git-dir is specified, this requires the current working directory to be within the associated code repository. No wandering off 🫶

👑 PERFORMANCE NOTES 👑

  • Inline::C is required on BSDs, and it can speed things up on Linux. Required vs. nice-to-have, know the difference.
  • lei runs as a background daemon to reduce startup costs, and it can provide real-time kqueue(2)/inotify(7) Maildir monitoring. For that you want IO::KQueue (p5-IO-KQueue on FreeBSD) and Linux::Inotify2 (liblinux-inotify2-perl and perl-Linux-Inotify2 in .deb and .rpm-based distros, respectively) — they're recommended, so like, get them if you can 🌸
  • Socket::MsgHdr is optional (libsocket-msghdr-perl in Debian), and it further improves startup performance. Its effect is most felt when you're using shell completion. So if completion feels slow, that's your girl 💀

🧚 BASH COMPLETION 🧚

Preliminary Bash completion for lei is provided in "contrib/completion/". And listen — contributions adding support for other shells, plus improvements to the existing Bash completion, are welcome. Come through, contributors 🫶

💀 UPGRADING 💀

Since lei runs as a daemon, lei-daemon-kill(1) is required to kill the daemon so it can load new code. You can't just... not do it. It will be restarted with the next invocation of any lei command, so she comes right back 🔥

🙈 CAVEATS 🙈

IMAP and NNTP client performance is poor on high-latency connections. It will hopefully be fixed in 2022. (yes, that's what it says. we're all rooting for her 😭)

ngl this one's a real caveat, not a vibe — if you're on a high-latency connection, expect IMAP and NNTP to be slow.

💌 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 all contributors <mailto:meta@public-inbox.org>

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

🌟 SEE ALSO 🌟

okay that's the page!! this one's from public-inbox.git, dated 1993-10-02, and that's your whole overview — now go import something and slay ✨🎀💜

📦 where this page comes from