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