Install the command-line interface with pip install "cerbia[cli]". The
executable provides scan and validate.
cerbia validate CONFIG.yaml
Validate one YAML configuration file, construct its Runner, and print the
configured pipeline. This command does not load entries or execute scanners.
cerbia validate examples/cli-usage/config.cerbia.yaml| Input | Meaning |
|---|---|
|
Required path to one YAML configuration file. Directories are not supported. |
|
|
|
Write logs to this path instead of standard error. |
Exit code 0 means the file parsed and its pipeline could be constructed.
Missing or malformed configuration files exit 2; a configuration that parses
but cannot construct its pipeline exits 1 for CerbIAError or 2 for
TypeError.
cerbia scan --config CONFIG.yaml
Run one configured pipeline and render a result for each loaded entry.
cerbia scan --config examples/cli-usage/config.cerbia.yaml --text "Text to scan"| Option | Meaning |
|---|---|
|
Required path to one YAML configuration file. |
|
Repeatable inline input. Any supplied values replace configured loaders. |
|
Repeatable file input. Any supplied values replace configured loaders. |
|
Write JSON results to a path ending in |
|
Override the YAML threshold for this invocation. |
|
Show and serialize only unsafe entry results. It does not change scanner execution. |
|
|
|
Write logs to this path instead of standard error. |
The --unsafe-only option filters console output and entry_results in JSON; it does not change scan execution or exit codes.
Inline text and file options replace every loader configured in YAML. When no override is supplied, the configuration’s loaders are used. The command rejects a run with no loaders after this selection.
FileLoader treats missing paths and extension-filtered paths as no entries,
so a --file value can produce an empty, safe result rather than an error.
With no explicit logging options, the standalone command preserves the host
logging setup when one exists. In a standalone process with no root handlers it
installs an INFO stderr handler for that CLI process; if a root handler
already exists, it installs nothing. This CLI-owned behavior differs from
reusing CerbIA as a library import, which has no logging-configuration side
effects. Explicit logging options control that CLI invocation.
Output and exit codes
The terminal output groups findings by entry. Each scanner row shows its outcome; skipped scanners are retained in the entry result so routing and error policy decisions remain visible.
--output serializes a ScanResult with entry_results, is_safe,
total_findings, and unsafe_entries. Every entry result includes the entry
metadata, aggregated_score, rationale, findings, and skipped scanners. Raw
entry text is included in the serialized entry, so treat JSON output as
potentially sensitive and store it accordingly.
| Exit code | Meaning |
|---|---|
|
Every resulting entry is safe, including an empty result set. |
|
At least one resulting entry is unsafe. |
|
Usage, configuration, input selection, output-path, or handled execution error. |
Examples
# Use loaders from the configuration.
cerbia scan --config examples/cli-usage/config.cerbia.yaml
# Scan two inline values instead of configured loaders.
cerbia scan -c examples/cli-usage/config.cerbia.yaml -t "first input" -t "second input"
# Scan local files and write only unsafe entry results to JSON.
cerbia scan -c examples/cli-usage/config.cerbia.yaml -f input.txt --unsafe-only -o results.json
# Inspect a configuration before running it.
cerbia validate examples/cli-usage/config.cerbia.yaml --log-level DEBUG