Metadata-Version: 2.5
Name: maskflow-cli
Version: 0.8.0
Summary: Command-line interface for MaskFlow: .maskflowrc config validation and inspection
License: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: maskflow-core[yaml]<0.9,>=0.6.0
Requires-Dist: maskflow-pack-india<0.6,>=0.1.0
Requires-Dist: maskflow-pack-intl<0.4,>=0.3.0
Requires-Dist: rich>=13.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.12
Provides-Extra: bench
Requires-Dist: maskflow-bench<0.2,>=0.1.0; extra == 'bench'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: evidence
Requires-Dist: maskflow-evidence<0.2,>=0.1.0; extra == 'evidence'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Provides-Extra: s3
Requires-Dist: boto3>=1.34; extra == 's3'
Description-Content-Type: text/markdown

# maskflow-cli

Command-line interface for [MaskFlow](https://github.com/):

```
maskflow config validate
maskflow config show --resolved
maskflow doctor
maskflow explain "<text>"
maskflow scan jsonl requests.jsonl --field 'messages[].content'
```

`maskflow doctor` checks installed versions, spaCy model presence (and
which entities that consequently disables), and `.maskflowrc` validity,
then reports enabled/disabled status for every registered entity. It
exits 0 only when every check passes.

`maskflow explain "<text>"` shows, span by span, why each piece of text
was (or wasn't) detected as PII -- the pattern/NER hit, checksum result,
context boost, and the threshold decision behind it. Spans that scored
below their entity's threshold are listed separately as NEAREST MISSES,
with the `.maskflowrc` change that would catch them. Matched text is
truncated to 8 characters unless `--full` is passed. Accepts the same
`--config`/`--set` overrides as `maskflow config`, so explanations reflect
the same resolved config a real `mask()` call would use.

## `maskflow scan` -- what PII already reached your LLM providers

`maskflow scan SOURCE ...` answers the question a DPDP-deadline audit asks
first: **what PII has this system already sent to third-party LLM
providers, and how bad is it?** It reads your historical LLM traffic, runs
MaskFlow's own detection over it, and writes **one self-contained HTML
report** -- inline CSS/JS, zero external requests, so it prints cleanly and
can be emailed to an auditor as-is.

**Features**

- **Eight source adapters**, one interface: `jsonl` / `ndjson` (with
  `--field` selectors), `csv` (`--columns`), `dir` (recursive), `s3`
  (streamed), `postgres` (server-side cursor), and the `langfuse` /
  `helicone` / `langsmith` REST APIs. `s3` and `postgres` need the
  `maskflow-cli[s3]` / `[postgres]` extras; the rest need nothing extra.
- **Streaming, bounded memory** -- inputs can be gigabytes. `--workers N`
  parallelises detection; `--checkpoint FILE` makes a run resumable;
  `--sample N` is a fast first pass.
- **Hybrid detection.** The pattern/checksum pass (Aadhaar, PAN, GSTIN,
  UPI, IFSC, cards, email, ...) covers the whole corpus. The NER pass
  (bare names & addresses) runs on a sample and is reported as a clearly
  labelled estimate -- pass `--deep` to run it over everything.
- **The report**: one headline number, breakdowns by entity type /
  provider / model / time, a severity ranking with a plain-English "why
  this matters" per row, **masked excerpts only** (values shown as
  `<AADHAAR_1>`, never raw), and a DPDP Rule 6 mapping appendix. Also
  `--format json|csv`.
- **Runs entirely locally. Nothing is transmitted.** The API sources only
  *read* from your own observability account.

**Try it** -- a synthetic 60-record sample ships in
[`examples/`](examples/):

```bash
uv run maskflow scan jsonl packages/maskflow-cli/examples/sample-llm-traffic.jsonl \
  --field 'messages[].content' \
  --provider-field provider --service-field model --timestamp-field created_at \
  --deep --out exposure-report.html
```

Notes: `uv run` runs the CLI from the workspace venv -- drop it if
`maskflow-cli` is on your `PATH` (`pipx install maskflow-cli`). Quote the
`--field` value: `messages[].content` contains `[]`, which the shell would
otherwise try to expand.

**Install it** -- four ways, see
[`packaging/`](packaging/) and [`docs/scan.md`](../../docs/scan.md#install):

| | NER (names/addresses/DOB) |
|---|---|
| `pipx install maskflow-cli` + `python -m spacy download en_core_web_sm` | yes |
| `docker run --rm -v "$PWD:/work" ghcr.io/maskflow/cli scan ...` | yes, baked in |
| standalone binary (GitHub Releases, no Python) | no -- pattern pass only |
| [`maskflow/scan-action`](../../packaging/scan-action/) for CI | yes |

Then open `exposure-report.html`. See [`examples/README.md`](examples/README.md)
for a walk-through of the output, and `docs/scan.md` for the full reference.

See `docs/configuration.md` in the repo root for the full config reference.
