Updating PII Crawler

PII Crawler ships as a single binary, so updating is a swap: download the new build, replace the old file, done. The fastest way is the built-in piicrawler update command, which fetches the latest build for your platform, verifies its SHA-256, and replaces the running binary in place. If you would rather do it yourself, the manual steps below still work.

Your data is never touched by an update. Scans, findings, triage verdicts, custom regex rules, terms lists, and your license all live in ~/.piicrawler/piicrawler.db (the same path on Linux, macOS, and Windows, relative to your home directory), completely separate from the piicrawler binary. Replacing the binary preserves everything.

Update in place with piicrawler update

piicrawler update

What it does:

1. Fetches https://downloads.eligian.com/piicrawler-cli-<platform>.json for your OS / architecture.
2. Compares the build timestamp baked into your running binary against the published one and tells you whether an update is available.
3. Asks for [y/N] confirmation, then downloads the matching archive, verifies its SHA-256 against the metadata, extracts the binary, and atomically replaces the binary you just ran, at the path it ran from. With nothing attached to stdin to answer the prompt it stops and says to pass --yes, rather than reading end-of-file as "no".

Useful flags:

• --yes / -y: skip the confirmation prompt (for scripted upgrades).
• --force / -f: reinstall even when the local build is already at or newer than the published one.

Platform notes:

• Linux and macOS swap the file atomically. Any already-running piicrawler processes (e.g. a long serve or watch) keep using the old binary until they exit; new invocations pick up the new build.
• macOS updates the command-line install: the archive's standalone piicrawler-cli copy, which is what the quickstart puts at /usr/local/bin/piicrawler. Running update from inside PIICrawler.app stops with a message instead, because replacing one file inside a signed bundle breaks its signature — update the app by replacing the whole .app (see the manual steps below).
• Windows cannot overwrite a running .exe, so the live binary is renamed to piicrawler.exe.old and the new bytes are written at the original path. update names that file and its size when it creates it, and the next time PII Crawler starts it deletes it — so if you may want to go back to the build you just replaced, copy piicrawler.exe.old somewhere else before you run PII Crawler again. Only the current build of each platform is published, so that copy is the only way back.
• Windows installs a second file, piicrawler-launcher.exe, beside piicrawler.exe — it is what the Start-menu shortcut runs, and it starts the web UI with no console window. update replaces it too, from the same archive, whenever it is already installed beside the binary; a portable install that only unzipped piicrawler.exe does not get one added. If it cannot be replaced (another process is using it), update says so and still finishes: the binary is updated and the launcher keeps working.
• The Windows update path always pulls the Azure-Trusted-Signing-signed zip (piicrawler-cli-windows-signed.zip), so SmartScreen continues to recognise both files across upgrades.
• If your platform or architecture is not currently published (for example Linux ARM), the command exits with a friendly error and points you at the download page. Use the manual steps below in that case.

If the install path is in a privileged directory, update says so before it downloads anything and names the directory. On Linux and macOS (for instance /usr/local/bin/) run sudo piicrawler update; on Windows — where the MSI installs under C:\Program Files\ — run it from an Administrator prompt.

Check your current version

Run:

piicrawler version

It prints the version string and nothing else (for example 26.0905.1432), so a script can read it. piicrawler -V and piicrawler --version print the same thing with the program name in front.

The version is a build timestamp — YY.MMDD.HHMM — so two builds made in the same minute share it. To name a build exactly, run:

piicrawler doctor

Its Version line reports the version, the short commit hash the build came from, and how long ago it was built:

  ✓  Version        26.0905.1432 (84919fe)  (built 3h ago)

Quote all of it when you report a problem. The TUI shows the same pair in its title bar, and the web UI at the bottom of the left sidebar (v. 26.0905.1432 84919fe). Builds made outside a source checkout have no commit hash and show only the version.

The latest published version is on the download page.

Manual update steps

If you prefer to update by hand (for example because the install path needs administrative permissions, or you are deploying with a configuration management tool), download the build for your OS from the download page, then overwrite the binary in the same location you installed it.

macOS (Apple Silicon)

The zip holds two things: PIICrawler.app, and piicrawler-cli, a standalone copy of the same build signed on its own. Which one you replace depends on how you installed.

Command line:

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

App: drag the new PIICrawler.app into /Applications, replacing the old one. Replace the whole bundle — swapping the binary inside it breaks the signature Gatekeeper checks, which is why piicrawler update refuses to do it and sends you here.

Both are signed and notarized, so Gatekeeper will not prompt again on launch.

Linux (x86_64)

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

Windows (x86_64)

If you installed with piicrawler-windows.msi, use piicrawler update from an Administrator prompt, or download the new MSI and run it — either replaces both installed files in place and keeps the Start-menu shortcut working. What you should not do is unzip a loose piicrawler.exe over an MSI install by hand: that leaves piicrawler-launcher.exe behind at its old version, and it is easy to grab the unsigned zip by mistake.

For a portable install (the .zip):

1. Quit any running piicrawler.exe process (the TUI, serve, or watch). Windows will not let you overwrite a binary that is in use.
2. Unzip piicrawler-cli-windows-signed.zip — the Azure-Trusted-Signing-signed build, which is the one the download page offers and the one piicrawler update installs. piicrawler-cli-windows.zip also exists on the download server, but it is the unsigned input to the signing pipeline: installing it replaces a signed binary with an unsigned one, and SmartScreen will start warning about it.
3. Move piicrawler.exe into the same folder you installed it (e.g. C:\Users\<you>\bin), overwriting the old file. If that folder also holds piicrawler-launcher.exe — the Start-menu launcher — move the new one over it as well, so the pair stays from the same build.

Verify the upgrade

piicrawler doctor

The version and commit on the Version line should match the build you just installed, and built should read as just now.

Rolling back to an older version

Keep a copy of your current build before you update. PII Crawler publishes new builds continuously, and only the current build of each platform is available for download — older builds are not kept online, so there is no link to go back to once you have replaced your binary.

Rolling back is then the same manual install described above, using the copy you saved:

• macOS / Windows — the piicrawler binary or piicrawler.exe you replaced. Move it back into place.
• Linux — the piicrawler binary you replaced, or the piicrawler-cli-linux.tar.gz you downloaded.

If an update does not work out and you do not have a copy of the previous build, contact [email protected] with the version you were on (the Version line of piicrawler doctor) and what went wrong, and we will help you get back to a working build.

Air-gapped environments

In an air-gapped environment, transfer the new binary the same way you transferred the original (USB, internal mirror, your approved software-distribution channel) and follow the steps above. Your existing scans and license remain intact.