Documentation/lei-overview.pod

   1 =head1 NAME
   2
   3 lei - an overview of lei
   4
   5 =head1 DESCRIPTION
   6
   7 L<lei(1)> is a local email interface for public-inbox.  This document
   8 provides some basic examples.
   9
  10 =head1 LEI STORE
  11
  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>.
  16
  17 =head2 EXAMPLES
  18
  19 =over
  20
  21 =item $ lei import mboxrd:t.mbox
  22
  23 Import the messages from an mbox into the local storage.
  24
  25 =item $ lei blob 59ec517f9
  26
  27 Show message with the git blob OID of 59ec517f9.  If a message with
  28 that OID isn't found, check if the current git repository has the
  29 blob, trying to reconstruct it from a message if needed.
  30
  31 =item $ lei blob 59ec517f9 | lei mark - -F eml +kw:flagged +L:next
  32
  33 Set the "flagged" keyword and "next" label on the message with the
  34 blob OID of 59ec517f9.
  35
  36 =back
  37
  38 =head1 EXTERNALS
  39
  40 In addition to the above store, lei can make read-only queries to
  41 "externals": inboxes and external indices.  An external can be
  42 registered by passing a URL or local path to L<lei-add-external(1)>.
  43 For existing local paths, the external needs to be indexed with
  44 L<public-inbox-index(1)> (in the case of a regular inbox) or
  45 L<public-inbox-extindex(1)> (in the case of an external index).
  46
  47 =head2 EXAMPLES
  48
  49 =over
  50
  51 =item $ lei add-external https://public-inbox.org/meta/
  52
  53 Add a remote external for public-inbox's inbox.
  54
  55 =item $ lei add-external --mirror https://public-inbox.org/meta/ path
  56
  57 Clone L<https://public-inbox.org/meta/> to C<path>, index it with
  58 L<public-inbox-index(1)>, and add it as a local external.
  59
  60 =back
  61
  62 =head1 SEARCHING
  63
  64 The L<lei-q(1)> command searches the local store and externals.  The
  65 search prefixes match those available via L<public-inbox-httpd(1)>.
  66
  67 =head2 EXAMPLES
  68
  69 =over
  70
  71 =item $ lei q s:lei s:skeleton
  72
  73 Search for messages whose subject includes "lei" and "skeleton".
  74
  75 =item $ lei q -t s:lei s:skeleton
  76
  77 Do the same, but also report unmatched messages that are in the same
  78 thread as a matched message.
  79
  80 =item $ lei q -t -o mboxcl2:t.mbox --mua=mutt s:lei s:skeleton
  81
  82 Write mboxcl2-formatted results to t.mbox and enter mutt to view the
  83 file by invoking C<mutt -f %f>.
  84
  85 =item $ lei q kw:flagged L:next
  86
  87 Search for all flagged messages that also have a "next" label.
  88
  89 =item $ lei p2q HEAD | lei q --stdin -tt -o mdir
  90
  91 Search for messages that have post-image git blob IDs that match those
  92 of the current repository's HEAD commit, writing them to the Maildir
  93 directory "mdir" and flagging the messages that were an exact match.
  94
  95 =back
  96
  97 =head1 PERFORMANCE NOTES
  98
  99 L<Inline::C> is recommended for performance.  To enable it, create
 100 C<~/.cache/public-inbox/inline-c/>.
 101
 102 If Socket::MsgHdr is installed (libsocket-msghdr-perl in Debian), the
 103 first invocation of lei starts a daemon, reducing the startup cost of
 104 for future invocations (which is particularly important for Bash
 105 completion).
 106
 107 =head1 BASH COMPLETION
 108
 109 Preliminary Bash completion for lei is provided in
 110 C<contrib/completion/>.  Contributions adding support for other
 111 shells, as well as improvements to the existing Bash completion, are
 112 welcome.
 113
 114 =head1 CONTACT
 115
 116 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 117
 118 The mail archives are hosted at L<https://public-inbox.org/meta/>
 119 and L<http://hjrcffqmbrq6wope.onion/meta/>
 120
 121 =head1 COPYRIGHT
 122
 123 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
 124
 125 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>