# 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.

```bash
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.

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

```
piighost validate <PATH>
```

| Argument | Description |
|----------|-------------|
| `PATH` | Path to a TOML or JSON pipeline config, or a catalog reference such as `catalog:piighost/fr-notarial` |

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.

```bash
$ 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.

```bash
$ 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.

```bash
$ 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), or a catalog reference |
| `--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": [...]}`. 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](api-cli.md).

---

## Getting help

```bash
$ piighost --help
$ piighost anonymize --help
```

---

## See also

- [TOML configuration](../configuration/toml.md) for the schema the CLI validates.