quick_search/packaging/quicksearch.1

.\" The version in the .TH line above is rewritten from [workspace.package]
.\" version by packaging/build-deb.sh at package time; the literal here is
.\" only what an uninstalled read of this file shows.
.TH QUICKSEARCH 1 "2026-08-05" "quicksearch 1.0.2" "User Commands"
.SH NAME
quicksearch, quicksearch\-cli \- fast full\-text search across your files
.SH SYNOPSIS
.B quicksearch
.br
.B quicksearch
.RI [ FLAGS ]
.IR "query terms" ...
.br
.B quicksearch\-cli
.RI [ FLAGS ]
.IR "query terms" ...
.SH DESCRIPTION
.B quicksearch
maintains a SQLite/FTS5 index of the paths listed in its configuration and
searches it by filename and file content.
.PP
Invoked with no positional arguments it opens the desktop application, which
owns the indexer: it walks the configured roots, watches them for changes and
periodically reindexes.
.PP
Invoked with one or more query terms it runs the same ranked search cascade the
application uses, prints the results and exits. Terminal mode never starts the
indexer, the filesystem watcher or any background thread, so a one\-shot query
neither leaves anything running nor competes for inotify watches with a running
application. It requires an index that already exists; run the application once
to build one.
.PP
.B quicksearch\-cli
is terminal search and nothing else, and accepts the same flags and query
syntax. On this platform it is equivalent to giving
.B quicksearch
a query, and exists so that scripts and documentation have one name that never
opens a window. It matters on Windows, where the two cannot be one executable:
a GUI built as a console application flashes a console window at every launch,
and a console tool built as a GUI application cannot write back to the shell
that invoked it. Given no query it prints usage and exits 2 rather than falling
back to the application.
.SH OPTIONS
.TP
.B \-\-fuzzy
Also run the fuzzy filename and full\-text passes, which tolerate spelling
differences at the cost of speed. The edit distance comes from
.I [search].fuzzy_max_edits
in the configuration.
.TP
.BI \-\-limit " N"
Return at most
.I N
results. Defaults to
.I [search].display_limit
in the configuration.
.B \-\-limit=N
is also accepted.
.TP
.B \-\-long
Print rank, size, modification time and a matching snippet for each hit instead
of bare paths. Highlights the match in bold when stdout is a terminal.
.TP
.BR \-h ", " \-\-help
Print usage and exit.
.TP
.BR \-V ", " \-\-version
Print the version and the commit it was built from, then exit. Quote this in
bug reports.
.PP
An unrecognised option given without any query terms is passed through and the
application is opened, since it may be an option for the windowing backend.
.SH QUERY SYNTAX
Plain words form a single phrase, matched against names, contents and paths.
Filters may be combined with it:
.TP
.B \(dq\fIexact phrase\fB\(dq
Quoting keeps spaces, stars and filter\-like words literal.
.B \(dq\(dq
escapes a quote.
.TP
.BI bud * port
.B *
matches any run of characters, staying within one line of content.
.B %
and
.B _
are always literal.
.TP
.B regex:\fIpattern\fR
Match a regular expression against names, contents and paths, for example
.BR regex:\(dq(foo|bar)\ed+\(dq .
Case\-insensitive by default;
.B (?\-i:\(dq\(dq)
overrides. Quote patterns containing spaces or
.BR "( ) : = < > \(dq" .
.TP
.B type:\fIName\fR
Match a file class: one of
.IR Audio ", " Image ", " Video ", " Document ", " Text ", " Archive ", "
.IR Spreadsheet ", " Presentation ", " Folder .
.TP
.B modified:\fIexpr\fR
Compare against the modification date, for example
.IR modified:>=2024-01-01 .
Also
.BR < ", " <= ", " > " and " = ;
dates are
.IR yyyy-mm-dd .
.B mtime:
is an alias.
.TP
.B path:\fI/dir\fR
Restrict results to a directory and its subdirectories.
.B folder:
and
.B includefolder:
are aliases.
.B *
is literal here.
.TP
.B mime:\fItype\fR
Match a MIME type exactly, for example
.IR mime:application/pdf .
.TP
.B name:\fIfragment\fR
Match a fragment of the filename. A filter, so it does not affect ranking.
.B filename:
is an alias; an unquoted
.B *
globs.
.PP
Unrecognised
.I key:value
text stays part of the search phrase.
.BR AND ", " OR
and parentheses are treated as plain words.
.SH PASSWORD PROTECTION
The index can be encrypted with a password (the Settings tab, Security).
A protected index must be unlocked every time either binary starts. The
application shows an unlock screen; terminal mode resolves the key from, in
order: the OS keychain (when \(lqRemember on this device\(rq is enabled),
the
.B QUICKSEARCH_PASSWORD
environment variable, then a hidden interactive prompt with three attempts.
Without a terminal and with neither source available it exits 2 with an
explanatory message. A wrong password never modifies the index.
.PP
Enabling, disabling or changing the password deletes and rebuilds the index
from the application; the password itself is never stored, only a derived
key in the OS keychain when explicitly requested.
.SH ENVIRONMENT
.TP
.B QUICKSEARCH_PASSWORD
Password for a protected index, for scripted terminal search. Environment
variables are readable by other processes of the same user; prefer the
keychain where possible.
.SH FILES
.TP
.I ~/.config/quicksearch/config.toml
Configuration. Created with defaults on first run. See
.I /usr/share/doc/quicksearch/config_example.toml
for the annotated reference.
.TP
.I ~/.local/share/quicksearch/index.sqlite
The index. The location is set by
.I [paths].database_path
in the configuration.
.TP
.I ./config.toml
A configuration file placed next to the
.B quicksearch
executable selects portable mode and overrides the per\-user configuration
entirely. The packaged build deliberately installs no such file.
.PP
.I XDG_CONFIG_HOME
and
.I XDG_DATA_HOME
are honoured when set to absolute paths.
.SH EXIT STATUS
.TP
.B 0
The search completed, or
.B \-\-help
was requested.
.TP
.B 1
The application failed to start.
.TP
.B 2
The configuration could not be read, the index could not be opened or
unlocked, the query was rejected, or
.B quicksearch\-cli
was given no query.
.SH EXAMPLES
.TP
Search for a phrase:
.B quicksearch quarterly revenue report
.TP
Recent PDFs under a directory, with details:
.B quicksearch \-\-long type:Document mime:application/pdf path:/home/me/docs modified:>=2026-01-01
.TP
Tolerate misspellings and cap the output:
.B quicksearch \-\-fuzzy \-\-limit 10 recieve
.SH SEE ALSO
.I /usr/share/doc/quicksearch/README.md
.SH AUTHOR
Jeremy <jeremy@karsttech.com>