QUICKSEARCH(1)

NAME
quicksearch, quicksearch-cli - fast full-text search across your files

SYNOPSIS
quicksearch
quicksearch [FLAGS] query terms...
quicksearch-cli [FLAGS] query terms...

DESCRIPTION
quicksearch maintains a SQLite/FTS5 index of the paths listed in its configuration and searches it by filename and file content.

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.

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.

quicksearch-cli is terminal search and nothing else, and accepts the same flags and query syntax. On this platform it is equivalent to giving 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.

OPTIONS

--fuzzy
    Also run the fuzzy filename and full-text passes, which tolerate spelling differences at the cost of speed. The edit distance comes from [search].fuzzy_max_edits in the configuration.

--limit N
    Return at most N results. Defaults to [search].display_limit in the configuration. --limit=N is also accepted.

--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.

-h, --help
    Print usage and exit.

-V, --version
    Print the version and the commit it was built from, then exit. Quote this in bug reports.

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.

QUERY SYNTAX
Plain words form a single phrase, matched against names, contents and paths. Filters may be combined with it:

"exact phrase"
    Quoting keeps spaces, stars and filter-like words literal. "" escapes a quote.

bud*port
    * matches any run of characters, staying within one line of content. % and _ are always literal.

regex:pattern
    Match a regular expression against names, contents and paths, for example regex:"(foo|bar)\d+". Case-insensitive by default; (?-i:"") overrides. Quote patterns containing spaces or ( ) : = < > ".

type:Name
    Match a file class: one of Audio, Image, Video, Document, Text, Archive, Spreadsheet, Presentation, Folder.

modified:expr
    Compare against the modification date, for example modified:>=2024-01-01. Also <, <=, > and =; dates are yyyy-mm-dd. mtime: is an alias.

path:/dir
    Restrict results to a directory and its subdirectories. folder: and includefolder: are aliases. * is literal here.

mime:type
    Match a MIME type exactly, for example mime:application/pdf.

name:fragment
    Match a fragment of the filename. A filter, so it does not affect ranking. filename: is an alias; an unquoted * globs.

Unrecognised key:value text stays part of the search phrase. AND, OR and parentheses are treated as plain words.

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 “Remember on this device” is enabled), the 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.

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.

ENVIRONMENT

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.

FILES

~/.config/quicksearch/config.toml
    Configuration. Created with defaults on first run. See /usr/share/doc/quicksearch/config_example.toml for the annotated reference.

~/.local/share/quicksearch/index.sqlite
    The index. The location is set by [paths].database_path in the configuration.

./config.toml
    A configuration file placed next to the quicksearch executable selects portable mode and overrides the per-user configuration entirely. The packaged build deliberately installs no such file.

XDG_CONFIG_HOME and XDG_DATA_HOME are honoured when set to absolute paths.

EXIT STATUS

0   The search completed, or --help was requested.

1   The application failed to start.

2   The configuration could not be read, the index could not be opened or unlocked, the query was rejected, or quicksearch-cli was given no query.

EXAMPLES

Search for a phrase:
    quicksearch quarterly revenue report

Recent PDFs under a directory, with details:
    quicksearch --long type:Document mime:application/pdf path:/home/me/docs modified:>=2026-01-01

Tolerate misspellings and cap the output:
    quicksearch --fuzzy --limit 10 recieve

SEE ALSO
/usr/share/doc/quicksearch/README.md

AUTHOR
Jeremy <jeremy@karsttech.com>