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 ]
.IR "query terms" ...
.br
.B quicksearch\-cli
.RI [ FLAGS ]
.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 query 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. 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
.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 query terms is passed through and the
application opens, since the option may be meant for the windowing backend.
.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:\(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 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. 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 a private directory
under the temporary directory when
.I XDG_RUNTIME_DIR
is unset.
.TP
.I ./config.toml
A configuration file next to the
.B quicksearch
executable selects portable mode and overrides the per\-user configuration
entirely. 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, 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
.IR /usr/share/doc/quicksearch/README.md ,
.I /usr/share/doc/quicksearch/config_example.toml
.SH AUTHOR
Jeremy <jeremy@karsttech.com>