CLI¶
spanguard installs a spanguard command with two subcommands: scan
(report what would be redacted, without ever printing raw values) and
redact (write the redacted text).
Given a file notes.txt:
spanguard scan¶
Reports entity-type counts only — never the matched raw values.
Restrict to specific entity types with --entities (comma-separated):
Emit the audit record as JSON with --json:
$ spanguard scan notes.txt --json
{"counts": {"EMAIL": 1, "PHONE": 1, "SSN": 1}, "policy_hash": "e064cd5139c733ed", "ts": "2026-07-06T00:55:46.523122+00:00"}
spanguard redact¶
Writes redacted text to stdout (or a file with --out).
$ spanguard redact notes.txt --mode placeholder
Patient contacted via [EMAIL] or [PHONE].
SSN on file: [SSN].
--mode accepts mask (default), placeholder, hash, or tokenize.
--entities filters which entity types are redacted, same as scan:
$ spanguard redact notes.txt --mode mask --entities EMAIL,PHONE
Patient contacted via ████████████████ or ████████████.
SSN on file: 123-45-6789.
Write to a file instead of stdout:
Emit the audit record as JSON to stderr (so it never mixes with the
redacted text on stdout) with --audit-json:
Reading from stdin¶
Pass - as the file to read standard input, so spanguard can sit in a
pipeline:
$ cat notes.txt | spanguard redact - --mode placeholder > redacted.txt
$ some-transcriber --live | spanguard scan - --json
Exit codes and errors¶
| Code | Meaning |
|---|---|
0 |
Success. |
2 |
Usage or input error, printed as error: ... on stderr. Nothing is written to stdout. |
Error messages name the path or entity label involved and never echo any input content:
$ spanguard redact notes.txt --entities EMIAL
error: unknown entity type(s): EMIAL; choose from EMAIL, PHONE, SSN, MRN, DOB, CREDIT_CARD, API_KEY
$ spanguard scan latin1.txt
error: cannot decode latin1.txt as UTF-8
$ spanguard scan missing.txt
error: file not found: missing.txt
An unknown --entities name is an error rather than being skipped, because
silently ignoring a typo would leave that entity type unredacted. PERSON
and LOCATION (spaCy NER) are library-only; see
Recognizers.
Notes¶
- Both commands read their input (file or stdin) as UTF-8.
scanalways resolves an internalplaceholderpolicy to compute counts; it never writes the redacted text anywhere.- The CLI forces its stdout/stderr streams to UTF-8 so
maskmode's█mask character never crashes on a non-UTF-8 console.