26.6 · June 12 Try it free →
Getting started

Quickstart

Last updated June 2026

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, plus a double-clickable app for macOS and an installer for Windows. Command-line users can simply download, unpack, and put the binary on their PATH.

Grab the build for your OS from the download page.

macOS (Apple Silicon)

The macOS archive contains two things:

  • PIICrawler.app — the easiest option. Drag it into Applications and double-click it: it starts PII Crawler and opens the web UI in your browser. No Terminal needed. If PII Crawler is already running, double-clicking the app again just opens the web UI in a new browser tab.
  • piicrawler-cli — the standalone binary for command-line use. Move it onto your PATH:
unzip piicrawler-cli-macos-arm.zip
sudo mv piicrawler-cli /usr/local/bin/piicrawler

Both the app and the binary are signed and notarized. 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)

Windows ships in two flavors. Pick whichever fits how you want to use PII Crawler:

  • Installer (piicrawler-windows.msi) — the easiest option. Run the MSI, and it installs PII Crawler with a Start Menu shortcut that opens the web UI in your browser. Both the installer and the binaries it installs are signed.
  • Portable (piicrawler-cli-windows-signed.zip) — no installation. Unzip 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). Best for command-line use and servers.

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. See it in action (optional)

Before registering or pointing it at your own files, you can watch PII Crawler work on synthetic data:

piicrawler demo

This generates throwaway sample files seeded with fake-but-realistic PII, scans them with the live progress bar on, and prints a report card. The samples are deleted the moment the command finishes, so nothing on your disk is touched. No registration is needed. See demo for details.

3. 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.

4. 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:

piicrawler ~/Downloads

On a terminal this ends with a color report card: a risk verdict, which PII types turned up, and the files with the most findings. Redirect or pipe stdout and you get the full JSON instead, so it drops straight into scripts:

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

See the CLI Reference for the report card, the JSON schema, and streaming options. New to the tool? Run piicrawler doctor to confirm everything is set up.

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)
Was this page helpful?