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 \-\-toggle
.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 \-\-toggle
Bring a running QuickSearch to the front with the search box focused, or start
it if none is running. Intended as the target of a key binding made in the
desktop's own keyboard settings.
.IP
QuickSearch also claims a shortcut of its own while it is running
.RI ( Ctrl+Shift+F
by default, rebindable to any combination on the Settings tab), which needs no
setting up. That one cannot fire while QuickSearch is not running, because
nothing a program registers for itself can; this option is what a desktop
binding runs so that a key can start it as well.
.IP
The activation reaches the running instance over a unix socket in
.IR $XDG_RUNTIME_DIR ,
named after the configuration file; when nothing answers, this process becomes
the application. On Wayland the window comes forward when the desktop supplied
an activation token for the launch (a binding made with the Settings tab's
set\-up button does); run by hand with no token, the window is highlighted in
the task bar instead.
.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
.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 \(em not the index's, which is a
setting that can change while running. Present only while the application is
running; a leftover one is inert and is replaced at the next start. Falls back
to a private directory under the temporary directory when
.I XDG_RUNTIME_DIR
is unset.
.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>