Pseek

Fast and powerful command-line search tool for finding files, directories, and text content.

Features

• Search file names
• Search directory names
• Search file contents
• Search inside archive files
• Boolean query expressions (and, or, not)
• Regular expressions
• Fuzzy matching
• Whole-word matching
• Case-sensitive search
• Archive recursion depth control
• Extension filters
• Path filters
• Size filtering
• Full path output
• Highlight matches in output
• Cross-platform (Linux, macOS, Windows)

Installation

Install from PyPI (Recommended)

pip install pseek

Install from Source

git clone https://github.com/grootle/pseek.git

cd pseek

python -m venv venv

# Activate virtual environment

pip install click==8.1.8 lark==1.2.2 py7zr==1.0.0 rarfile==4.2 rapidfuzz==3.13.0

Basic Usage

psk <query> [options]

Example:

psk "error"

If no search type is specified, Pseek searches:

• File names
• Directory names
• File contents

simultaneously.

Command Options

Option	Description
--path	Base directory to search in (default: current directory .)
--file	Search only in file names
--directory	Search only in directory names
--content	Search within file contents
--ext, --exclude-ext	Filter by file extension (e.g., txt, log)
--case-sensitive	Make the search case-sensitive (except when --expr is enabled, in which case you can make it case sensitive by putting c before term: c"foo")
--regex	Use regular expressions to search (except when --expr is enabled, in which case you can make it regex by putting r before term: r"foo")
--include, --exclude	Limit search results to specific set of directories or files
--re-include, --re-exclude	Limit search results to specific directories or files with regex
--word	Match the whole word only (except when --expr is enabled, in which case you can make it match whole word by putting w before term: w"foo")
--expr	Enable boolean query expressions. Example: r"foo.*bar" and ("bar" or "baz") and not "qux". Prefixes: r=regex, c=case-sensitive, w=whole-word, f=fuzzy
--timeout	Stop the search after the specified number of seconds
--fuzzy	Enable fuzzy search (Highlighting and counting matches are disabled in this mode if --word is not enabled to prevent the program from slowing down). except when --expr is enabled, in which case you can make it fuzzy by putting f before term: f"foo"
--fuzzy-level	Fuzzy matching threshold (0-99). Higher values require closer matches (default: 80)
--max-size, --min-size	Specify maximum and minimum sizes for files and directories
--archive	Enable search within archive files (e.g. zip, rar, 7z, gz, bz2, xz, tar, tar.gz, tar.bz2, tar.xz)
--depth	Maximum nested archive depth. Example: 2 allows searching up to two archive levels
--arc-ext, --arc-exc-ext	Filter by file extension inside archive files
--arc-include, --arc-exclude	Limit search results to specific set of directories or files inside archive files
--arc-max, --arc-min	Specify maximum and minimum sizes for files inside archive files (It doesn't work for directories because their size is zero in archive files)
--rar-backend	Path to RAR backend tool (e.g. UnRAR.exe, ...)
--full-path	Display full path of files and directories
--paths-only	Only show matching file paths for content search

Search Types

Search File Names

psk "config" --file

Search Directory Names

psk "backup" --directory

Search File Contents

psk "TODO" --content

Search Everywhere

psk "error"

Equivalent to:

psk "error" --file --directory --content

Query Modes

By default, the query is treated as plain text.

Example:

psk "hello world"

Case Sensitive Search

psk "Hello" --case-sensitive

Matches:

Hello

Does not match:

hello
HELLO

Whole Word Search

psk "cat" --word

Matches:

cat

Does not match:

cats
concatenate

Regular Expression Search

Enable regex mode:

psk "error\d+" --regex

Example matches:

error1
error25
error999

Fuzzy Search

Fuzzy search allows approximate matching.

Example:

psk "apple" --fuzzy

Can match:

appl
appel
aple

Fuzzy Similarity Threshold

psk "apple" --fuzzy --fuzzy-level 90

Range: 0-99

Higher values require closer matches.

Examples:

Level	Strictness
60	Loose
80	Recommended
95	Very strict

Default: 80

Expression Queries

Expression mode enables logical search expressions.

Enable:

psk '("error" or "warning") and not "debug"' --expr

Supported Operators

AND

psk '"foo" and "bar"' --expr

Both terms must match.

OR

psk '"foo" or "bar"' --expr

At least one term must match.

NOT

psk 'not "foo"' --expr

Exclude matches containing the term.

PARENTHESES

psk '("foo" or "bar") and not "baz"' --expr

Used for grouping expressions.

Expression Prefixes

Each term can have its own search mode.

Regex

r"pattern"

Example:

psk 'r"error\d+"' --expr

Case Sensitive

c"text"

Example:

psk 'c"Error"' --expr

Whole Word

w"text"

Example:

psk 'w"cat"' --expr

Fuzzy

f"text"

Example:

psk 'f"apple"' --expr

Combined Prefixes

Prefixes can be combined.

Examples:

rc"text"
cw"text"
cf"text"
wcf"text"

Example:

psk 'rc"Error\d+"' --expr

Meaning:

• regex
• case-sensitive

simultaneously.

Allowed modes: r, c, w, f, rc, cr, cw, wc, cf, fc, wf, fw, cwf, cfw, wcf, wfc, fcw, fwc

Extension Filters

Include only specific extensions:

psk "TODO" --ext py --ext js

Exclude extensions:

psk "TODO" --exclude-ext exe --exclude-ext dll

Path Filters

Include Paths

psk "TODO" \
    --include src \
    --include tests

Only search inside those paths.

Exclude Paths

psk "TODO" \
    --exclude build \
    --exclude .git

Skip those paths.

Regex Path Filters

Include

psk "TODO" \
    --re-include "src/.*"

Exclude

psk "TODO" \
    --re-exclude "node_modules|dist"

Size Filters

Limit search by size.

Maximum:

psk "TODO" --max-size 100

Only search files/directories up to: 100 MB

Minimum:

psk "TODO" --min-size 10

Only search files/directories larger than: 10 MB

Archive Search

Enable archive support:

psk "TODO" --archive

Supported formats: zip, rar, 7z, gz, bz2, xz, tar, tar.gz, tar.bz2, tar.xz

Nested Archives

Pseek supports recursive archive traversal.

Example:

backup.zip
 └── source.7z
      └── notes.txt

Pseek can search:

backup.zip::source.7z::notes.txt

Archive Depth

Limit recursion depth:

psk "TODO" --archive --depth 2

Meaning:

archive level 1
archive level 2

will be searched.

Deeper levels will be skipped.

Archive Filters

Extension Filters

psk "TODO" --archive --arc-ext py

Only search .py files inside archives.

psk "TODO" --archive --arc-exc-ext jpg

Exclude .jpg files inside archives.

Path Filters

Include:

psk "TODO" --archive --arc-include src

Exclude:

psk "TODO" --archive --arc-exclude cache

Size Filters

Maximum:

psk "TODO" --archive --arc-max 10

Minimum:

psk "TODO" --archive --arc-min 1

Values are in MB.

Note: Archive directory sizes are usually reported as zero by archive formats, therefore archive size filtering is mainly useful for files.

RAR Backend

RAR archives require an external backend that must be set up.

Supported backends include:

• UnRAR
• 7-Zip
• BSDTar
• Unar

Example:

psk "unrar" --rar-backend /usr/bin/unrar

Windows:

psk "unrar" --rar-backend "C:\Program Files\WinRAR\UnRAR.exe"

Enter the file type in the query (e.g. unrar, bsdtar, unar, 7z).

Output Options

Show Full Paths

psk "TODO" --full-path

Paths Only

Only display matching file paths:

psk "TODO" --content --paths-only

Useful for very large result sets.

Timeout

Stop the search automatically after a specified number of seconds.

Example:

psk "TODO" --timeout 30

If the search exceeds the limit, it will be terminated.

Requirements

• Python 3.8+
• unrar, bsdtar, unar or 7zip for the rarfile library to support searching inside .rar files (optional)