Usage

This page is the interface-agnostic reference for creating a scan and reviewing its results. The same scan options are available regardless of how you launch PII Crawler. The three interfaces are views of the same engine and the same on-disk database.

If you haven't installed and registered yet, start with the Quickstart.

Pick an interface

Interface	Launch with	Best for
TUI	piicrawler (no args)	Day-to-day interactive use over SSH or in a local terminal
Web	piicrawler serve	Sharing a scan with a teammate on the same network, browser-based triage
CLI	piicrawler scan <path>	Automation, CI, scripting, piping output into another tool

The TUI and the web UI write to the same local database, so a scan started in one shows up in the other.

Create a scan

TUI

From the scan list, press n to open the new-scan form.

Web UI

Run piicrawler serve, open http://localhost:3001, and click Create New Scan.

Command line

piicrawler scan ~/Documents --workers 8 --out findings.jsonl

The scan keyword is optional: piicrawler ~/Documents works the same. See the CLI Reference for every flag.

Scan options

Every interface exposes the same options. The only required field is the path to scan; everything below is optional.

• Path: file, directory, or archive (.zip, .tar.gz, etc.) to scan. Directory scans walk the tree in parallel.
• Workers: number of files scanned concurrently. Defaults to 4; raise it on machines with more cores or fast storage.
• OCR: extract text from images and scanned PDFs. On by default; turn it off for a faster scan over mostly-text trees (--no-ocr on the CLI).
• File type filter: restrict the scan to specific file types (e.g. only PDFs and emails) when you don't want to scan everything.
• PII types: restrict detection to specific PII data types (e.g. only SSNs and credit cards). In the TUI this is the PII Types panel beside the fields, on every form that starts a scan (local, network share, mailbox): Up/Down moves the cursor, Alt+Space turns a type on or off.
• Terms list: a list of exact-match strings to flag alongside the built-in detectors. Useful for individual identifiers (a specific employee ID, a customer's name) during a DSAR or incident investigation. To search for your terms and nothing else, clear every PII type: the scan then flags only your terms list, which is much faster to review on large trees.
• Custom regex: your own regex patterns for data shapes the built-in detectors don't cover.
• Proximity regex groups: a set of regex patterns that must all match within a configurable distance, for data that is only meaningful when found together (e.g. a name near a date of birth).
• Exclusion patterns: paths to skip (build artifacts, vendored dependencies, virtual environments).

The TUI's forms fit the terminal they are drawn in. On a short window a form shows as many fields as there is room for and scrolls to whichever one you are editing, and the bottom of the form says which part of the list is on screen (fields 1-5 of 9). The selectors that Tab does not reach scroll to themselves when you use them, so you can see what changed: Ctrl+T, Ctrl+X and Ctrl+O on this form, Alt+C on the network share and mailbox forms. The keys you can press are always on the footer at the bottom of the screen. A large enough window shows the whole form at once.

Copy a scan's settings

Press C on a scan in the TUI's scan list (or c on its detail page) to open the New Scan form pre-filled with that scan's settings: the path, exclusions, extensions, size limit, worker count, OCR switch, PII type selection, terms list, and proximity groups. Settings the form has no field for come along too, unchanged: a scan started from the command line with --regex, --terms-file or --detect-forms keeps its own patterns, its own terms and the form pass, so the copy looks for everything the original did. The results stay behind. Starting the form runs a brand-new scan, so this is how you re-run a scan with the same setup without losing the previous results, or tweak one setting and scan again. The name is pre-filled as "name (copy)"; edit any field before starting. Network share and mailbox scans can't be copied yet.

Re-run a scan in place

Press Ctrl+R on a scan's detail page to run it again on the same scan row, replacing its previous results. The scan runs with exactly the settings it was created with, and picks up whatever has changed on disk since. Because the old results are deleted, PII Crawler asks for confirmation first; press y to proceed, any other key to cancel.

Your review work carries over where it still applies:

• Kept: false-positive text rules, ignored folders, and per-file verdicts (matched back to the file by its path). A file that was not there this time keeps its verdict for the next run, so re-running over a share that was not mounted, or a folder something had emptied, costs you no review work.
• Deleted: verdicts on individual matches, since those matches are replaced, plus identity runs and action-list entries built from the old results.

Use Ctrl+R when you want one scan per target with fresh results (say, a weekly re-check of the same share of documents). Use Copy instead when you want to keep the previous results for comparison, or change a setting before scanning again. Re-running network share and mailbox scans isn't supported yet.

Edit a scan's settings

Press E on a scan in the TUI's scan list (or on its detail page) to change its settings in place. The same form as Copy opens, pre-filled with everything the scan runs with: path, name, exclusions, extensions, size limit, worker count, OCR switch, PII type selection, terms list, and proximity groups. Pressing Enter saves your changes back to the same scan instead of creating a new one, and clearing a field removes that setting: empty the extensions filter and the scan stops filtering by extension.

If the scan has already run, its results were produced under the old settings, so after saving PII Crawler offers to re-run it right away; press y to re-run (the same thing Ctrl+R does, including which review work carries over), any other key to keep the old results for now. A scan can't be edited while it is running, and network share and mailbox scans can't be edited yet.

Use Edit to fix or tune a scan you re-check regularly. Use Copy when the old results should survive for comparison.

Review the findings

Findings stream in as files complete. You don't need to wait for the scan to finish.

• TUI: press Enter on a scan to drill into its findings, f to open the Findings view, r to enter Review mode for fast keyboard triage. l opens the Files view, where / filters the list by PII type, match text, extension, file status and whether the file is still on disk, and files that are gone are marked [DEL]. e exports the filtered list as CSV, one row per file with its status, error and verdict.
• Web UI: click View Files on a scan to filter, search, sort, and export to CSV. Filter by PII type with the chips at the top (long lists fold behind a more toggle), or by file extension: the most common extensions appear as one-click pills, and the more button opens a searchable list of every extension in the scan, sorted by file count. Rows with many PII types show the top three and fold the rest into a +N badge; hover it to see the full breakdown. Click the Duration column header to sort by per-file scan time so the slowest files surface at the top (useful when one file is holding up the queue). Click again to reverse the order, a third time to clear it. Files that have been removed from disk since the scan (deleted through PII Crawler or outside it) carry a red Deleted badge; the Deleted toggle in the filter panel can hide them, or show only them to review what has already been cleaned up. Switching the toggle re-checks every file in the scan against disk first, so the list is current even for files removed outside the app since you last looked. That check is a fraction of a second on a scan of a hundred thousand files.
• CLI: JSON streams to stdout (or to --out) as findings are produced. Use --format csv for a flat report.

Browse findings as a directory tree

The Web UI's Tree button (next to View Files on the scan page) opens a directory-style browser that aggregates per-folder PII counts. Each row shows the folder's descendant file count, its non-false-positive match count, and a per-PII-type breakdown that sums everything underneath. This is the fastest way to answer "which part of the share has the bulk of the SSNs?" without paging through individual files.

Click a folder to drill in, click the path segments at the top to jump back to any ancestor, or click a folder's match-count number to open the file list pre-filtered to that path. Files appear as leaves and link straight through to the file detail page. Archive contents (.zip entries) appear as a folder named after the archive so you can navigate into them the same way.

False-positive matches at any scope (match, text, or file) are excluded from the rolled-up counts, so the tree mirrors what the rest of the Web UI shows after you've triaged.

Once you have findings, the next step is separating real positives from noise. See Triaging Findings for the verdict model and the keyboard-driven review workflow.