A reference for terms used in peekdocs documentation, the CLI, the GUI, and the source code. Covers technical concepts (FTS5, regex, exit codes), tools peekdocs integrates with (Tesseract, jq, cron), industry context (MSP, SIEM, CI pipelines), and Python networking libraries — listed because they are notably absent from peekdocs's source code.
| Term | What it means |
|---|---|
| aiohttp | A Python library for making asynchronous HTTP requests. If found in source code, it could indicate network activity. peekdocs does not use it |
| Air-gapped | A computer with no network connection — no Wi-Fi, no Ethernet, no internet. Used for the most sensitive work. peekdocs works well on air-gapped machines since it has no network requirements |
| API | Application Programming Interface — a way for programs to use peekdocs from Python code, not just the GUI or terminal. Example: from peekdocs import search, run_suite, run_regex_collection |
| apt | Advanced Package Tool — the package manager for Debian, Ubuntu, Linux Mint, Pop!_OS, and other Debian-derivative Linux distributions. peekdocs's Linux install uses sudo apt install python3-venv python3-pip python3-tk for the Python toolchain plus tkinter, and sudo apt install tesseract-ocr / unrar for optional OCR and archive support. Other Linux distros use different package managers: Fedora/RHEL has dnf, Arch has pacman, openSUSE has zypper. peekdocs docs focus on apt because Debian-derivatives are the most common desktop Linux |
| Binaries | Compiled, ready-to-run executables that don't require Python to be installed. peekdocs ships six standalone binaries built with PyInstaller — the GUI and CLI for each of Windows, macOS, and Linux (e.g., peekdocs-gui-windows.exe, peekdocs-cli-macos.zip, peekdocs-gui-linux). Each one bundles its own Python interpreter plus every library peekdocs needs into a single file, so a fresh download is "everything you need, in one file." Distributed via the Releases page; the README's Option A has direct download links per platform. The pipx / pip install paths are the alternative when Python is already installed — they share one Python environment instead of bundling a separate interpreter into each binary |
| BOM | Byte Order Mark — an invisible character at the very start of a text file that indicates the file's encoding. Common in files created by Windows Notepad. peekdocs strips it automatically so it doesn't interfere with searches |
| Boolean expression | A search using AND, OR, and NOT to combine terms. Example: (budget OR revenue) AND NOT draft |
| chmod | "Change mode" — a Unix command, available on macOS and Linux, that sets file permissions including the execute bit. peekdocs's Linux install uses chmod +x peekdocs-gui-linux (or peekdocs-cli-linux) to mark the downloaded binary as executable so the shell will run it. Without the execute bit, you get "permission denied" instead of a running program. Windows uses different permission semantics (the file extension .exe does the equivalent job) and doesn't have chmod |
| chown | "Change owner" — a Unix command, available on macOS and Linux, that sets which user and group own a file or directory. peekdocs's Linux troubleshooting uses sudo chown -R $USER /path/to/folder to take ownership of a folder so the current user can read it — useful when a permission error blocks a search. The -R flag applies the change recursively to every file and subfolder |
| CI pipeline | Continuous Integration pipeline — an automated workflow that runs tests, scans, or checks every time code changes (e.g., on every git commit or pull request). Common platforms include GitHub Actions, GitLab CI, Jenkins, and CircleCI. peekdocs fits into CI pipelines via its CLI: JSON output (--stdout), exit codes (0 = matches found, 1 = none), and --regex-collection for batch pattern scans — for example, a nightly job that checks every repo for deprecated APIs, TODO/FIXME comments, or credentials accidentally committed to source control |
| CLI | Command-Line Interface — the terminal version of peekdocs. You type commands like peekdocs budget -r instead of clicking buttons |
| Command Prompt | The Windows terminal application where you type commands. On macOS it's called Terminal |
| cron | A built-in Unix/Linux/macOS scheduler that runs commands automatically on a schedule — every hour, every Monday at 8am, the first of every month, etc. On Windows the equivalent is Task Scheduler (or its CLI form schtasks). peekdocs's --suite, --regex-collection, --timestamp, --stdout, --on-match, and --diff flags are designed to compose into cron / Task Scheduler jobs for unattended scheduled scans. The Tools → Schedule Search dialog generates the correct command for your OS automatically |
| Deterministic | A computer-science property: given the same inputs (files + query + options), the system produces byte-identical outputs every time. peekdocs's search algorithms — literal substring, regex, fuzzy matching with Levenshtein distance, Boolean expression evaluation — are classical pattern-matching with well-defined behavior. No model inference, no sampling, no stochastic ranking. Result ordering is fixed (alphabetical by file path, then ascending line number). The same search against the same files always returns the same matches, the same counts, and the same report contents. Load-bearing for reproducible-output workflows, scheduled scans whose output gets compared against last week's, peekdocs --diff workflows, and CI pipelines that depend on stable exit codes |
| Diff | A side-by-side comparison of two files, datasets, or scan results — the term is borrowed from the Unix diff command (1974). peekdocs's --diff peekdocs_snapshot_old.json peekdocs_snapshot_new.json compares two JSON snapshots and reports what's new, removed, changed, or modified — answering the scheduled-scan "what's new since last week?" question. Snapshot files use the convention peekdocs_snapshot_<label>.json and diff output peekdocs_diff_<label>.json to sort alongside other peekdocs files. Exit codes follow diff convention: 0 = no actionable change, 1 = new findings detected, 2 = error. Also available in the GUI under Tools → Diff Snapshots |
| Exit codes | The number a command-line program returns when it finishes, used by other programs to decide what happened. Convention: 0 = success, non-zero = some kind of error. peekdocs uses 0 (matches found), 1 (no matches), 2 (error). Scripts use these to branch: peekdocs --check && echo OK || echo BROKEN. The --diff command follows diff-style codes: 0 = no actionable change, 1 = new findings detected, 2 = error |
| File-integrity monitoring (FIM) | A class of tools that hash every file in a folder tree, save the manifest, then re-hash later and report new / removed / modified files. Distinct from what peekdocs's --hash does: peekdocs hashes only files that matched your search (match-scoped — for provenance of specific findings); FIM tools hash every file regardless (folder-scoped — for security monitoring). The two are complementary rather than competing. Three tiers of options. Shell one-liner (free, universal, no install; slows past a few thousand files): find . -type f -exec shasum -a 256 {} \\; | sort > baseline.txt, re-run later, diff the two manifests. Purpose-built: hashdeep / md5deep family (batch-hash + verify — apt install hashdeep / brew install md5deep); restic and borgbackup (backup tools that store per-file hashes and can answer "what changed between snapshot A and B?" in one command). Enterprise FIM: AIDE (open source, config-file driven, standard on Debian/RHEL); Wazuh (successor to OSSEC, SIEM-integrated, real-time watching); Tripwire (the 1992 classic, community edition open source). Realistic audit workflow using both peekdocs and a FIM: for an engagement where a client hands you a folder of exhibits — hashdeep at engagement start (baseline the whole set), hashdeep -a -k baseline at handoff (verify nothing shifted while you worked), plus peekdocs --hash on your findings for provenance of specific citations. Belt and suspenders. See also SHA-256 reproducibility for peekdocs's match-scoped mechanism |
| ftplib | A Python library (built into Python) for FTP file transfers. If found in source code, it could indicate file uploads/downloads. peekdocs does not use it |
| FTS5 | Full-Text Search 5 — a fast search extension built into SQLite that peekdocs uses for its search index. FTS5 builds an inverted index (like a book's index — words mapped to locations) so searches run in milliseconds instead of re-reading every file. The "5" is the fifth generation, introduced in 2015, replacing FTS3/FTS4 with better performance and ranking support. It's the same technology behind search in many desktop and mobile apps. |
| Fuzzy matching | Finding approximate matches — catches typos like "budgt" when searching for "budget" |
| Gatekeeper | macOS's gatekeeper for executable code — runs signature and notarization checks on every launch of an unsigned binary (or every launch of a binary that still has the com.apple.quarantine extended attribute set). peekdocs is unsigned (no Apple Developer ID), so the standalone CLI / GUI pays Gatekeeper's per-launch overhead on macOS. See PyInstaller / Gatekeeper startup tax below for the full per-platform breakdown |
| grep | A classic Unix command-line tool for searching text in files. Designed for plain text — extremely fast and the first tool most developers reach for when searching source code. Created by Ken Thompson at Bell Labs in 1973, one of the oldest Unix utilities still in daily use. The name stands for "globally search for a regular expression and print matching lines" (g/re/p), derived from a command in the ed text editor. Over 50 years later, grep is still going strong. CLI-only by design. |
| GUI | Graphical User Interface — the point-and-click window version of peekdocs (launched with peekdocs-gui) |
| .gz file | A file compressed with gzip. Often used for log files (e.g., access.log.gz) or combined with tar (.tar.gz). peekdocs searches both tar.gz archives and standalone .gz compressed files |
| Hash (SHA-256) | A short, fixed-length fingerprint (64 hexadecimal characters) computed from a file's raw bytes. Any change to the file — even a single byte — produces a completely different hash, so two files with the same SHA-256 are mathematically certain to be byte-identical. peekdocs uses SHA-256 for file-identity and integrity verification: add --hash to any --stdout or -o json run and each matched file's sha256 is included in the JSON, letting a reviewer verify later that "this is the exact file I found" even after the original has been modified, moved, or deleted. Same algorithm used by Git, Bitcoin, and most modern security tools |
| Headless | A computer with no display, keyboard, or mouse — typically a server, virtual machine, or container running unattended. peekdocs's CLI runs headlessly without the GUI dependency installed; peekdocs --check reports the GUI as missing and still exits 0 because the CLI is fully usable. See Headless servers and containers in the User Guide |
| Heatmap | A chart that plots the distribution of matches inside a single file, by line number. peekdocs's Matched Files popup adds a Heatmap button per row: select a file and click Heatmap to open a matplotlib popup with line number on the x-axis and match-count-per-bin on the y-axis. Tall bars at the left mean matches cluster near the start of the document; tall bars at the right mean they cluster near the end; a flat profile means the term recurs throughout. Faint blue tick marks are drawn at every individual match line so single hits stay visible even when no histogram bin is tall. Useful for triaging which of many matching files to open first — a long report with all matches concentrated in one section is a different read than one with matches scattered everywhere. Requires per-match line numbers in the result set (captured by default; older saved runs may show "No line-number data"). Distinct from the match position shown in the Matched Files popup row itself, which lists the first ten line numbers as plain text |
| Homebrew | A popular package manager for macOS. Used to install Python, pipx, and other tools. Website: brew.sh |
| httplib2 | A Python HTTP client library. If found in source code, it could indicate network activity. peekdocs does not use it |
| httpx | A modern Python HTTP client library, increasingly popular as a replacement for requests. If found in source code, it could indicate network activity. peekdocs does not use it |
| Index | A pre-built database of your files' contents that makes repeated searches much faster. Like a book's index — instead of reading every page, you look up the word and go straight to the right page |
| Inverse search | Find files that are missing required content — the opposite of normal search. Useful for completeness checks ("which contracts don't have a signature line?", "which scripts don't import the logging module?"). Run with --inverse (CLI) or check Inverse in Advanced Search Options (GUI) |
| jq | A command-line JSON processor — like grep/awk/sed but for JSON. Lets you filter, transform, and extract fields from JSON streams. Useful for parsing peekdocs's --stdout output, the .json report, and ~/.peekdocs_runs.log without writing a script. Install via Homebrew (brew install jq), apt/dnf, or the standalone binary at jqlang.github.io/jq. Example: peekdocs --stdout TODO | jq '.matches_per_file[] | select(.matches > 10)' |
| JSON Lines (JSONL / NDJSON) | A streaming text format where each line is one self-contained JSON object — no top-level array, no commas between records. Universal in log shipping (Filebeat, Splunk, Elastic Beats) because a malformed line never breaks later ones and tail -f | jq works without aggregation. peekdocs's per-run log (~/.peekdocs_runs.log) is JSON Lines. So is the output of peekdocs --runs --json. Specification: jsonlines.org |
| Little Snitch | A macOS application that monitors and controls outbound network connections. Alerts you when any program tries to connect to the internet. Useful for verifying that software like peekdocs makes no network calls. Website: obdev.at/products/littlesnitch |
| LSTM | Long Short-Term Memory — a type of neural network designed to recognize patterns in sequences of data. Tesseract 4+ uses an LSTM network to recognize text in images, which significantly improved accuracy over the older template-matching approach |
| MCP (Model Context Protocol) | An open, vendor-neutral standard that lets an AI assistant call external tools during a conversation — the assistant asks a "tool," the tool runs locally and returns structured results the assistant reasons over. peekdocs ships an optional MCP server (peekdocs-mcp, installed via pip install peekdocs[mcp]) so an MCP-capable assistant (Claude Desktop, Claude Code, and other hosts) can search your local documents: you ask a question about your files, the assistant runs a peekdocs search and answers. It runs over stdio (the transport every MCP client speaks) and is a thin adapter over the same peekdocs.api engine the CLI and GUI use, so results are identical. Two properties keep it safe: it is read-only — it exposes only search/context/inventory/list tools, and nothing that writes, moves, renames, deletes, or generates reports — and it is fenced by a required --root DIR flag, so the assistant can only search inside the folders you name, never your whole drive. Searches also never write peekdocs's on-disk index by default. See User Guide → MCP server |
| MIT License | A permissive open-source license that lets anyone use, copy, modify, and share the software for free, with no restrictions. Originated in the 1980s from MIT's X Window System project — they wanted the broadest possible adoption with zero legal friction. Now the most popular open-source license on GitHub, used by React, Node.js, Ruby on Rails, and thousands of other projects. |
| MSP technician | Managed Service Provider technician — an IT professional employed by an outside firm that manages computers, networks, and software for client businesses on contract. One MSP typically serves dozens of small clients (dental offices, law firms, accounting practices, retail chains) who do not have their own in-house IT staff. MSP technicians visit or remote-into client sites to install software, troubleshoot issues, and run maintenance — so they need tools that travel well between unfamiliar machines without complex setup. |
| mv | "Move" — a Unix command, available on macOS and Linux, that renames or relocates files and directories. peekdocs's standalone-CLI install uses sudo mv ~/Downloads/peekdocs /usr/local/bin/peekdocs (macOS) or sudo mv peekdocs-cli-linux /usr/local/bin/peekdocs (Linux) to put the binary on PATH so peekdocs works from any terminal session. The Windows PowerShell equivalent is Move-Item |
| NameNotFoundError | Python exception raised by peekdocs.api.run_suite() and peekdocs.api.run_regex_collection() when the requested suite or collection name doesn't exist. Defined in peekdocs.errors; inherits from both PeekdocsError (the peekdocs root) and the stdlib KeyError for back-compat with existing consumer code that catches KeyError. The exception message lists the available names so the caller can print a helpful correction |
| Network calls | Any outbound communication a program makes over a network — HTTP requests, DNS lookups, telemetry pings, license checks, update checks, crash reports, and so on. peekdocs makes none. Search runs entirely in-process against files on your local disk; no peekdocs dependency phones home. Verify on macOS with Little Snitch, on Windows with the Resource Monitor's Network tab, or on Linux with lsof -i while peekdocs is running. The pipx / pip install commands themselves do fetch from PyPI / GitHub at install time, but the running program never opens a socket. |
| OCR | Optical Character Recognition — technology that reads text from images and scanned PDFs. Requires Tesseract (optional). When do you need OCR? Modern scanners with built-in OCR (like the Fujitsu ScanSnap) produce PDFs with an embedded text layer — peekdocs reads these directly, no OCR needed. But older scanners, phone cameras, and screenshot tools produce image-only files (.jpg, .png, .tiff, or PDFs that are just pictures of pages). These have no text layer — they're just pixels. OCR converts those pixels back into searchable text. Enable it with the OCR checkbox (GUI) or -O flag (CLI). Note: peekdocs does not use ocrmypdf — it extracts text in memory using PyMuPDF and Tesseract without modifying your PDF files. ocrmypdf is a separate tool that permanently adds a text layer to PDFs. |
| ocrmypdf | A free, open-source command-line tool that adds a text layer to image-only PDFs, making them searchable. Uses Tesseract under the hood and runs entirely on your computer — your documents never leave your machine. Use it when you have a backlog of scanned PDFs without a text layer and want to convert them once instead of OCR'ing on every search. Install: brew install ocrmypdf (macOS) · pipx install ocrmypdf (Windows) · sudo apt install ocrmypdf (Linux). Basic usage: ocrmypdf input.pdf output.pdf, or use the same path twice to convert in place. peekdocs itself never modifies your PDFs; ocrmypdf is a separate tool you opt into for permanent conversion. Website: ocrmypdf.readthedocs.io |
| paramiko | A Python library for SSH and SFTP connections. If found in source code, it could indicate remote server access. peekdocs does not use it |
| Password-protected archive | A .zip, .7z, or .rar file that requires a password to open. peekdocs cannot read encrypted archives — it detects them and reports a clear message instead of a confusing error |
| PATH | A system setting that tells your computer where to find programs. If a command says "not recognized," the program probably isn't in your PATH |
| PeekdocsError | Root of the peekdocs exception hierarchy in peekdocs.errors. Catch this to handle any exception raised by peekdocs's library surface without also catching unrelated built-in exceptions. Subclasses: QueryError (bad search input), RangeError (malformed -R spec), NameNotFoundError (missing suite / regex collection). Each subclass also inherits from the closest stdlib exception (ValueError or KeyError) so existing consumer code that already catches those types keeps working — the hierarchy is a non-breaking upgrade |
| pip | Python's built-in package installer. Comes with Python automatically. Used to install Python programs and libraries |
| Piping | Connecting one command's output to another command's input with the | character on macOS, Linux, and Windows terminals. Example: peekdocs --stdout TODO | jq '.matches_found' runs the search, then pipes the JSON output into jq to extract just the match count. peekdocs's --stdout and --runs --json flags exist specifically to compose into pipes |
| pipx | A tool that installs Python programs (like peekdocs) in isolated environments so they don't interfere with anything else on your computer. pipx vs pip: pip install git+https://github.com/exbuf/peekdocs.git installs into your current Python environment — simple and fast, but peekdocs's 50 dependencies mix with your other Python packages and could cause version conflicts. pipx install git+https://github.com/exbuf/peekdocs.git creates a private environment just for peekdocs — completely isolated, no conflicts, and the peekdocs command works from any terminal without activating a virtual environment. The tradeoff: pipx must be installed first (pip install pipx on Windows, brew install pipx on macOS, sudo apt install pipx on Linux). For developers who manage multiple Python projects, pipx is strongly recommended. For a quick try, the same URL with plain pip install works fine. |
| Provenance audit | A peekdocs workflow that pairs --hash (SHA-256 fingerprint of every matched file, baked into JSON output) with --diff (snapshot comparison of two JSON outputs). Capture a baseline early in an engagement (peekdocs --hash --stdout ... > baseline.json), work with the corpus, then re-capture at handoff — peekdocs --diff baseline.json current.json buckets the delta into new / removed / changed / modified. The modified bucket is the subtle one: same file, same match count, different SHA-256 — content shifted under the search's radar. Match-scoped rather than folder-scoped (see File-integrity monitoring for the folder-scoped complement — the two are commonly paired belt-and-suspenders style). One of three named compositions in the README's How these compose section, alongside Live pattern sweep (--watch + --regex-collection) and Scheduled pattern scan (cron + --regex-collection + --timestamp). Full baseline-to-verify walkthrough in USER_GUIDE.md's A worked example: audit engagement provenance section. Use cases: audit engagements where citations may be challenged later; due-diligence document sweeps where hashes pin findings to specific byte-content; any workflow where "is this the exact file I searched last week?" is a load-bearing question |
| Proximity search | Find search terms that appear close to each other in the same document. Word proximity (-p N): terms within N words on the same line — e.g., peekdocs -p 5 budget revenue matches lines where "budget" and "revenue" sit within 5 words of each other. Line proximity (-P N): terms within N lines of each other (the terms can be on different lines but still in the same neighborhood). Useful when both terms appear in many files but you only want documents where they appear together |
| pycurl | A Python wrapper for the curl library, used for making HTTP requests. If found in source code, it could indicate network activity. peekdocs does not use it |
| PyInstaller | A tool that packages Python programs into standalone executables (.exe on Windows, .app on macOS) so users don't need Python installed |
| PyInstaller / Gatekeeper startup tax | Combined per-invocation overhead the standalone download (Option A) pays at launch on top of the actual peekdocs work. Two components: (1) PyInstaller unpack — peekdocs ships as a binary that bundles its own Python interpreter and every library it needs. On Windows and Linux it's a --onefile bundle that self-extracts to a temp directory on every invocation (~2–4s Windows, ~0.5–1.5s Linux); on macOS since v1.0.21 it's a --onedir folder that skips this cost entirely. (2) macOS Gatekeeper / XProtect / AMFI checks — signature and notarization round-trips that fire on every execution of an unsigned binary (~1–2s, partially cached for ~1 hour after first run). Together these add roughly 1–7 seconds to invocation time on the Option A download, depending on platform. The pipx install path (Option B; pipx install peekdocs) skips both — peekdocs runs as a normal Python script in a venv, with no PyInstaller bundle and no Gatekeeper involvement. For the full breakdown see docs/INSTALLATION.md → CLI standalone startup time |
| PyPI | Python Package Index (pronounced "pie-pee-eye") — the official repository where Python packages are published. Like an app store for Python programs |
| Python | The programming language peekdocs is written in. Python orchestrates the search, but the performance-critical work — PDF decoding, regex matching, fuzzy search, ZIP decompression — is handled by C/C++ libraries under the hood. Users need Python 3.10 or newer installed (unless using the standalone download). Created by Guido van Rossum in 1991, named after Monty Python's Flying Circus (not the snake). Now one of the most popular programming languages in the world, widely used in web development, data science, AI, and automation. |
| QueryError | Python exception raised by peekdocs.api.search() for invalid search-mode combinations (fuzzy + regex, wildcard + fuzzy, expression + match_all), empty term lists, malformed individual regex patterns, and boolean-expression syntax errors. Also raised by run_suite / run_regex_collection when the suite / collection exists but has no runnable content. Defined in peekdocs.errors; inherits from PeekdocsError and stdlib ValueError for back-compat |
| RangeError | Python exception raised by peekdocs.range_query for a malformed -R range specifier (missing : or .., unparseable date/time/filesize, min > max). Distinct from QueryError so callers can point the user at the specific -R flag they got wrong. Defined in peekdocs.errors; inherits from PeekdocsError and stdlib ValueError for back-compat |
| Range queries | Filter matched lines (or files) by numeric or date values. Examples: --range amount:1000..5000 for dollar amounts between $1,000 and $5,000, --range date:2024-01-01..2024-12-31 for dates in 2024, --range size:>1MB for files larger than 1 MB. Supported range types: amounts, dates, percentages, ages, file sizes |
| Regex | Regular Expression — a pattern language for matching text. Example: \d{3}-\d{2}-\d{4} matches a 9-digit ID with dashes, like 123-45-6789 |
| Regex collection | A named, persisted group of regex patterns saved in ~/.peekdocs_regex_collections.json and run together as a single search. The GUI Regex Search popup edits up to 10 patterns at a time; the collection on disk is unbounded (the seeded Examples collection ships with 17). Created in the GUI (Tools → Regex Search → Save Collection As — CREATE / OVERWRITE / ADD), restored with Restore From Collection (loads the first 10 into the popup workbench), edited row-by-row with the red − button, run from the CLI with peekdocs --regex-collection NAME (all patterns, no cap), or from Python with run_regex_collection(). Multiple collections can be run together in the GUI via the Run Multiple Collections… picker — patterns are read straight off disk, so the popup's 10-row cap doesn't apply |
| requests | The most popular Python library for making HTTP requests. If found imported in source code, it almost certainly means the software makes network calls. peekdocs does not use it |
| rm | "Remove" — a Unix command, available on macOS and Linux, that deletes files. With -r (recursive) and -f (force) it deletes directories and ignores prompts. peekdocs's uninstall guide uses sudo rm /usr/local/bin/peekdocs to remove the standalone CLI when switching to a pipx install, and the README's Uninstalling factory-reset section uses rm -rf ~/peekdocs_reports and rm -f ~/.peekdocsrc to wipe persisted user data. The Windows PowerShell equivalent is Remove-Item |
| Sandbox | An isolated environment for running software safely — if the software does something malicious, it can't affect your real system. Examples: Windows Sandbox (built into Windows Pro), VirtualBox VMs, Docker containers. Useful for testing unfamiliar software before trusting it on your main machine |
| Search suite | A named group of saved searches that run together with one click. Create them in the GUI (Tools → Search Suites) or run from the CLI with --suite. Multiple suites can be run together in the GUI via the Run Multiple Search Suites… picker at the bottom of the Search Suites popup — pick two or more, click Run Selected, and the combined run produces one merged report with a dedicated completion popup (Open TXT / Open DOCX / Open Folder) so report attribution stays unambiguous |
| SHA-256 reproducibility | A content-fingerprint mechanism that lets you prove two files are byte-identical (or prove they differ). SHA-256 produces a 256-bit hash rendered as a 64-character hex string; even a single byte changing in the file yields a completely different hash. peekdocs's --hash flag adds the SHA-256 of each matched file to the JSON output. Scan the same folder a week later with --hash and peekdocs --diff old.json new.json reports which files that matched both scans had their content change (diff.py: same path + same match count + different sha256 → modified), versus files re-touched without content change (same hash, different mtime). Scope is deliberate: peekdocs hashes files in the current match set, not the whole folder — a file that dropped out of the match set (e.g., you edited it and it no longer contains the term) shows up as removed, not modified, so peekdocs can't distinguish "content changed enough to no longer match" from "file deleted." For whole-folder integrity monitoring across every file regardless of match status, reach for a dedicated file-integrity tool — see File-integrity monitoring (FIM) above. Where SHA-256 in peekdocs does pull its weight: audit workflows where "we found this text in this exact version of this file" has to be defensible, and scheduled-scan pipelines that compare snapshots to distinguish real content churn from filesystem noise. Companion mechanism to the release-artifact SHA-256 published as peekdocs_SHA256SUMS.txt on the Releases page, which serves the same reproducibility role for downloaded binaries |
| Shim | A small wrapper executable that forwards calls to a real program. When you install peekdocs with pipx (pipx install ...), pipx creates shims at ~/.local/bin/peekdocs and ~/.local/bin/peekdocs-gui that locate the isolated venv pipx made and invoke python -m peekdocs.cli:main (or peekdocs.gui:main) without you having to activate the venv. When you type peekdocs in any terminal, you're running the shim, not a binary — the shim is just a few hundred bytes that calls Python with the right arguments. This is why the pipx path has near-zero startup overhead (~0.2–0.5s) compared to the PyInstaller standalone (5–7s on macOS): there's no bundled Python to unpack, just a thin wrapper that invokes your system's Python in pipx's pre-built venv. The standalone binary has no shim layer; you run the bundled executable directly |
| SIEM | Security Information and Event Management — a class of tools (Splunk, Elastic Security, Datadog, Microsoft Sentinel, IBM QRadar) that aggregate logs and security events from across an organization for searching, alerting, and forensics. peekdocs integrates with SIEMs without any plugins by emitting JSON Lines to its run log and JSON to --stdout — both of which any SIEM can ingest via Filebeat, Fluent Bit, or an equivalent log shipper |
| SLA | Service Level Agreement — a contract between a software vendor and a customer that commits the vendor to specific response times, uptime percentages, or bug-fix turnaround (e.g., "critical bugs acknowledged within 4 hours, 99.9% uptime guarantee"). Commercial enterprise software typically comes with one. Open-source projects like peekdocs do not — the maintainer fixes bugs on a best-effort basis as time allows, with no contractual commitment to response time. This is standard for solo-maintained MIT-licensed software and is one of the trade-offs of free, transparent, no-strings tools versus paid vendor relationships |
| smtplib | A Python library (built into Python) for sending email. If found in source code, it could indicate the software sends data via email. peekdocs does not use it |
| socket | A low-level Python networking library (built into Python) for making direct network connections. The foundation most other networking libraries are built on. If imported in source code, it indicates network capability. peekdocs does not import it — the word "socket" appears only in a comment about skipping Unix sockets during file scanning |
| SQLite | A lightweight database engine built into Python. peekdocs uses it for the search index — no separate database software needed. Created by D. Richard Hipp in 2000, SQLite is the most widely deployed database in the world — it's embedded in every smartphone, every web browser, and most operating systems. It's in the public domain (no license, no restrictions). |
| SSD | Solid State Drive — a fast storage drive with no moving parts. Searches are faster on SSDs than on older spinning hard drives |
| SSL .key file | A certificate key file used for website encryption (HTTPS). These share the .key extension with Apple Keynote presentations but are not zip archives. peekdocs detects the difference and skips certificate files |
| stdin / stdout / stderr | The three "standard streams" every command-line program has. stdin is its input, stdout is its normal output, stderr is its errors and warnings — kept on separate channels so you can pipe one without the other. peekdocs --stdout writes a JSON document to stdout (the normal output channel), keeping it clean for piping into other tools; warnings go to stderr where they don't pollute the JSON. Quiet mode (-qq) suppresses most stderr noise |
| Stemming, stop-words, word segmentation | Three concepts from linguistic search engines that peekdocs deliberately does not perform. Stemming reduces words to a root form (so "running" matches "run"). Stop-word removal ignores common words like "the", "and", "of" during indexing. Word segmentation breaks languages without spaces (like Chinese or Japanese) into individual words. peekdocs does exact character-sequence matching across all languages instead — simpler, more predictable, and works equally well for English prose, Chinese text, code identifiers, account numbers, and product SKUs |
| sudo | "Substitute user, do" — a Unix command, available on macOS and Linux, that runs a single command with elevated (typically root) privileges. Required for any command that writes to system directories like /usr/local/bin/ or installs packages system-wide. peekdocs's install uses sudo in several places: sudo mv (to put the binary on PATH), sudo apt install ... (Linux package install), sudo xattr -dr com.apple.quarantine (macOS quarantine-flag removal after sudo mv), and sudo rm (uninstall). Windows uses "Run as administrator" or an elevated PowerShell instead |
| Symlink | Symbolic link — a shortcut that points to another file or folder. peekdocs skips symlinks during search to prevent infinite loops when a symlink points back to a parent folder |
| Telemetry | Data that software silently sends back to its developer — usage statistics, error reports, search terms, or system information. Often collected without the user's knowledge or explicit consent. peekdocs has no telemetry of any kind |
| Tesseract | Free OCR software that reads text from images. Optional — only needed if you want to search scanned documents or photos of text. Originally developed at Hewlett-Packard Labs in Bristol, England in the mid-1980s by HP engineer Ray Smith. It was one of the top three OCR engines in a 1995 UNLV accuracy test but remained proprietary for two decades. Google acquired and open-sourced it in 2006 to support the Google Books scanning project. Now the most widely used open-source OCR engine in the world, supporting 100+ languages. Version 4+ (2018) added a built-in LSTM neural network that significantly improved accuracy over the original template-matching approach. (The name comes from mathematics — a tesseract is a 4-dimensional cube.) |
| Unicode | The standard that lets computers handle text in every language — English, Chinese, Arabic, emoji, and everything else. peekdocs uses Unicode throughout |
| urllib | A Python library (built into Python) for making HTTP requests and opening URLs. If found imported in source code, it indicates network capability. peekdocs does not use it |
| venv | Virtual environment — an isolated copy of Python where peekdocs and its libraries are installed without affecting the rest of your system. You'll see (venv) in your terminal prompt when one is active. Think of it as a quarantine room for Python packages. |
| VirusTotal | A free online service that scans files with 70+ antivirus engines simultaneously. Upload a suspicious file to virustotal.com and get a report from every major antivirus vendor in minutes. Note: PyInstaller executables often trigger 1-2 false positives because the bundling technique resembles malware packers — this is normal for legitimate open-source tools |
| Warm index | The state of the search index after it's been recently read into the OS file cache and any per-session startup costs (Python interpreter load, dependency imports, the refresh_index os.stat() pass on the folder) have already been paid once. peekdocs's first search in a new terminal session can take a few seconds even when .peekdocs.db already exists — that's the cold state. Subsequent searches in the same session re-use the cached state and typically run in well under a second. The cost difference is mostly OS-level disk I/O on the index file plus Python startup overhead, not peekdocs itself doing extra work. To pre-warm before an interactive session, schedule peekdocs --index-refresh from a launchd / systemd / Task Scheduler job at login. See First-run timing in the README and "Why is my first search slow but later searches are fast?" in docs/TROUBLESHOOTING.md for the full breakdown |
| Webhook | A user-defined HTTP callback — when something happens, your service sends a POST request to a URL someone gave you, usually with a JSON body describing what occurred. Common in Slack ("notify this channel when..."), GitHub ("ping me on every push"), and alerting systems (PagerDuty, Opsgenie). peekdocs's --on-match hook can invoke curl against a webhook URL to fire notifications into chat, paging, or ticketing systems |
| Wheel (Python wheel) | Pre-built, ready-to-install Python package format (.whl file). Most Python libraries ship as wheels so pip install doesn't need a C compiler — it just downloads the matching wheel for your OS and Python version. A few peekdocs optional dependencies (notably libpff-python for .pst archives) have no Windows wheel, which means Windows users either need a working compiler toolchain or have to use the documented .mbox workaround. See Prerequisites for details |
| Whole-word matching | Match a search term only when it stands alone, not when it's part of a longer word. With whole-word on, searching for "bob" finds "bob" but not "bobcat" or "ribbon"; searching for "log" finds "log" but not "logger" or "blog". Run with -W (CLI) or check Whole Word in Advanced Search Options (GUI) |
| Wildcard | A search pattern where * matches any characters and ? matches one character. Example: budg* matches "budget," "budgeting," "budgetary" |
| Wireshark | A free, open-source network protocol analyzer that captures and displays all network traffic on your machine in real time. The definitive tool for verifying whether software makes outbound connections. Website: wireshark.org |
| XML namespace | A string identifier (usually a URL like http://schemas.microsoft.com/...) used inside XML documents to avoid naming conflicts between different standards. Despite looking like a web address, it's just a unique label — no network connection is made. These appear in peekdocs's grep results because it parses Office and Visio XML formats |
| xmlrpc | A Python library (built into Python) for making remote procedure calls over HTTP. If found in source code, it indicates the software communicates with remote servers. peekdocs does not use it |