Quickstart

This guide takes you from a fresh machine to your first PII findings. By the end you'll have:

1. The piicrawler binary on your PATH
2. A registered license
3. A completed scan you can browse

1. Install

PII Crawler ships as a single binary per platform. There is no installer — download, unpack, and put it on your PATH.

Grab the build for your OS from the download page.

macOS (Apple Silicon)

unzip piicrawler-cli-macos-arm.zip
sudo mv piicrawler /usr/local/bin/

The macOS archive ships a signed and notarized binary. Apple Silicon (M1 and later) is supported today; an Intel build is not currently published — contact [email protected] if you need one.

Linux (x86_64)

tar -xzf piicrawler-cli-linux.tar.gz
sudo mv piicrawler /usr/local/bin/

Windows (x86_64)

Unzip piicrawler-cli-windows.zip and move piicrawler.exe to a folder on your PATH (for example C:\Users\<you>\bin, or any folder you've added to the Path environment variable under System Properties → Environment Variables).

Verify the install

piicrawler --help

You should see the built-in usage summary. If your shell can't find the binary, the folder you moved it to isn't on your PATH.

2. Register your license

PII Crawler is licensed software and needs to be registered before it will run scans. Registration is a one-time email verification — your scan data never leaves the machine.

The fastest path is the built-in TUI:

piicrawler

With no arguments, piicrawler launches the interactive terminal UI. On first run it opens the Register view:

1. Type the email address you want to license to
2. Press Enter — PII Crawler emails you a verification link
3. Click the link in the email
4. The TUI auto-detects verification and drops you into the scan list

Prefer a browser? Run piicrawler serve and open http://localhost:3001/#/register instead. The two flows produce the same license.

If you try to run a CLI scan before registering, you'll see:

Registration required. Run `piicrawler serve` and register at http://localhost:3001/#/register

That's expected — register first, then come back.

3. Run your first scan

From the TUI scan list, press n to open the new-scan form. The only required field is Path — the directory or file you want to scan.

A good first target is your Downloads folder:

Path: ~/Downloads

Leave the other options at their defaults — every PII type is enabled, OCR is on, and four worker threads is a sensible starting point. Press Enter to start the scan.

Findings stream in as files complete. Press Enter on any scan in the list to drill into its findings, grouped by PII type and file path.

Prefer the command line?

You can skip the TUI entirely and pipe results to a file:

piicrawler ~/Downloads --workers 8 > findings.json

The output is JSON — see the CLI Reference for the schema and streaming options.

Where to next

• Triaging Findings — work through your scan, mark false positives, and export a clean report
• Usage — scan options, terms lists, custom regex, and the web UI
• PII Data Types — what's detected and how
• CLI Reference — every command and flag
• Watch mode — real-time monitoring with webhooks
• Security — what data leaves the machine (almost none)