lei q [OPTIONS] TERM [TERM...]
+lei q [OPTIONS] (--stdin|-)
+
=head1 DESCRIPTION
-Search for messages across the lei store and externals.
+Search for messages across the lei/store and externals.
+=for comment
TODO: Give common prefixes, or at least a description/reference.
=head1 OPTIONS
+=for comment
+TODO: mention curl options?
+
=over
-=item -o PATH, --output=PATH, --mfolder=PATH
+=item --stdin
+
+Read search terms from stdin.
+
+=item --no-save
+
+Do not save the search for L<lei-up(1)>.
+
+=item --output=MFOLDER
+
+=item -o MFOLDER
+
+=item --mfolder=MFOLDER
+
+Warning: this clobbers and overwrites the output destination unless
+L</--augment> is specified.
+
+Destination for results (e.g., C</tmp/results-Maildir>,
+C<imaps://user@mail.example.com/INBOX.test>, or
+C<mboxcl2:/tmp/results-mboxcl2>). The prefix may be a supported protocol:
+C<imap://> or C<imaps://>. URLs requiring
+authentication use L<git-credential(1)> to
+fill in the username and password.
+
+A prefix can specify the format of the output: C<maildir>,
+C<mboxrd>, C<mboxcl2>, C<mboxcl>, C<mboxo>. For a description of
+mail formats, see L<lei-mail-formats(5)>.
+
+C<maildir> is the default for an existing directory or non-existing path.
+
+Default: C<-> (stdout)
+
+=item --format=FORMAT
-Destination for results (e.g., C<path/to/Maildir> or - for stdout).
+=item -f FORMAT
-Default: -
+Format of results to stdout. This option exists as a convenient
+way to specify the format for the default stdout destination.
+C<reply>, C<text>, C<json>, C<jsonl>, or C<concatjson> are all supported,
+as are the various mbox variants described in L</--output>.
-=item -f FORMAT, --format=FORMAT
+When a format isn't specified, it's chosen based on the
+L</--output> destination or prefix. C<json> is used for the
+default destination (stdout).
-Format of results: C<maildir>, C<mboxrd>, C<mboxcl2>, C<mboxcl>,
-C<mboxo>, C<json>, C<jsonl>, or C<concatjson>. The default format
-used depends on C<--output>.
+Using a C<format:> prefix with the C<--output> destination is
+preferred when not writing to stdout.
-TODO: Provide description of formats?
+=item --no-color
+
+Disable color (for C<-f reply> and C<-f text>).
=item --pretty
be abbreviated to the name of the program: C<mutt>, C<mailx>, C<mail>,
or C<neomutt>.
-=item -a, --augment
+=item --alert=COMMAND[,COMMAND...]
+
+Run C<COMMAND> after writing to output. C<:WINCH> indicates to send
+C<SIGWINCH> to the C<--mua> process. C<:bell> indicates to print a
+bell code. Any other value is interpreted as a command to execute as
+is.
+
+This option may be given multiple times.
+
+Default: C<:WINCH,:bell> when C<--mua> is specified and C<--output>
+doesn't point to stdout, nothing otherwise.
+
+=item --augment
+
+=item -a
Augment output destination instead of clobbering it.
-=item -t, --threads
+=item --no-import-before
+
+Do not import keywords before writing to an existing output
+destination.
+
+=item --threads
+
+=item -t
Return all messages in the same thread as the actual match(es).
-=item -d STRATEGY, --dedupe=STRATEGY
+Using this twice (C<-tt>) sets the C<flagged> (AKA "important")
+on messages which were actual matches. This is useful to distinguish
+messages which were direct hits from messages which were merely part
+of the same thread.
+
+TODO: Warning: this flag may become persistent and saved in
+lei/store unless an MUA unflags it! (Behavior undecided)
+
+=item --dedupe=STRATEGY
+
+=item -d STRATEGY
Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
C<none>.
Default: C<content>
+=for comment
TODO: Provide description of strategies?
=item --[no-]remote
Don't include results from externals.
-=item -NUMBER, -n NUMBER, --limit=NUMBER
+=item --include=LOCATION
+
+=item -I LOCATION
-Limit the number of matches.
+Include specified external in search. This option may be given
+multiple times.
+
+=item --exclude=LOCATION
+
+Exclude specified external from search. This option may be given
+multiple times.
+
+=item --only=LOCATION
+
+=item -O LOCATION
+
+Use only the specified external for search. This option may be given
+multiple times, in which case the search uses only the specified set.
+
+=item --globoff
+
+=item -g
+
+Do not match locations using C<*?> wildcards and C<[]> ranges. This
+option applies to C<--include>, C<--exclude>, and C<--only>.
+
+=item --no-import-remote
+
+Disable the default behavior of memoizing remote messages into the
+local store.
+
+=item --lock=METHOD
+
+L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
+C<none>.
+
+Default: fcntl,dotlock
+
+=item --limit=NUMBER
+
+=item -NUMBER
+
+=item -n NUMBER
+
+Fuzzy limit the number of matches per-local external and lei/store.
+Messages added by the L<--threads> switch do not count towards this
+limit, and there is no limit on remote externals.
Default: 10000
Default: 0
-=item -r, --reverse
+=item --reverse
+
+=item -r
Reverse the results. Note that this applies before C<--limit>.
-=item -s KEY, --sort=KEY
+=item --sort=KEY
+
+=item -s KEY
Order the results by KEY. Valid keys are C<received>, C<relevance>,
and C<docid>.
Default: C<received>
-=item -v, --verbose
+=item --verbose
+
+=item -v
Provide more feedback on stderr.
-=item --torsocks=auto|no|yes, --no-torsocks
+=item --quiet
+
+=item -q
+
+Suppress feedback messages.
+
+=item --torsocks=auto|no|yes
+
+=item --no-torsocks
Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.
Default: C<auto>
+=item --proxy=PROTO://HOST[:PORT]
+
=back
+=head1 SEARCH TERMS
+
+C<lei q> supports the same search prefixes used by HTTP(S) public-inbox
+instances:
+
+=for comment
+AUTO-GENERATED-SEARCH-TERMS-BEGIN
+
+ s: match within Subject e.g. s:"a quick brown fox"
+ d: match date-time range, git "approxidate" formats supported
+ Open-ended ranges such as `d:last.week..' and
+ `d:..2.days.ago' are supported
+ b: match within message body, including text attachments
+ nq: match non-quoted text within message body
+ q: match quoted text within message body
+ n: match filename of attachment(s)
+ t: match within the To header
+ c: match within the Cc header
+ f: match within the From header
+ a: match within the To, Cc, and From headers
+ tc: match within the To and Cc headers
+ l: match contents of the List-Id header
+ bs: match within the Subject and body
+ dfn: match filename from diff
+ dfa: match diff removed (-) lines
+ dfb: match diff added (+) lines
+ dfhh: match diff hunk header context (usually a function name)
+ dfctx: match diff context lines
+ dfpre: match pre-image git blob ID
+ dfpost: match post-image git blob ID
+ dfblob: match either pre or post-image git blob ID
+ rt: match received time, like `d:' if sender's clock was correct
+
+=for comment
+AUTO-GENERATED-SEARCH-TERMS-END
+
+Additional search prefixes which only affect the local lei/store:
+
+ L: match the given label
+ kw: match the given keywords
+
+See L<lei-tag(1)> for more info on labels and keywords.
+
+Most prefixes are probabilistic, meaning they support stemming
+and wildcards (C<*>). Ranges (such as C<d:>) and boolean prefixes
+do not support stemming or wildcards.
+The upstream Xapian query parser documentation fully explains
+the query syntax: L<https://xapian.org/docs/queryparser.html>
+
+=head1 TIPS
+
+C<-f reply> is intended to aid in turning a cover letter
+into a reply (since using C<git format-patch --in-reply-to=...>
+is tedious). Results (including "From " lines) should be edited
+and trimmed in your favorite C<$EDITOR> before sending.
+
=head1 CONTACT
Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
-The mail archives are hosted at L<https://public-inbox.org/meta/>
-and L<http://hjrcffqmbrq6wope.onion/meta/>
+The mail archives are hosted at L<https://public-inbox.org/meta/> and
+L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
=head1 COPYRIGHT
-Copyright 2021 all contributors L<mailto:meta@public-inbox.org>
+Copyright all contributors L<mailto:meta@public-inbox.org>
License: AGPL-3.0+ L<https://www.gnu.org/licenses/agpl-3.0.txt>
=head1 SEE ALSO
-L<lei-add-external(1)>,
+L<lei-add-external(1)>, L<lei-lcat(1)>, L<lei-up(1)>,
L<Xapian::QueryParser Syntax|https://xapian.org/docs/queryparser.html>