lei q [OPTIONS] TERM [TERM...]
+lei q [OPTIONS] --stdin
+
=head1 DESCRIPTION
Search for messages across the lei store and externals.
=head1 OPTIONS
+TODO: mention curl options?
+
=over
-=item -o PATH, --output=PATH, --mfolder=PATH
+=item --stdin
+
+Read search terms from stdin.
+
+=item -o MFOLDER, --output=MFOLDER, --mfolder=MFOLDER
+
+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>.
+
+TODO: Provide description of formats?
-Destination for results (e.g., C<path/to/Maildir> or - for stdout).
+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.
Default: -
=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>.
-
-TODO: Provide description of formats?
+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
a tty and used as the C<--output> destination, C<--pretty> is enabled
by default.
-=item --mua-cmd=COMMAND, --mua=COMMAND
+=item --mua=COMMAND
A command to run on C<--output> Maildir or mbox (e.g., C<mutt -f %f>).
For a subset of MUAs known to accept a mailbox via C<-f>, COMMAND can
be abbreviated to the name of the program: C<mutt>, C<mailx>, C<mail>,
or C<neomutt>.
+=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 -a, --augment
Augment output destination instead of clobbering it.
-=item -t, --thread
+=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 messages. 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
Don't include results from externals.
+=item -I LOCATION, --include=LOCATION
+
+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
+
+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
+
+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
Limit the number of matches.
Provide more feedback on stderr.
+=item -q, --quiet
+
+Suppress feedback messages.
+
=item --torsocks=auto|no|yes, --no-torsocks
Whether to wrap L<git(1)> and L<curl(1)> commands with torsocks.