CLI

The Beliq CLI validates, generates, parses and converts e-invoices from a terminal or CI. Each verdict shows the check depth the API states for it.

Available

The beliq CLI wraps the same API as the SDKs for the terminal and CI. It is a thin layer over the Node SDK, so validation, generation, parsing, and conversion behave identically to every other path.

• Package: beliq-cli on npm (binary beliq)
• Source: github.com/beliq-eu/beliq-cli

npm install -g beliq-cli
# or run without installing
npx beliq-cli validate invoice.xml

The CLI reads your key from --api-key or the BELIQ_API_KEY environment variable (the flag wins over the env):

export BELIQ_API_KEY="blq_..."
beliq me            # zero-quota credential check

beliq --help lists every command with the values each flag accepts.

validate accepts many file arguments, shell globs, and a directory (walked recursively over .xml and .pdf). It prints a per-file row (PASS, FAIL or ERROR, the error and warning counts, and the check depth) and an aggregate summary. A directory is a batch even when it holds one file, so its --json shape does not depend on how many invoices it contains:

beliq validate invoices/            # every .xml / .pdf under invoices/
beliq validate out/*.xml --fail-on error   # the shell expands the glob

The CLI does not expand a glob itself, so leave it unquoted. A file argument of - reads the document from stdin.

For one document, validate prints a verdict line: the verdict word, the detected format and profile, the check depth, and the Schematron version where one ran. Below it come the error and warning counts and a table of every finding.

• VALID and INVALID are the API’s valid. valid means the document passed the rule packs and schemas Beliq runs for its format, in the versions the result names. It does not mean every recipient, validation tool or tax authority accepts it.
• The check depth is the label the API sends in verificationBadgeLabel, printed as it came. How verification works says what each depth means. Where the API sends no label, the CLI prints check depth not stated and names no depth.
• For a PDF, a line says which embedded XML the verdict is about. The PDF itself is not checked.
• When the result carries franceCtcBlockingRuleIds, the CLI prints the API’s message for them with the rule ids, and the file fails with exit code 1 under every --fail-on, also where the verdict is VALID. The API reports those ids beside valid and does not fold them into it.

generate names the same depth in its summary, or not validated with --no-verify. convert prints no verdict and no depth: a successful convert means the API validated the converted XML before returning it. For a facturx or zugferd target at profile en16931 the converted document carries the plain EN 16931 identifier, so it is checked as EN 16931 CII and against no Factur-X profile schema.

The exit code is the contract for scripts and CI:

In batch mode the code covers the whole run: 3 if any file could not be checked, else 1 if any document failed, else 0. A missing key (401), a refused key or a forbidden request (403), or a rate limit (429) stops a batch: the CLI prints the API error instead of the report and exits 3.

--json prints the raw result (a batch report { total, passed, failed, errored, results } in batch mode) as the only thing on stdout, so piped output stays clean. Without it, validate, parse and me print their human-readable report on stdout; generate and convert print the document on stdout and a one-line summary on stderr.

In a batch report, the row of a checked file carries the file, a status of pass or fail, and every field of the API result. status is the CLI’s call under --fail-on and the France rule, so a row can be fail with valid: true: a warning under --fail-on warning, or France CTC blocking rule ids. A file that could not be checked has status: "error" and a message.

An API error prints its code and message on stderr. When the API names the rules a document failed, the CLI prints them after the message in the same table validate uses. generate names them when it refuses to return an invoice that fails its own validation (422 INVALID_INVOICE), and convert when it refuses a converted document that fails validation (422 CONVERSION_OUTPUT_INVALID, the details). With --json, stdout also carries the error as { "error": { "status", "code", "message", "details" } }.

• Node SDK: the client the CLI wraps.
• GitHub Action: run the same validation in a pull request.
• Quickstart: the underlying API in five minutes.