Command-line interface

Module: piighost.cli

piighost is a small command-line tool that validates and inspects a pipeline configuration and de-identifies text from the shell. It is installed as a console entry point with the config extra.

pip install "piighost[config]"

The tool needs typer, shipped with the config extra. If typer is missing, the CLI prints a short install hint to stderr and exits 1, rather than a traceback. The validate and schema subcommands instantiate no pipeline component. So they build no detector and load no model. They are therefore fast and safe to run in CI.

piighost validate

Parses and validates a configuration file, TOML or JSON by its suffix, against the pipeline schema. It checks the structure and every value without building a component.

$ piighost validate ./pipeline.toml
OK: pipeline.toml

piighost validate <PATH>

The exit code is 0 on success and 1 on any configuration error, whether a missing file, invalid TOML or JSON syntax, a value that fails schema validation, or a catalog that cannot be reached. The error message is written to stderr. So the command suits a CI gate.

$ piighost validate ./broken.toml
invalid configuration in broken.toml: ...
$ echo $?
1

piighost schema

Prints the JSON Schema of PipelineConfig to stdout. The schema is generated by Pydantic from the config models, so it always matches the version of piighost installed.

$ piighost schema > schema.json

Point an editor at schema.json for autocompletion and inline validation of a config file, or feed it to any tool that consumes JSON Schema.

piighost anonymize

De-identifies a text and prints the result. The text is an argument, or - to read stdin. By default, the command runs a RegexDetector over the catalog group catalog:piighost/generic:fab51b33 (DEFAULT_CATALOG in piighost.cli). The group is fetched on the first run, then read from the on-disk cache. --config runs a configured pipeline, and --api runs a remote piighost-api server. Unlike validate and schema, this builds and runs the pipeline.

$ piighost anonymize "mail me at a@b.co"
mail me at <<EMAIL:1>>

$ echo "mail me at a@b.co" | piighost anonymize -
mail me at <<EMAIL:1>>

$ piighost anonymize "reach a@b.co" --config ./pipeline.toml
$ piighost anonymize "reach a@b.co" --api https://piighost.internal

piighost anonymize [TEXT] [--config PATH | --api URL] [--thread-id ID] [--json]

--config and --api are mutually exclusive. With --json, the output is {"anonymized_text": ..., "detections": [...]}. The listed detections are those the text replaced, after overlap resolution, overrides and the expander. A configuration that does not validate prints the same message as validate and exits 1. When a catalog group cannot be pulled, the command prints Could not pull from the catalog: followed by the cause and exits 1. --api sends no API key. So it reaches only a server started with PIIGHOST_ALLOW_ANONYMOUS, see Server CLI.

Getting help

$ piighost --help
$ piighost anonymize --help

See also

• TOML configuration for the schema the CLI validates.