Buy Download free trial
Getting started

Quickstart

Last updated October 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 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 followed by a spot check of the actual matches, highlighted inside the lines they were found on. The samples are deleted the moment the command finishes, so nothing on your disk is touched. Run piicrawler demo --keep instead to keep the samples in ./piicrawler-demo, so you can open the files and verify the matches yourself. The demo needs no registration. Rescanning that folder with piicrawler piicrawler-demo is an ordinary scan, so do step 3 first. 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:

  Welcome to PII Crawler 👋

  This copy isn't registered yet. Registration is free and takes about
  30 seconds:

      piicrawler register [email protected]

That's expected. Register first, then come back.

How long you have left

Registering starts a free 7-day trial with every feature enabled. Trial scans record a large sample of each PII type rather than every finding; see What a trial scan records. piicrawler register tells you which day it ends as soon as it finishes, and piicrawler doctor repeats it whenever you ask, along with where to buy a license when you are ready:

  ✓  Registration   registered as ja**@example.com, trial ends 2026-09-11 (6 days left)
      To keep scanning after the trial, buy a license:
      https://www.piicrawler.com/#pricing

The count is the number of days until that date, so it reads the same all day and changes at midnight UTC. On the trial's final day it reads last day.

A purchased license is perpetual: one payment, yours forever, with no countdown to show. The same line says so:

  ✓  Registration   registered as ja**@example.com, license does not expire

What a trial scan records

A trial scans everything you point it at and finds every match, but it records only the first 500 findings of each PII type in each scan. That is enough to check every detector against your own data, including how many of its matches are false positives, before you buy.

Every finding past that is counted and nothing more: its value, its context, and the file it was in are not kept. Wherever a scan's findings appear, a trial scan that went past the limit says how many more there were:

  • The web UI's scan page and Files list show a findings were found but not recorded notice, and each type on the scan page shows +N not recorded under its total.
  • The TUI's findings-by-type table shows the count along its bottom edge.
  • piicrawler scan (with or without --save) and piicrawler findings stats print the count per type and how many files it was in:
1,240 more findings were found but not recorded.
  email  1,200 in 312 files
  ssn    40 in 6 files
Trial scans keep the first 500 findings of each type. Buy a license, then rerun the scan to record all of them: https://www.piicrawler.com/?utm_source=piicrawler-app#pricing
  • The HTML risk report has a Not Recorded by the Trial section with the same counts.

Because those files are not recorded, a file whose findings were all past the limit is listed with no findings, and CSV and JSON output from piicrawler scan leaves it out. For a saved scan, its totals, risk score, reports, and exports cover what was recorded.

A purchased license records everything. Scans made during the trial keep what they recorded, so after you buy, re-run them (Re-scan in the web UI, Ctrl+r in the TUI) to record every finding. For a network share or mailbox scan, start a new scan of the same source.

When your trial ends

When the trial ends, scanning pauses and the web UI shows a Your free trial has ended screen with a link to buy a license. Nothing is deleted: your scans, findings, and settings stay on your machine.

The CLI says the same thing rather than treating the machine as unregistered. A scan prints Your PII Crawler trial has ended, the date the license stopped working, and where to buy one, and piicrawler doctor reports it on the Registration line:

  ✗  Registration   registered as p***[email protected], license expired on 2026-08-18
      Registering that address again won't renew it. Buy a license:
      https://www.piicrawler.com/#pricing

Registering the same address again will not renew a trial, so the CLI says so rather than sending you to a command that cannot work. Commands that only read what is already on your machine, such as piicrawler scans and piicrawler findings, keep working.

After you purchase with the same email you trialed with, open the Register page and the app picks up your full license automatically. If you purchased under a different email, click Register with your purchase email on that screen and verify the new address.

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

Was this page helpful?