VellumPdf.Cli 2.0.0

VellumPdf.Cli

vellum-preflight — the command-line PDF/A and PDF/UA validator from VellumPdf, a dependency-free PDF library for .NET 10. It checks a PDF against PDF/A-2b/2u/2a and PDF/UA-1 with the in-process VellumPdf.Conformance engine, with no JVM and no Docker.

• Ships as a cross-platform .NET tool and as self-contained Native-AOT binaries.
• Text, JSON, and SARIF 2.1.0 output; file, glob, directory, and stdin inputs.
• Exit codes: 0 (conformant), 1 (non-conformant), 2 (usage or I/O error).

Install

dotnet tool install -g VellumPdf.Cli

Or download a self-contained native binary (Windows x64/Arm64, macOS Arm64, Linux x64) from the latest release.

Usage

# Does the PDF honour the conformance level it claims? (pass/fail, with reasons)
vellum-preflight invoice.pdf

# A specific profile, machine-readable output
vellum-preflight invoice.pdf -p 2u -f json -o report.json

# Validate a whole tree; fail CI on any error
vellum-preflight ./out --recurse --fail-on error -q

# Several profiles at once
vellum-preflight report.pdf -p 2b,2a,ua1

JSON report shape

The shape changed in 2.0. summary.total used to be failed + passed + notEvaluated, which added a count of rule assertions to a count of catalogue checks. It is now the size of the profile's check catalogue, and failedChecks and inconclusive are new.

{
  "tool": "vellum-preflight",
  "toolVersion": "2.0.0",
  "file": "invoice.pdf",
  "profile": "PDF/A-2b",
  "profileSource": "explicit",   // "explicit" or "auto" (from the PDF's own claim)
  "conformant": false,
  "summary": {
    "error": 4, "warning": 0, "info": 0,   // rule assertions, by severity
    "passed": 132,                          // catalogue checks satisfied
    "failedChecks": 0,                      // catalogue checks a rule named by test id
    "inconclusive": 9,                      // clause failed, specific check unidentified
    "partial": 2, "deferred": 0,            // subsets of notEvaluated
    "total": 144                            // passed + failedChecks + inconclusive + notEvaluated
  },
  "failed": [
    { "ruleId": "ISO19005-2:6.3.4-font-embedding",
      "clause": "ISO 19005-2:2011, 6.3.4",
      "severity": "ERROR",
      "message": "The font /Helvetica is not embedded; ..." }
    // "objectRef" is present only when the rule identified an object
  ],
  "passed":       [ { "testId": "6.1.3-1", "clause": "6.1.3" } ],
  "failedChecks": [],
  "inconclusive": [ { "testId": "6.1.2-1", "clause": "6.1.2" } ],
  "notEvaluated": [ { "testId": "6.1.13-10", "clause": "6.1.13",
                      "status": "Partial", "note": "..." } ]
}

failed lists rule assertions; the four check arrays partition the catalogue, so every catalogued check appears in exactly one of them. A check lands in inconclusive when a rule failed in its ISO clause without a test id identifying which check it corresponds to — that check can then be neither claimed as passing nor blamed for the failure. Before 2.0 those checks were dropped from the report entirely.

Several input files, or several profiles for one file, produce { "results": [ ... ] } with one object of the above shape per result.

Documentation

Command-line reference: https://github.com/Tim81/VellumPDF#command-line-preflight

The VellumPdf family

Roadmap

License

Apache-2.0. Source and issues: https://github.com/Tim81/VellumPDF