beliq-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 beliq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# beliq-cli
+
+Validate, generate, parse, and convert EU e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) from the terminal or CI, against beliq's authority-pinned, drift-checked rules.
+
+The headline use is **validating e-invoices in CI**: point it at your invoice files, and a non-compliant document fails the build.
+
+## Install
+
+```bash
+npm install -g beliq-cli
+# or run without installing:
+npx beliq-cli validate invoice.xml
+```
+
+Requires Node.js >= 20.15.
+
+## Usage
+
+```
+beliq validate <file|->  [--format auto|cii|ubl] [--fail-on error|warning] [--content-type <mime>] [--json]
+beliq generate <invoice.json|-> --standard xrechnung|zugferd|facturx|peppol-bis [--pdf] [--facturx-profile <p>] [--no-verify] [--output <file>] [--json]
+beliq parse    <file|->  [--format auto|cii|ubl] [--json]
+beliq convert  <file|->  --target-format cii|ubl|zugferd|facturx|xrechnung|peppol-bis [--source-format <f>] [--target-profile <p>] [--output <file>] [--json]
+beliq me                 [--json]
+```
+
+A file argument of `-` reads from stdin. `--json` prints the raw API result as the only thing on stdout, so it pipes cleanly.
+
+```bash
+# Validate a file, human-readable
+beliq validate invoice.xml
+
+# Validate from a pipe, machine-readable, fail the shell on any warning too
+cat invoice.xml | beliq validate - --json --fail-on warning
+
+# Generate an XRechnung from a JSON invoice, write the XML to stdout
+beliq generate examples/invoice.json --standard xrechnung > invoice.xml
+
+# Convert a CII document to a Peppol BIS UBL document
+beliq convert invoice.xml --target-format peppol-bis --output peppol.xml
+```
+
+## Configuration
+
+Every setting has a flag that overrides the environment variable.
+
+| Variable | Flag | Required | Default | Description |
+|---|---|---|---|---|
+| `BELIQ_API_KEY` | `--api-key` | yes | | Your beliq API key. The free tier is enough to evaluate. |
+| `BELIQ_BASE_URL` | `--base-url` | no | `https://api.beliq.eu` | Override only for a self-hosted deployment. |
+| `BELIQ_AUTH` | `--auth` | no | `header` | How the key is sent: `header` (X-API-Key) or `bearer`. |
+
+## Exit codes
+
+The exit code is the contract that makes it useful in scripts and CI:
+
+| Code | Meaning |
+|---|---|
+| 0 | success, or a valid document |
+| 1 | document invalid (`validate`, per `--fail-on`) |
+| 2 | usage error (bad flag, missing argument, missing API key, PDF without `--output`) |
+| 3 | beliq API error (bad key, quota, engine, a rejected document) |
+| 4 | I/O error (unreadable input, or an output path that already exists) |
+
+## In CI
+
+Validate every invoice a build produces and fail on a non-compliant one:
+
+```yaml
+- run: npx beliq-cli validate "dist/invoices/*.xml" --fail-on error
+  env:
+    BELIQ_API_KEY: ${{ secrets.BELIQ_API_KEY }}
+```
+
+For a first-class GitHub Action with a per-file step summary, see `beliq-eu/beliq-validate-action`.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test              # unit tests, no network
+npm run scrub:check   # no em-dash
+BELIQ_API_KEY=... npm run test:integration   # live smoke against the real API
+```
+
+## License
+
+MIT

package/dist/args.js

@@ -0,0 +1,97 @@
+import { UsageError } from './errors.js';
+/** Flags that take no value. */
+const BOOLEAN_FLAGS = new Set(['json', 'pdf', 'no-verify', 'france-ctc']);
+/** Flags that take a value (`--flag value` or `--flag=value`). */
+const VALUE_FLAGS = new Set([
+    'format',
+    'target-format',
+    'source-format',
+    'target-profile',
+    'facturx-profile',
+    'content-type',
+    'fail-on',
+    'standard',
+    'api-key',
+    'base-url',
+    'auth',
+    'output',
+]);
+/**
+ * Parse argv into a command, its positionals, and flags. Hand-rolled (no
+ * dependency): the surface is small and this stays pure and unit-testable. The
+ * first non-flag token is the command; a `-` positional means stdin. Unknown
+ * flags and unknown short options are usage errors.
+ */
+export function parseArgs(argv) {
+    const out = { positionals: [], flags: {}, help: false, version: false };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === '--help' || token === '-h') {
+            out.help = true;
+            continue;
+        }
+        if (token === '--version' || token === '-v') {
+            out.version = true;
+            continue;
+        }
+        if (token.startsWith('--')) {
+            const body = token.slice(2);
+            const eq = body.indexOf('=');
+            const name = eq >= 0 ? body.slice(0, eq) : body;
+            const inlineValue = eq >= 0 ? body.slice(eq + 1) : undefined;
+            if (BOOLEAN_FLAGS.has(name)) {
+                if (inlineValue !== undefined)
+                    throw new UsageError(`option --${name} takes no value`);
+                out.flags[name] = true;
+            }
+            else if (VALUE_FLAGS.has(name)) {
+                let value = inlineValue;
+                if (value === undefined) {
+                    value = argv[++i];
+                    if (value === undefined)
+                        throw new UsageError(`option --${name} needs a value`);
+                }
+                out.flags[name] = value;
+            }
+            else {
+                throw new UsageError(`unknown option --${name}`);
+            }
+            continue;
+        }
+        // A lone "-" is the stdin positional; any other "-x" is an unknown short option.
+        if (token.startsWith('-') && token.length > 1) {
+            throw new UsageError(`unknown option ${token}`);
+        }
+        if (out.command === undefined)
+            out.command = token;
+        else
+            out.positionals.push(token);
+    }
+    return out;
+}
+export function flagBool(args, name) {
+    return args.flags[name] === true;
+}
+export function flagStr(args, name) {
+    const value = args.flags[name];
+    return typeof value === 'string' ? value : undefined;
+}
+export function requirePositional(args, usage) {
+    const value = args.positionals[0];
+    if (value === undefined)
+        throw new UsageError(`missing file argument. Usage: ${usage}`);
+    return value;
+}
+/**
+ * Validate a flag value against an allow-list. Returns the value (typed to the
+ * allowed union), the fallback when the flag is absent, or throws a UsageError
+ * when the value is not allowed.
+ */
+export function oneOf(value, allowed, flagName, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!allowed.includes(value)) {
+        throw new UsageError(`--${flagName} must be one of: ${allowed.join(', ')}`);
+    }
+    return value;
+}

package/dist/cli.js

@@ -0,0 +1,73 @@
+import { Beliq, BeliqApiError } from '@beliq/sdk';
+import { parseArgs } from './args.js';
+import { resolveConfig } from './config.js';
+import { EXIT } from './exit.js';
+import { IoError, UsageError } from './errors.js';
+import { HELP, version } from './help.js';
+import { runValidate } from './commands/validate.js';
+import { runGenerate } from './commands/generate.js';
+import { runParse } from './commands/parse.js';
+import { runConvert } from './commands/convert.js';
+import { runMe } from './commands/me.js';
+const COMMANDS = {
+    validate: runValidate,
+    generate: runGenerate,
+    parse: runParse,
+    convert: runConvert,
+    me: runMe,
+};
+async function dispatch(args, io, env) {
+    const command = args.command ? COMMANDS[args.command] : undefined;
+    if (!command)
+        throw new UsageError(`unknown command "${args.command}". Run beliq --help.`);
+    const config = resolveConfig(args, env);
+    const client = new Beliq({ apiKey: config.apiKey, baseUrl: config.baseUrl, auth: config.auth });
+    return command(args, { client }, io);
+}
+/**
+ * The CLI entry: parse argv, handle --help / --version, dispatch to a command,
+ * and map every error class to its exit code (see EXIT). Pure in its IO + env
+ * seams so it can be driven from a test without touching real streams. Returns
+ * the process exit code.
+ */
+export async function main(argv, io, env = process.env) {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            io.stderr(`beliq: ${err.message}`);
+            return EXIT.USAGE;
+        }
+        throw err;
+    }
+    if (args.help || (!args.command && !args.version)) {
+        io.stdout(HELP);
+        return EXIT.OK;
+    }
+    if (args.version) {
+        io.stdout(`${version()}\n`);
+        return EXIT.OK;
+    }
+    try {
+        return await dispatch(args, io, env);
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            io.stderr(`beliq: ${err.message}`);
+            return EXIT.USAGE;
+        }
+        if (err instanceof IoError) {
+            io.stderr(`beliq: ${err.message}`);
+            return EXIT.IO;
+        }
+        if (err instanceof BeliqApiError) {
+            const code = err.code ? ` (${err.code})` : '';
+            io.stderr(`beliq: API error ${err.status}${code}: ${err.message}`);
+            return EXIT.API;
+        }
+        io.stderr(`beliq: unexpected error: ${err.message}`);
+        return 1;
+    }
+}

package/dist/commands/convert.js

@@ -0,0 +1,46 @@
+import { LIVE_CONVERT_SOURCE_FORMATS, LIVE_CONVERT_TARGET_FORMATS, } from '@beliq/sdk';
+import { flagStr, oneOf, requirePositional } from '../args.js';
+import { UsageError } from '../errors.js';
+import { emitDocument } from './emit.js';
+/** Convert targets that produce a hybrid PDF rather than an XML document. */
+const PDF_TARGETS = new Set(['facturx', 'zugferd']);
+/**
+ * Convert a document from one EN 16931 format to another. An XML target is
+ * printed to stdout (or --output); a PDF target (facturx / zugferd) must go to
+ * --output. Elements the conversion could not carry across are surfaced so a
+ * lossy conversion is visible.
+ */
+export async function runConvert(args, deps, io) {
+    const file = requirePositional(args, 'beliq convert <file|-> --target-format <format>');
+    const targetFormat = oneOf(flagStr(args, 'target-format'), LIVE_CONVERT_TARGET_FORMATS, 'target-format');
+    if (!targetFormat) {
+        throw new UsageError(`--target-format is required (one of: ${LIVE_CONVERT_TARGET_FORMATS.join(', ')})`);
+    }
+    const sourceFormat = oneOf(flagStr(args, 'source-format'), LIVE_CONVERT_SOURCE_FORMATS, 'source-format');
+    const bytes = await io.readInput(file);
+    const result = await deps.client.convert(bytes, {
+        targetFormat: targetFormat,
+        sourceFormat: sourceFormat,
+        targetProfile: flagStr(args, 'target-profile'),
+        contentType: flagStr(args, 'content-type'),
+    });
+    const kind = PDF_TARGETS.has(targetFormat) ? 'pdf' : 'xml';
+    const from = result.meta.sourceFormat ? `${result.meta.sourceFormat} ` : '';
+    const to = result.meta.targetFormat ?? targetFormat;
+    const lost = result.meta.lostElementsCount && result.meta.lostElementsCount > 0
+        ? ` ${result.meta.lostElementsCount} element(s) could not be carried across.`
+        : '';
+    return emitDocument(io, args, {
+        kind,
+        bytes: result.bytes,
+        meta: {
+            sourceFormat: result.meta.sourceFormat,
+            targetFormat: to,
+            profileDetected: result.meta.profileDetected,
+            lostElementsCount: result.meta.lostElementsCount,
+            lostElements: result.meta.lostElements,
+            contentType: result.contentType,
+        },
+        summary: `Converted ${from}to ${to}.${lost}`,
+    });
+}

package/dist/commands/emit.js

@@ -0,0 +1,35 @@
+import { flagBool, flagStr } from '../args.js';
+import { UsageError } from '../errors.js';
+import { EXIT } from '../exit.js';
+/**
+ * Emit a produced document (generate / convert). A PDF must go to --output; XML
+ * without --output is written to stdout so it can be piped. The human summary
+ * goes to stderr so it never mixes into piped bytes. `--json` writes the
+ * metadata to stdout instead (plus the XML text for an XML result).
+ */
+export async function emitDocument(io, args, opts) {
+    const outputPath = flagStr(args, 'output');
+    const json = flagBool(args, 'json');
+    if (opts.kind === 'pdf' && !outputPath) {
+        throw new UsageError('a PDF result needs --output <file> to write it to');
+    }
+    if (outputPath) {
+        await io.writeNewFile(outputPath, opts.bytes);
+        if (json) {
+            io.stdout(`${JSON.stringify({ ...opts.meta, outputPath, bytesWritten: opts.bytes.byteLength }, null, 2)}\n`);
+        }
+        else {
+            io.stderr(`${opts.summary} Written to ${outputPath} (${opts.bytes.byteLength} bytes).`);
+        }
+        return EXIT.OK;
+    }
+    const xml = new TextDecoder().decode(opts.bytes);
+    if (json) {
+        io.stdout(`${JSON.stringify({ ...opts.meta, xml }, null, 2)}\n`);
+    }
+    else {
+        io.stdout(xml.endsWith('\n') ? xml : `${xml}\n`);
+        io.stderr(opts.summary);
+    }
+    return EXIT.OK;
+}

package/dist/commands/generate.js

@@ -0,0 +1,48 @@
+import { LIVE_GENERATE_STANDARDS } from '@beliq/sdk';
+import { flagBool, flagStr, oneOf, requirePositional } from '../args.js';
+import { UsageError } from '../errors.js';
+import { emitDocument } from './emit.js';
+/**
+ * Generate a compliant document from an EN 16931 invoice given as JSON. XML is
+ * printed to stdout (or --output); a PDF must go to --output. verify defaults on
+ * so a non-compliant document fails closed rather than being handed back.
+ */
+export async function runGenerate(args, deps, io) {
+    const file = requirePositional(args, 'beliq generate <invoice.json|-> --standard <standard>');
+    const standard = oneOf(flagStr(args, 'standard'), LIVE_GENERATE_STANDARDS, 'standard');
+    if (!standard) {
+        throw new UsageError(`--standard is required (one of: ${LIVE_GENERATE_STANDARDS.join(', ')})`);
+    }
+    const raw = await io.readInput(file);
+    let invoice;
+    try {
+        invoice = JSON.parse(new TextDecoder().decode(raw));
+    }
+    catch {
+        const what = file === '-' ? 'stdin' : file;
+        throw new UsageError(`${what} is not valid JSON; generate takes an EN 16931 invoice as JSON`);
+    }
+    const output = flagBool(args, 'pdf') ? 'pdf' : 'xml';
+    const result = await deps.client.generate({
+        standard,
+        invoice,
+        output,
+        facturxProfile: flagStr(args, 'facturx-profile'),
+        verify: !flagBool(args, 'no-verify'),
+    });
+    const checked = result.meta.schematronVersion
+        ? `, checked against Schematron ${result.meta.schematronVersion}`
+        : '';
+    return emitDocument(io, args, {
+        kind: output,
+        bytes: result.bytes,
+        meta: {
+            output,
+            contentType: result.contentType,
+            schematronVersion: result.meta.schematronVersion,
+            pdfKind: result.meta.pdfKind,
+            outputEnvelope: result.meta.outputEnvelope,
+        },
+        summary: `Generated a ${standard} ${output} document${checked}.`,
+    });
+}

package/dist/commands/me.js

@@ -0,0 +1,12 @@
+import { flagBool } from '../args.js';
+import { EXIT } from '../exit.js';
+import { renderAccountHuman } from '../format/account.js';
+/** Report the account behind the API key (GET /v1/me, no quota drawn). */
+export async function runMe(args, deps, io) {
+    const account = await deps.client.me();
+    if (flagBool(args, 'json'))
+        io.stdout(`${JSON.stringify(account, null, 2)}\n`);
+    else
+        io.stdout(`${renderAccountHuman(account)}\n`);
+    return EXIT.OK;
+}

package/dist/commands/parse.js

@@ -0,0 +1,19 @@
+import { LIVE_PARSE_FORMATS } from '@beliq/sdk';
+import { flagBool, flagStr, oneOf, requirePositional } from '../args.js';
+import { EXIT } from '../exit.js';
+import { renderParseHuman } from '../format/parse.js';
+/** Parse one document into a structured EN 16931 invoice. */
+export async function runParse(args, deps, io) {
+    const file = requirePositional(args, 'beliq parse <file|->');
+    const format = oneOf(flagStr(args, 'format'), LIVE_PARSE_FORMATS, 'format');
+    const bytes = await io.readInput(file);
+    const result = await deps.client.parse(bytes, {
+        format: format,
+        contentType: flagStr(args, 'content-type'),
+    });
+    if (flagBool(args, 'json'))
+        io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+    else
+        io.stdout(`${renderParseHuman(result)}\n`);
+    return EXIT.OK;
+}

package/dist/commands/validate.js

@@ -0,0 +1,25 @@
+import { LIVE_VALIDATE_FORMATS } from '@beliq/sdk';
+import { flagBool, flagStr, oneOf, requirePositional } from '../args.js';
+import { computeExitCode } from '../exit.js';
+import { renderValidationHuman } from '../format/validate.js';
+const FAIL_ON = ['error', 'warning'];
+/**
+ * Validate one document against beliq's authority-pinned rules. Prints the
+ * verdict (human table or, with --json, the raw ValidationResult) and returns
+ * the CI exit code: 0 if it passes the --fail-on threshold, 1 if it fails.
+ */
+export async function runValidate(args, deps, io) {
+    const file = requirePositional(args, 'beliq validate <file|->');
+    const format = oneOf(flagStr(args, 'format'), LIVE_VALIDATE_FORMATS, 'format');
+    const failOn = (oneOf(flagStr(args, 'fail-on'), FAIL_ON, 'fail-on') ?? 'error');
+    const bytes = await io.readInput(file);
+    const result = await deps.client.validate(bytes, {
+        format: format,
+        contentType: flagStr(args, 'content-type'),
+    });
+    if (flagBool(args, 'json'))
+        io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+    else
+        io.stdout(`${renderValidationHuman(result)}\n`);
+    return computeExitCode(result, failOn);
+}

package/dist/config.js

@@ -0,0 +1,19 @@
+import { DEFAULT_BASE_URL } from '@beliq/sdk';
+import { flagStr } from './args.js';
+import { UsageError } from './errors.js';
+/**
+ * Resolve the typed config with precedence flag > env > default. Throws a
+ * UsageError if no API key is available so the CLI reports a clean usage error
+ * rather than failing mid-request. The SDK reads no environment itself, so the
+ * CLI owns this.
+ */
+export function resolveConfig(args, env = process.env) {
+    const apiKey = (flagStr(args, 'api-key') ?? env.BELIQ_API_KEY)?.trim();
+    if (!apiKey) {
+        throw new UsageError('no API key. Set BELIQ_API_KEY or pass --api-key. Create a key in the beliq dashboard under API Keys.');
+    }
+    const baseUrl = (flagStr(args, 'base-url') ?? env.BELIQ_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const authRaw = (flagStr(args, 'auth') ?? env.BELIQ_AUTH ?? '').trim().toLowerCase();
+    const auth = authRaw === 'bearer' ? 'bearer' : 'header';
+    return { apiKey, baseUrl, auth };
+}

package/dist/deps.js

@@ -0,0 +1 @@
+export {};

package/dist/errors.js

@@ -0,0 +1,6 @@
+/** A user-facing usage problem (bad flag, missing argument, missing key). Maps to EXIT.USAGE. */
+export class UsageError extends Error {
+}
+/** A failure reading a document or writing an output file. Maps to EXIT.IO. */
+export class IoError extends Error {
+}

package/dist/exit.js

@@ -0,0 +1,25 @@
+export const EXIT = {
+    /** Success, or a document that passed validation. */
+    OK: 0,
+    /** A document that failed validation per the chosen --fail-on threshold. */
+    INVALID: 1,
+    /** A usage problem: bad flag, missing argument, missing API key, PDF without --output. */
+    USAGE: 2,
+    /** The beliq API returned an error (bad key, quota, engine, a rejected document). */
+    API: 3,
+    /** A local I/O error: an unreadable input or an output path that already exists. */
+    IO: 4,
+};
+/**
+ * The CI contract: EXIT.OK when the document passes the chosen threshold,
+ * EXIT.INVALID otherwise. `error` (default) fails on any error; `warning` also
+ * fails on any warning.
+ */
+export function computeExitCode(result, failOn) {
+    const errorCount = result.errors?.length ?? 0;
+    const warningCount = result.warnings?.length ?? 0;
+    const failsOnError = !result.valid || errorCount > 0;
+    if (failOn === 'warning')
+        return failsOnError || warningCount > 0 ? EXIT.INVALID : EXIT.OK;
+    return failsOnError ? EXIT.INVALID : EXIT.OK;
+}

package/dist/format/account.js

@@ -0,0 +1,20 @@
+/**
+ * A compact human-readable account summary for `beliq me`: the org, plan, and
+ * key prefix, then the quota and rate limit. `--json` emits the raw AccountInfo.
+ */
+export function renderAccountHuman(account) {
+    const lines = [];
+    const plan = account.plan?.name ? `plan ${account.plan.name}` : 'plan (none)';
+    const key = account.keyPrefix ? `key ${account.keyPrefix}` : '';
+    const org = `org ${account.org?.name ?? account.org?.id ?? 'unknown'}`;
+    lines.push([org, plan, key].filter(Boolean).join('  '));
+    const quota = account.quota;
+    if (quota) {
+        const resets = quota.resetsAt ? ` (resets ${quota.resetsAt})` : '';
+        lines.push(`quota ${quota.used}/${quota.limit} used, ${quota.remaining} remaining${resets}`);
+    }
+    if (typeof account.rateLimitPerMinute === 'number') {
+        lines.push(`rate limit ${account.rateLimitPerMinute}/min`);
+    }
+    return lines.join('\n');
+}

package/dist/format/parse.js

@@ -0,0 +1,18 @@
+function plural(n, word) {
+    return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
+/**
+ * A one-line summary of a parse: the detected syntax and profile, then the
+ * invoice number, line count, and gross total. `--json` emits the full parsed
+ * invoice instead.
+ */
+export function renderParseHuman(result) {
+    const invoice = result.invoice;
+    const profile = result.profileDetected ? ` (profile ${result.profileDetected})` : '';
+    const number = invoice?.number ? `invoice ${invoice.number}` : 'invoice';
+    const lines = invoice?.lines?.length ?? 0;
+    const gross = invoice?.totalGrossAmount != null
+        ? `, gross ${invoice.totalGrossAmount} ${invoice.currencyCode ?? ''}`.trimEnd()
+        : '';
+    return `Parsed a ${result.format}${profile} document: ${number}, ${plural(lines, 'line')}${gross}`;
+}

package/dist/format/validate.js

@@ -0,0 +1,33 @@
+function plural(n, word) {
+    return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
+/**
+ * Render an aligned table. Every column except the last (message) is padded to
+ * its widest cell; the message is left unpadded so a long message never forces
+ * truncation or breaks alignment.
+ */
+function renderTable(headers, rows) {
+    const last = headers.length - 1;
+    const widths = headers.map((h, col) => col === last ? 0 : Math.max(h.length, ...rows.map((r) => r[col].length)));
+    const line = (cells) => cells.map((cell, col) => (col === last ? cell : cell.padEnd(widths[col]))).join('  ');
+    return [line(headers), ...rows.map(line)].join('\n');
+}
+/**
+ * A human-readable verdict: the pass/fail line with format, profile, and
+ * ruleset version, the issue counts, and an aligned table of the errors then
+ * warnings. `--json` emits the raw result instead.
+ */
+export function renderValidationHuman(result) {
+    const errors = (result.errors ?? []);
+    const warnings = (result.warnings ?? []);
+    const verdict = result.valid ? 'VALID' : 'INVALID';
+    const profile = result.profileDetected ? ` (profile ${result.profileDetected})` : '';
+    const schematron = result.schematronVersion ? `  checked against Schematron ${result.schematronVersion}` : '';
+    const head = `${verdict}  ${result.format}${profile}${schematron}`;
+    const counts = `${plural(errors.length, 'error')}, ${plural(warnings.length, 'warning')}`;
+    const issues = [...errors, ...warnings];
+    if (issues.length === 0)
+        return `${head}\n${counts}`;
+    const rows = issues.map((i) => [i.severity, i.ruleId, i.location || '-', i.message]);
+    return `${head}\n${counts}\n\n${renderTable(['SEVERITY', 'RULE', 'LOCATION', 'MESSAGE'], rows)}`;
+}

package/dist/help.js

@@ -0,0 +1,33 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+export function version() {
+    const pkg = require('../package.json');
+    return pkg.version;
+}
+export const HELP = `beliq: validate, generate, parse, and convert EU e-invoices
+
+Usage:
+  beliq validate <file|->  [--format auto|cii|ubl] [--fail-on error|warning] [--content-type <mime>] [--json]
+  beliq generate <invoice.json|-> --standard xrechnung|zugferd|facturx|peppol-bis [--pdf] [--facturx-profile <p>] [--no-verify] [--output <file>] [--json]
+  beliq parse    <file|->  [--format auto|cii|ubl] [--json]
+  beliq convert  <file|->  --target-format cii|ubl|zugferd|facturx|xrechnung|peppol-bis [--source-format <f>] [--target-profile <p>] [--output <file>] [--json]
+  beliq me                 [--json]
+
+Global options:
+  --api-key <key>   beliq API key (default: BELIQ_API_KEY)
+  --base-url <url>  API base URL (default: BELIQ_BASE_URL, else https://api.beliq.eu)
+  --auth <mode>     header (default, X-API-Key) or bearer
+  --json            machine-readable JSON on stdout
+  -h, --help        show this help
+  -v, --version     show the version
+
+Exit codes:
+  0  success, or a valid document
+  1  document invalid (validate, per --fail-on)
+  2  usage error
+  3  beliq API error
+  4  I/O error
+
+A file argument of "-" reads from stdin. Set BELIQ_API_KEY (or pass --api-key)
+with a key from the beliq dashboard; the free tier is enough to evaluate.
+`;

package/dist/index.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { main } from './cli.js';
+import { nodeIO } from './io.js';
+main(process.argv.slice(2), nodeIO()).then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    process.stderr.write(`beliq: fatal: ${err.message}\n`);
+    process.exitCode = 1;
+});

package/dist/io.js

@@ -0,0 +1,38 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { IoError } from './errors.js';
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+}
+export function nodeIO() {
+    return {
+        stdout(chunk) {
+            process.stdout.write(chunk);
+        },
+        stderr(line) {
+            process.stderr.write(`${line}\n`);
+        },
+        async readInput(pathOrDash) {
+            try {
+                return pathOrDash === '-' ? await readStdin() : await readFile(pathOrDash);
+            }
+            catch (err) {
+                const what = pathOrDash === '-' ? 'stdin' : pathOrDash;
+                throw new IoError(`could not read ${what}: ${err.message}`);
+            }
+        },
+        async writeNewFile(path, bytes) {
+            try {
+                await writeFile(path, bytes, { flag: 'wx' });
+            }
+            catch (err) {
+                if (err.code === 'EEXIST') {
+                    throw new IoError(`a file already exists at ${path}; choose a path that does not exist`);
+                }
+                throw new IoError(`could not write ${path}: ${err.message}`);
+            }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "beliq-cli",
+  "version": "0.1.0",
+  "description": "beliq CLI: validate, generate, parse, and convert EU e-invoices (XRechnung, ZUGFeRD, Factur-X, Peppol BIS) against authority-pinned, drift-checked rules, from the terminal or CI.",
+  "license": "MIT",
+  "type": "module",
+  "author": {
+    "name": "beliq",
+    "email": "hello@beliq.eu"
+  },
+  "homepage": "https://beliq.eu",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beliq-eu/beliq-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/beliq-eu/beliq-cli/issues"
+  },
+  "keywords": [
+    "beliq",
+    "cli",
+    "e-invoice",
+    "einvoice",
+    "xrechnung",
+    "zugferd",
+    "factur-x",
+    "peppol",
+    "en16931",
+    "validation",
+    "compliance",
+    "ci"
+  ],
+  "engines": {
+    "node": ">=20.15"
+  },
+  "bin": {
+    "beliq": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "provenance": true
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "test": "vitest run --exclude test/integration.test.ts",
+    "test:integration": "vitest run test/integration.test.ts",
+    "scrub:check": "bash scripts/scrub-check.sh",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@beliq/sdk": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "typescript": "^5.5.4",
+    "vitest": "^2.1.8"
+  }
+}