lei q [OPTIONS] TERM [TERM...]
-lei q [OPTIONS] --stdin
+lei q [OPTIONS] (--stdin|-)
=head1 DESCRIPTION
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
Read search terms from stdin.
-=item -o MFOLDER, --output=MFOLDER, --mfolder=MFOLDER
+=item --no-save
-Destination for results (e.g., C<path/to/Maildir> or
-C<mboxcl2:path/to/mbox>). The format can be specified by adding a
-C<E<lt>formatE<gt>:> prefix with any of these values: C<maildir>,
-C<mboxrd>, C<mboxcl2>, C<mboxcl>, C<mboxo>, C<json>, C<jsonl>, or
-C<concatjson>.
+Do not save the search for L<lei-up(1)>.
-TODO: Provide description of formats?
+=item --output=MFOLDER
-When a format isn't specified, it's chosen based on the destination.
-C<json> is used for the default destination (stdout), and C<maildir>
-is used for an existing directory or non-existing path.
+=item -o MFOLDER
-Default: -
+=item --mfolder=MFOLDER
-=item -f FORMAT, --format=FORMAT
+Warning: this clobbers and overwrites the output destination unless
+L</--augment> is specified.
-Format of results. This option exists as a convenient way to specify
-the format for the default stdout destination. Using a C<format:>
-prefix with the C<--output> destination is preferred otherwise.
+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 must use L<netrc(5)> and/or 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
+
+=item -f FORMAT
+
+Format of results to stdout. This option exists as a convenient
+way to specify the format for the default stdout destination.
+C<text>, C<json>, C<jsonl>, or C<concatjson> are all supported,
+as are the various mbox variants described in L</--output>.
+
+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).
+
+Using a C<format:> prefix with the C<--output> destination is
+preferred when not writing to stdout.
+
+=item --no-color
+
+Disable color (for C<--format=text>).
=item --pretty
Default: C<:WINCH,:bell> when C<--mua> is specified and C<--output>
doesn't point to stdout, nothing otherwise.
-=item -a, --augment
+=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).
Using this twice (C<-tt>) sets the C<flagged> (AKA "important")
-on messages which were actual messages. This is useful to distinguish
+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 -d STRATEGY, --dedupe=STRATEGY
+=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 -I LOCATION, --include=LOCATION
+=item --include=LOCATION
+
+=item -I LOCATION
Include specified external in search. This option may be given
multiple times.
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 -g, --globoff
+=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 -NUMBER, -n NUMBER, --limit=NUMBER
+=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
Limit the number of matches.
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 -q, --quiet
+=item --quiet
+
+=item -q
Suppress feedback messages.
-=item --torsocks=auto|no|yes, --no-torsocks
+=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 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
=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>