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
=item -o MFOLDER, --output=MFOLDER, --mfolder=MFOLDER
-Destination for results (e.g., C<path/to/Maildir> or - for stdout).
+Warning: this clobbers and overwrites the output destination unless
+L</-a, --augment> is specified.
-Default: -
+Destination for results (e.g., C<path/to/Maildir>,
+C<imaps://user@mail.example.com/INBOX.test>, or
+C<mboxcl2:path/to/mbox>). 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.
-=item -f FORMAT, --format=FORMAT
-
-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>.
+The prefix can instead specify the format of the output: C<maildir>,
+C<mboxrd>, C<mboxcl2>, C<mboxcl>, C<mboxo>, C<json>, C<jsonl>, or
+C<concatjson>. 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.
+=for comment
TODO: Provide description of formats?
+Default: C<-> (stdout)
+
+=item -f FORMAT, --format=FORMAT
+
+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.
+
=item --pretty
Pretty print C<json> or C<concatjson> output. If stdout is opened to
Augment output destination instead of clobbering it.
+=item --no-import-before
+
+Do not importing keywords before writing to an existing output
+destination.
+
=item -t, --threads
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 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
Strategy for deduplicating messages: C<content>, C<oid>, C<mid>, or
Default: C<content>
+=for comment
TODO: Provide description of strategies?
=item --[no-]remote
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
+
+L<mbox(5)> locking method(s) to use: C<dotlock>, C<fcntl>, C<flock> or
+C<none>.
+
+Default: fcntl,dotlock
+
=item -NUMBER, -n NUMBER, --limit=NUMBER
Limit the number of matches.