Documentation/lei-q.pod

   1 =head1 NAME
   2
   3 lei-q - search for messages matching terms
   4
   5 =head1 SYNOPSIS
   6
   7 lei q [OPTIONS] TERM [TERM...]
   8
   9 lei q [OPTIONS] (--stdin|-)
  10
  11 =head1 DESCRIPTION
  12
  13 Search for messages across the lei store and externals.
  14
  15 =for comment
  16 TODO: Give common prefixes, or at least a description/reference.
  17
  18 =head1 OPTIONS
  19
  20 =for comment
  21 TODO: mention curl options?
  22
  23 =over
  24
  25 =item --stdin
  26
  27 Read search terms from stdin.
  28
  29 =item --output=MFOLDER
  30
  31 =item -o MFOLDER
  32
  33 =item --mfolder=MFOLDER
  34
  35 Warning: this clobbers and overwrites the output destination unless
  36 L</--augment> is specified.
  37
  38 Destination for results (e.g., C</tmp/results-Maildir>,
  39 C<imaps://user@mail.example.com/INBOX.test>, or
  40 C<mboxcl2:/tmp/results-mboxcl2>).  The prefix may be a supported protocol:
  41 C<imap://> or C<imaps://>.  URLs requiring
  42 authentication must use L<netrc(5)> and/or L<git-credential(1)> to
  43 fill in the username and password.
  44
  45 A prefix can specify the format of the output: C<maildir>,
  46 C<mboxrd>, C<mboxcl2>, C<mboxcl>, C<mboxo>.  For a description of
  47 mail formats, see L<lei-mail-formats(5)>.
  48
  49 C<maildir> is the default for an existing directory or non-existing path.
  50
  51 Default: C<-> (stdout)
  52
  53 =item --format=FORMAT
  54
  55 =item -f FORMAT
  56
  57 Format of results to stdout.  This option exists as a convenient
  58 way to specify the format for the default stdout destination.
  59 C<text>, C<json>, C<jsonl>, or C<concatjson> are all supported,
  60 as are the various mbox variants described in L</--output>.
  61
  62 When a format isn't specified, it's chosen based on the
  63 L</--output> destination or prefix.  C<json> is used for the
  64 default destination (stdout).
  65
  66 Using a C<format:> prefix with the C<--output> destination is
  67 preferred when not writing to stdout.
  68
  69 =item --pretty
  70
  71 Pretty print C<json> or C<concatjson> output.  If stdout is opened to
  72 a tty and used as the C<--output> destination, C<--pretty> is enabled
  73 by default.
  74
  75 =item --mua=COMMAND
  76
  77 A command to run on C<--output> Maildir or mbox (e.g., C<mutt -f %f>).
  78 For a subset of MUAs known to accept a mailbox via C<-f>, COMMAND can
  79 be abbreviated to the name of the program: C<mutt>, C<mailx>, C<mail>,
  80 or C<neomutt>.
  81
  82 =item --alert=COMMAND[,COMMAND...]
  83
  84 Run C<COMMAND> after writing to output.  C<:WINCH> indicates to send
  85 C<SIGWINCH> to the C<--mua> process.  C<:bell> indicates to print a
  86 bell code.  Any other value is interpreted as a command to execute as
  87 is.
  88
  89 This option may be given multiple times.
  90
  91 Default: C<:WINCH,:bell> when C<--mua> is specified and C<--output>
  92 doesn't point to stdout, nothing otherwise.
  93
  94 =item --augment
  95
  96 =item -a
  97
  98 Augment output destination instead of clobbering it.
  99
 100 =item --no-import-before
 101
 102 Do not importing keywords before writing to an existing output
 103 destination.
 104
 105 =item --threads
 106
 107 =item -t
 108
 109 Return all messages in the same thread as the actual match(es).
 110
 111 Using this twice (C<-tt>) sets the C<flagged> (AKA "important")
 112 on messages which were actual matches.  This is useful to distinguish
 113 messages which were direct hits from messages which were merely part
 114 of the same thread.
 115
 116 TODO: Warning: this flag may become persistent and saved in
 117 lei/store unless an MUA unflags it!  (Behavior undecided)
 118
 119 =item --dedupe=STRATEGY
 120
 121 =item -d STRATEGY
 122
 123 Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
 124 C<none>.
 125
 126 Default: C<content>
 127
 128 =for comment
 129 TODO: Provide description of strategies?
 130
 131 =item --[no-]remote
 132
 133 Whether to include results requiring network access.  When local
 134 externals are configured, C<--remote> must be explicitly passed to
 135 enable reporting of results from remote externals.
 136
 137 =item --no-local
 138
 139 Limit operations to those requiring network access.
 140
 141 =item --no-external
 142
 143 Don't include results from externals.
 144
 145 =item --include=LOCATION
 146
 147 =item -I LOCATION
 148
 149 Include specified external in search.  This option may be given
 150 multiple times.
 151
 152 =item --exclude=LOCATION
 153
 154 Exclude specified external from search.  This option may be given
 155 multiple times.
 156
 157 =item --only=LOCATION
 158
 159 Use only the specified external for search.  This option may be given
 160 multiple times, in which case the search uses only the specified set.
 161
 162 =item --globoff
 163
 164 =item -g
 165
 166 Do not match locations using C<*?> wildcards and C<[]> ranges.  This
 167 option applies to C<--include>, C<--exclude>, and C<--only>.
 168
 169 =item --no-import-remote
 170
 171 Disable the default behavior of memoizing remote messages into the
 172 local store.
 173
 174 =item --lock
 175
 176 L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
 177 C<none>.
 178
 179 Default: fcntl,dotlock
 180
 181 =item --limit=NUMBER
 182
 183 =item -NUMBER
 184
 185 =item -n NUMBER
 186
 187 Limit the number of matches.
 188
 189 Default: 10000
 190
 191 =item --offset=NUMBER
 192
 193 Shift start of search results.
 194
 195 Default: 0
 196
 197 =item --reverse
 198
 199 =item -r
 200
 201 Reverse the results.  Note that this applies before C<--limit>.
 202
 203 =item --sort=KEY
 204
 205 =item -s KEY
 206
 207 Order the results by KEY.  Valid keys are C<received>, C<relevance>,
 208 and C<docid>.
 209
 210 Default: C<received>
 211
 212 =item --verbose
 213
 214 =item -v
 215
 216 Provide more feedback on stderr.
 217
 218 =item --quiet
 219
 220 =item -q
 221
 222 Suppress feedback messages.
 223
 224 =item --torsocks=auto|no|yes
 225
 226 =item --no-torsocks
 227
 228 Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
 229
 230 Default: C<auto>
 231
 232 =back
 233
 234 =head1 CONTACT
 235
 236 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 237
 238 The mail archives are hosted at L<https://public-inbox.org/meta/> and
 239 L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 240
 241 =head1 COPYRIGHT
 242
 243 Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
 244
 245 License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
 246
 247 =head1 SEE ALSO
 248
 249 L<lei-add-external(1)>,
 250 L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>