quick_search/packaging/quicksearch.1

.\" packaging/build-deb.sh rewrites the version in the .TH line below from
.\" [workspace.package] version; the literal here only shows when this file is
.\" read uninstalled.
.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 \-\-toggle
.br
.B quicksearch
.RI [ FLAGS ]
.RB [ \-\- ]
.IR "query terms" ...
.br
.B quicksearch\-cli
.RI [ FLAGS ]
.RB [ \-\- ]
.IR "query terms" ...
.SH DESCRIPTION
.B quicksearch
maintains a SQLite/FTS5 index of the folders in its configuration and searches
it by file name and content.
.PP
With no arguments it opens the desktop application, which owns the indexer: it
walks the configured folders, watches them for changes and reindexes
periodically.
.PP
With one or more query terms it runs the application's ranked search, prints
the results and exits. Terminal mode never starts the indexer, the file watcher
or any background thread, so a one\-shot query leaves nothing running and does
not compete with a running application for inotify watches. It needs an
existing index; run the application once to build one.
.PP
.B quicksearch\-cli
is terminal search only: it takes the same flags and query syntax, never opens
a window, and exits 2 with usage when given no query. On Linux it is equivalent
to giving
.B quicksearch
a query; on Windows it is required, because one executable cannot be both a
GUI and a console program.
.SH OPTIONS
.TP
.B \-\-toggle
Bring a running QuickSearch to the front with the search box focused, or start
it if none is running. Bind a key to this in your desktop's keyboard settings.
.IP
While running, QuickSearch also holds a shortcut of its own
.RI ( Ctrl+Shift+F
by default, changeable on the Settings tab), but that cannot start it when it
is closed; this option can.
.IP
The request reaches the running instance through a socket in
.IR $XDG_RUNTIME_DIR ,
named after the configuration file; if nothing answers, this process becomes
the application. On Wayland the window comes forward only if the launcher
supplied an activation token (bindings made with the Settings tab's set\-up
button do); otherwise it is highlighted in the task bar.
.TP
.B \-\-fuzzy
Also run the fuzzy file name and full\-text passes, which tolerate
misspellings at some cost in speed. The edit budget comes from
.I [search].fuzzy_max_edits
in the configuration.
.TP
.BI \-\-limit " N"
Return at most
.I N
results, where
.I N
is a positive integer. Defaults to
.I [search].display_limit
in the configuration.
.B \-\-limit=N
also works.
.TP
.B \-\-long
Print rank, size, modification time and a matching snippet for each hit instead
of bare paths, with the match in bold when stdout is a terminal.
.TP
.B \-\-
End the options: every later argument is a query term, even one that starts
with
.BR \- .
.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
Options come before the query terms. From the first term on, every argument is
part of the query, so a
.B \-h
after a term is searched for. An unrecognised option, a
.B \-\-limit
that is not a positive integer, or options with no query terms are a usage
error.
.SH QUERY SYNTAX
Plain words form a single phrase, matched against names, contents and paths.
Filters combine 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:(foo|bar)\ed+ .
Case\-insensitive by default;
.BI (?\-i: pattern )
overrides. Quote patterns containing spaces or a leading
.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 .
Every operator compares whole days in the local time zone:
.I >2024-01-01
starts on January 2, and
.I <=2024-01-01
includes all of January 1.
.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 file name. 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 (Settings tab, Security). A
protected index must be unlocked every time either binary starts. The
application shows an unlock screen; terminal mode takes the key from, in
order: the OS keychain (when \(lqRemember on this device\(rq is on), the
.B QUICKSEARCH_PASSWORD
environment variable, then a hidden prompt with three attempts. Without a
terminal and with neither source available it exits 2 with an explanation. A
wrong password never modifies the index.
.PP
Enabling, disabling or changing the password deletes and rebuilds the index.
The password itself is never stored; only a derived key is, in the OS
keychain, and only on request.
.SH ENVIRONMENT
.TP
.B QUICKSEARCH_PASSWORD
Password for a protected index, for scripted terminal search. Set but empty,
it counts as unset. Other processes of the same user can read environment
variables; prefer the keychain where possible.
.SH FILES
.TP
.I ~/.config/quicksearch/config.toml
Configuration, created with defaults on first run.
.I /usr/share/doc/quicksearch/config_example.toml
documents every key.
.TP
.I ~/.local/share/quicksearch/index.sqlite
The index;
.I [paths].database_path
in the configuration sets its location.
.TP
.IR $XDG_RUNTIME_DIR /quicksearch\- <key> .sock
The socket
.B \-\-toggle
connects to, where
.I <key>
is a hash of the configuration file's path (not the index's, which can change
while running). Present only while the application runs; a leftover one is
inert and is replaced at the next start. Falls back to
.RI quicksearch\- <uid>
under the temporary directory when
.I XDG_RUNTIME_DIR
is unset. That directory must be the user's own with mode 0700; one that is
not is refused, and
.B \-\-toggle
then cannot reach the running instance.
.TP
.I ./config.toml
A configuration file next to the
.B quicksearch
executable, or the AppImage, selects portable mode and overrides the
per\-user configuration entirely, unless it has a top\-level table that is
not one of QuickSearch's own: another program's
.I config.toml
there is ignored, with a warning in the log. One that fails to parse still
counts, and the program reports the error. The packaged build 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 (also when the reader of a pipe stops early, as
.B head
does), or
.B \-\-help
or
.B \-\-version
was requested.
.TP
.B 1
The application failed to start.
.TP
.B 2
A usage error, the configuration could not be read, the index could not be
opened or unlocked, the query was rejected, the results could not be written,
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
.IR /usr/share/doc/quicksearch/README.md ,
.I /usr/share/doc/quicksearch/config_example.toml
.SH AUTHOR
Jeremy <jeremy@karsttech.com>