@pii-mask/cli

Command-line tool for masking PII in CSV, JSON, JSONL, and plain text files. Wraps @pii-mask/core with file I/O, stdin/stdout piping, and detection reports.

Installation

# Global install
pnpm add -g @pii-mask/cli

# Or run directly with npx/pnpm dlx
pnpm dlx @pii-mask/cli data.json --mode redact

Usage

pii-mask [file] [options]

If no file is provided, reads from stdin.

Basic Examples

# Mask a JSON file (default 'mask' mode)
pii-mask users.json

# Redact all PII in a CSV
pii-mask customers.csv --mode redact

# Tokenize and save the token map for later restoration
pii-mask records.json --mode tokenize --token-map-out tokens.json

# Pseudonymize JSONL data
pii-mask events.jsonl --mode pseudonymize

# Generate fake replacement data
pii-mask users.json --mode substitute

Stdin / Stdout

Pipe data through the CLI for use in shell pipelines:

# Pipe JSON through stdin
cat users.json | pii-mask --format json --mode redact

# Pipe from another command
curl -s https://api.example.com/users | pii-mask --format json --mode redact > masked.json

# Inline JSON
echo '{"email":"[email protected]","ssn":"123-45-6789"}' | pii-mask --format json --mode redact
# → {"email":"[REDACTED]","ssn":"[REDACTED]"}

When reading from stdin, use --format to specify the format (defaults to json).

Options

| Flag | Type | Default | Description | |------|------|---------|-------------| | file | positional | — | Input file path. Omit to read from stdin. | | --mode | string | mask | Masking mode: mask, redact, pseudonymize, anonymize, tokenize, substitute | | --output | string | ./masked-output | Output directory for masked files | | --in-place | boolean | false | Overwrite the input file instead of writing to output directory | | --format | string | (auto) | Force input format: csv, json, jsonl, txt. Auto-detected from file extension when using a file. | | --disable | string | — | Comma-separated detector IDs to skip (e.g. --disable phone,dob) | | --only | string | — | Comma-separated detector IDs or categories to run exclusively (e.g. --only email,ssn-us) | | --token-map-out | string | — | File path to persist the token map (tokenize mode) | | --report | boolean | false | Print a detection report to stderr without masking output | | --config | string | — | Path to a .pii-mask.json config file |

Detection Report

Use --report to scan for PII without masking. The report prints to stderr:

pii-mask users.json --report

── PII Detection Report ──────────────────────
  email                4 instance(s)
  ssn-us               2 instance(s)
  phone                3 instance(s)
─────────────────────────────────────────────

Config File

Create a .pii-mask.json config file to set defaults:

{
  "mode": "redact",
  "disable": ["dob", "address"],
  "output": "./sanitized"
}

pii-mask users.json --config .pii-mask.json

CLI flags override config file values.

Supported Formats

JSON

Objects and arrays are walked recursively. All string values are checked against detectors.

pii-mask data.json --mode redact

CSV

The first row is treated as headers. Headers are passed as the key parameter to detectors, enabling key-name heuristics (e.g., a column named "password" triggers the secret-key detector).

pii-mask customers.csv --mode mask

JSONL

Each line is parsed as a separate JSON object.

pii-mask events.jsonl --mode pseudonymize

Plain Text

The entire file content is treated as a single string and processed through freeform text scanning.

pii-mask notes.txt --mode redact

Token Map Persistence

In tokenize mode, the CLI can persist the token map to a file. The map accumulates across multiple runs — existing tokens are preserved and new ones are appended.

# First run
pii-mask batch1.json --mode tokenize --token-map-out tokens.json

# Second run — merges into existing tokens.json
pii-mask batch2.json --mode tokenize --token-map-out tokens.json

The token map file is a JSON object mapping tokens to original values:

{
  "<<PII_a1b2c3d4>>": "[email protected]",
  "<<PII_e5f6a7b8>>": "123-45-6789"
}

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | User error (bad arguments, unsupported format, TTY with no file) | | 2 | Unexpected runtime error |

License

MIT