Skip to content

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. Run without it, 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, which makes them 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>
Argument Description
PATH Path to a TOML or JSON pipeline config

The exit code is 0 on success and 1 on any configuration error, whether a missing file, invalid TOML or JSON syntax, or a value that fails schema validation. The error message is written to stderr, which suits the command for 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 it runs a generic RegexDetector. --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]
Option Description
TEXT The text to de-identify, or - to read stdin
--config PATH A pipeline config file (TOML or JSON)
--api URL Base URL of a piighost-api server, used through the HTTP client
--thread-id ID Thread id for the API or a thread-scoped config (default default)
--json Print the de-identified text and the detections as JSON

--config and --api are mutually exclusive. With --json, the output is {"anonymized_text": ..., "detections": [...]}.

Those detections are the detector's own output, read straight from the detector for the listing. They are not the set the de-identified text was rendered from, so an overlap the resolver dropped and a value an override cleared both still appear. Read them as what the detector saw, and anonymized_text as what the pipeline decided.

Getting help

$ piighost --help
$ piighost anonymize --help

See also