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

Choosing the folder

The Directory path box takes the folder to scan. Type or paste a path, or click Browse to pick one.

As you type, a line under the box says whether the path is a folder PII Crawler can read. It shows Folder found, Folder not found, This is a file, not a folder, or a permission problem, so a typo is caught before you click Create scan. A ~ at the start stands for your home folder, and a relative path is resolved against the folder the server was started from; in both cases the line also shows the full path the scan will use. Surrounding quotes, as left by Windows' "Copy as path", are stripped for you.

Browse opens a folder picker under the box:

• Quick-access chips at the top jump to your home folder, Desktop, Documents, and Downloads (when they exist), the filesystem root or each drive on Windows, and the usual mount points for removable and network volumes.
• The breadcrumb trail shows where you are. Click any segment to go back up, or use the up arrow at its left.
• The filter box narrows the folder list as you type. Press Enter to open the first match, Backspace in an empty filter to go up a level, and Escape to cancel.
• Hidden folders and files are left out until you tick Show hidden or Show files. The footer shows how many folders and files the current folder holds.
• Clicking a folder opens it and fills the path box, so you can stop at any level. Use this folder keeps the current folder and closes the picker. Cancel puts back whatever the box held when you opened it.

The picker starts in the folder named in the box. If that path does not exist, it starts at the closest folder above it that does, or at your home folder when the box is empty.

Folders you have scanned before appear as Previous locations above the box. Click one to use it again.

While the scan runs

The scan page shows how many files are done out of the total. The browser tab shows the percentage too, so you can switch to other work and glance back at the tab. If the scan finishes while the page is open, a summary tells you how many findings it made and links straight to the files. The Dashboard and All scans lists keep running scans up to date without a refresh.

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. Turning every type off is allowed, but only alongside something else that can match: a terms list, a custom regex pattern, a proximity group or tax-form detection, as in the Terms list entry below. With all of them off, a scan could not report anything at all, so it is refused when you start it rather than reported as a folder with nothing in it.
• 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

In the TUI, press Ctrl+R on a scan's detail page. In the web UI, click Re-scan on the scan's page. Either way the scan runs again on the same scan row, replacing its previous results. It 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: in the TUI press y to proceed or any other key to cancel, in the web UI confirm with Re-scan.

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.

Re-run 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, so the web UI doesn't offer Re-scan for them.

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.