pdfnative-cli — Command-Line Interface Guide

Tracks the latest published pdfnative-cli (v1.5.0, requires pdfnative ≥ 1.8.0 — pins ^1.8.0). The CLI versions independently from the library. Live package versions — and the pdfnative version each one is built on — are shown at the top of the documentation home. Full history: pdfnative-cli releases.

pdfnative-cli is the official command-line interface for the pdfnative library. It exposes 21 commands in five groups — create & edit (render, fill, annotate, metadata), page tree (merge, split, extract), security (sign, verify, ltv, doc-timestamp, encrypt, decrypt), read & extract (inspect, extract-text, compare), and automation & meta (batch, doctor, schema, completion, govern) — that together cover the full document lifecycle from JSON to a signed, timestamped, archive-grade PDF with the complete PAdES ladder (B-B → B-T → B-LT → B-LTA), plus page-tree editing, markup annotations, document comparison, and an AI-governance gate, with an agent-native automation contract for autonomous AI and CI pipelines. Since v1.5.0 it also exposes the typography engine, PDF/X-4 output with CMYK colours, custom fonts from disk and byte-reproducible builds.

Why a CLI? Many real-world workflows live outside Node.js: shell scripts, CI pipelines, Docker containers, Makefiles, batch jobs, build tools written in other languages. The CLI lets all of them call pdfnative without writing JavaScript, and is fully composable through stdin/stdout pipelines.

The CLI is a pure dispatch layer over pdfnative. No PDF logic lives in the CLI itself — every command forwards to a public pdfnative API:

This means every feature of the library is one release away from the CLI, and any bug fix in pdfnative is automatically picked up by pdfnative-cli on its next dependency bump.

Installation#

# Run directly with npx — no global install required
npx pdfnative-cli render --input document.json --output report.pdf

# Or install globally
npm install --global pdfnative-cli
pdfnative render --input document.json --output report.pdf

Requirements: Node.js ≥ 22 (since v1.4.0 — Node 20 reached end-of-life on 2026-04-30) · Bun · Deno (node dist/cli.cjs).

The CLI ships with NPM provenance — verify the published artifact with npm audit signatures or on npmjs.com.

When to use the CLI vs the library#

The two are complementary. A typical full-stack project uses the library at runtime and the CLI in CI scripts and operator workflows.

Quick start#

1. Render a document#

Create report.json:

{
  "title": "April 2026 Report",
  "blocks": [
    { "type": "heading", "text": "April 2026 Report", "level": 1 },
    { "type": "paragraph", "text": "Summary for the financial period ending 30 April 2026." },
    { "type": "list", "style": "bullet", "items": [
      "Revenue: +18% year-on-year",
      "Net Promoter Score: 72",
      "Active customers: 12,400"
    ]},
    { "type": "table",
      "headers": ["Quarter", "Revenue", "Profit"],
      "rows": [
        { "cells": ["Q1", "$1.2M", "$400K"], "type": "credit", "pointed": false },
        { "cells": ["Q2", "$1.5M", "$600K"], "type": "credit", "pointed": true }
      ]
    }
  ],
  "footerText": "Confidential",
  "metadata": { "author": "Finance Team", "subject": "April 2026 Report" }
}

Render it:

pdfnative render --input report.json --output report.pdf

That's it — the file report.pdf is now a valid ISO 32000-1 PDF, ready to send.

2. Sign the rendered PDF (with metadata)#

# Set keys via environment variables (recommended for CI/CD — never logged)
export PDFNATIVE_SIGN_KEY="$(cat private.pem)"
export PDFNATIVE_SIGN_CERT="$(cat cert.pem)"

pdfnative sign \
  --input report.pdf \
  --output report.signed.pdf \
  --reason "Approved by Finance" \
  --name "Finance Team" \
  --location "Paris, FR" \
  --signing-time 2026-04-28T10:00:00Z

The CLI accepts both RSA PKCS#1 v1.5 and ECDSA P-256 keys, both with SHA-256 digests. The signed PDF carries a CMS/PKCS#7 signature embedded as ISO 32000-1 §12.8 prescribes, validatable by Adobe Acrobat, MuPDF, and any other PAdES-compatible reader.

3. Verify embedded signatures#

pdfnative verify --input report.signed.pdf --strict --trust ca-root.pem

v0.3.0 performs real CMS/PKCS#7 verification — the CLI recomputes the byte-range digest, validates the signature value (RSA-SHA256 or ECDSA-SHA256), walks the certificate chain via pdfnative's verifyCertSignature, evaluates trust against --trust roots and self-signed acceptance, and reports the presence of an RFC 3161 timestamp token. Exit code is 0 on success, 1 on any failure under --strict.

A sample JSON report:

{
  "signatures": [
    {
      "integrity": true,
      "signatureValid": true,
      "signatureAlgorithm": "ecdsa-sha256",
      "chainValid": true,
      "trustedRoot": true,
      "timestampPresent": false,
      "signerSubject": "CN=pdfnative-cli ECDSA Test, O=pdfnative-cli, C=FR",
      "signerIssuer": "CN=pdfnative-cli ECDSA Test, O=pdfnative-cli, C=FR",
      "notes": ["no --trust provided; accepted self-signed root"]
    }
  ]
}

4. Inspect any PDF#

pdfnative inspect --input report.signed.pdf --format text

Version:        1.7
Pages:          2
Encrypted:      no
PDF/A:          none
Signatures:     1
Title:          April 2026 Report
Author:         Finance Team
Created:        2026-04-28T10:00:00+00:00
Subject:        April 2026 Report
Producer:       —

JSON output (default) is suited for piping into jq or storing as a CI artifact.

Hybrid layout model#

render adopts the same layout philosophy as gh, kubectl, and docker: high-frequency knobs are first-class flags, while the full PdfLayoutOptions shape is reachable via a JSON layout file.

Precedence: CLI flags > --layout file > pdfnative defaults.

# 1) Flags only — best for ad-hoc invocations
pdfnative render --input doc.json --output report.pdf \
  --page-size A4 --margin 50 --compress --tagged pdfa2b

# 2) Layout file only — best for reproducible CI configs
pdfnative render --input doc.json --output report.pdf \
  --layout layout.json

# 3) Hybrid — base config in a file, per-job overrides on the CLI
pdfnative render --input doc.json --output report.pdf \
  --layout layout.json \
  --watermark-text "DRAFT $(date +%Y-%m-%d)"

layout.json accepts any subset of PdfLayoutOptions:

{
  "pageSize": { "width": 595, "height": 842 },
  "margin": { "top": 60, "right": 50, "bottom": 60, "left": 50 },
  "compress": true,
  "tagged": "pdfa2b",
  "headerTemplate": { "left": "{title}", "right": "{date}" },
  "footerTemplate": { "center": "Page {page} / {pages}" }
}

Security: --layout paths are validated against directory traversal, and any attachments[].data field embedded in the JSON is stripped on load. Binary attachment payloads must come from --attachment <path> so the CLI can apply the same path-validation rules.

Command reference#

pdfnative render#

Renders a JSON document into a PDF. Supports both renderer variants exposed by pdfnative.

Core flags#

Smart tables (v1.3.0, document variant)#

These flags fill TableBlock fields left unset in the JSON (caption is per-table — set it in the JSON TableBlock):

Page geometry#

PDF/A conformance#

PDF/X-4 output (v1.5.0)#

One conformance claim per file — --pdfx is mutually exclusive with --tagged / --conformance and with every encryption flag (rejected with exit 2 before the build). Needs pdfnative ≥ 1.8.0.

Colours everywhere — document JSON, --layout and colour flags — accept CMYK beside hex / RGB: "c m y k" operands in 0–1 or [c,m,y,k] in percent (DeviceCMYK). layout.print.marks.colourBars: true | { tints, size } adds printer's colour bars to the marks. Re-check the result with pdfnative inspect --check pdfx (structural validation evidence, not a certified preflight).

Watermarks#

Watermarks with transparency are mutually exclusive with PDF/A-1b (ISO 19005-1 §6.4). The pdfnative core enforces this at render time — the run fails with the generic exit code 1 (Watermark transparency is not allowed with PDF/A-1b), not a CLI usage error.

Headers / footers#

Supported placeholders: {page}, {pages}, {date}, {title}. The {pages} placeholder is rejected with --stream because the total page count is only known after multi-pass pagination.

Encryption#

Since v1.3.0, render speaks the same unified encryption vocabulary as merge / split / extract:

The legacy v0.2.0 flags — --encrypt-algorithm, --encrypt-owner-pass, --encrypt-user-pass, --encrypt-permissions — remain accepted as aliases; when both are given, the unified value wins.

Env vars take precedence over flags, ensuring secrets never appear in shell history. Encryption is mutually exclusive with --tagged pdfa* per ISO 19005-1 §6.3.2 — rejected with exit 2.

PDF/A-3 attachments#

The Windows drive-letter colon (D:\path) is detected and not split — see Troubleshooting.

Multilingual fonts#

--lang activates a programmatically registered font loader via loadFontData(code). Latin scripts are built-in. With v1.1.0, every bundled font is registrable directly through --font — no wrapper script needed for the 27 bundled scripts, colour emoji, or Latin. pdfnative routes each code point to the font whose cmap covers it. Since v1.5.0, a font you ship yourself is registered with --font-file; see Recipes → Multilang fonts for the library path when you need a custom loader.

Bookmarks, math & layout tooling (v1.2.0)#

# Bookmarks derived from headings + math font
pdfnative render --input paper.json --output paper.pdf --outline auto --font math

# Layout introspection instead of a PDF
pdfnative render --input report.json --inspect-layout > layout.json

Print production, images from JSON & charts v2 (v1.4.0)#

Everything here needs pdfnative ≥ 1.7.0 and is reachable through the existing --layout file and the document JSON. v1.4.0 added no flags for it; since v1.5.0, typography and PDF/X have dedicated flags (see PDF/X-4 output above and Typography below), and layout.outputIntent can be supplied with --output-intent-icc:

• Image blocks in the document JSON — { "type": "image", "src": "logo.png" } (path resolved relative to the --input JSON, same validation as --attachment) or { "type": "image", "dataBase64": "…" } for inline JPEG/PNG.
• layout.print — bleed, trimBox / bleedBox / artBox / cropBox, vector printer's marks (print.marks), and /UserUnit (1–75 000). merge / split / extract now preserve these boxes too.
• layout.outputIntent — a custom RGB ICC output intent; layout.viewerPreferences — duplex, pickTrayByPDFSize, printPageRange, numCopies.
• params.metadata — author, subject, keywords, and trapped: True|False|Unknown, written to /Info and XMP.
• Charts v2 — the chart block now covers 9 types (adds stackedBar, stackedBarH, area, scatter), a secondary Y axis (series.yAxis: "right" + axis2), category / linear / time X axes, log scale, dataLabels, labelStride, and labelRotation.

Typography (v1.5.0)#

The pdfnative 1.8.0 typography engine is reachable through layout.typography — in the document JSON or a --layout file — and four flags that fill the same keys:

layout.typography carries the engine's 12 keys verbatim: widows, orphans, splitParagraphs, keepHeadingsWithNext, opticalMargins, punctuationSpacing ("fr", "fr-CA" or a rules array), unitBinding, bindShortWords, hyphenationLanguage, kerning, fontFeatures, metrics ("exact" acts on the base-14 path only). Soft hyphens (U+00AD) are honoured unconditionally. Paragraph blocks accept align: "justify", keepWithNext and splittable; heading blocks accept keepWithNext. Flags win over the file; nested typography / outputIntent objects merge one level deep between the document, --layout and the flags. punctuationSpacing: "fr" inserts narrow no-break spaces only where a font is embedded (--font latin --lang latin).

pdfnative render --input report.json --output report.pdf --font latin --lang latin \
  --split-paragraphs --keep-headings-with-next --kerning --font-features onum,smcp

Iteration helpers (v0.3.0)#

# Watch a file
pdfnative render --input report.json --output report.pdf --watch

# Template + override (template carries title/layout/headers, stdin overrides body)
echo '{"blocks":[{"type":"paragraph","text":"Today only."}]}' \
  | pdfnative render --template template.json -o today.pdf

# Bundled fonts via flag (no wrapper)
echo '{"blocks":[{"type":"paragraph","text":"Hi \ud83d\ude80"}]}' \
  | pdfnative render --font latin --font emoji --lang latin,emoji -o out.pdf

pdfnative sign#

Applies a CMS/PKCS#7 digital signature to an existing PDF.

Native constant-time signing (v1.2.0). sign now routes CMS signing through Node's node:crypto by default (via createNativeCryptoProvider), for side-channel-resistant RSA/ECDSA. Pass --pure-crypto to select the portable pure-JS path (e.g. on a runtime without node:crypto).

PAdES B-T (v1.4.0). --timestamp <tsa-url> — previously a reserved flag that failed with E_UNSUPPORTED — is now functional: the CLI POSTs an RFC 3161 request through its SSRF guard, verifies the token, and embeds it in the CMS unsigned attributes via signPdfBytesWithTimestamp. Pair it with --profile pades: the default pkcs7 profile writes /SubFilter /adbe.pkcs7.detached, a valid CMS signature but not an ETSI EN 319 142-1 baseline. The typical ladder:

pdfnative sign --timestamp <tsa> --profile pades   # → B-T
pdfnative ltv add --online                         # → B-LT
pdfnative doc-timestamp --url <tsa>                # → B-LTA
pdfnative ltv add --online                         # LTV for the doc-timestamp itself

Continue with ltv (B-LT) and doc-timestamp (B-LTA) below.

Signing keys are never logged — not in error output, not in debug traces, not in stack traces. The CLI redacts them at every code path that surfaces error context. --signing-time is a deliberate legal instant and is not pinned by the global --creation-date (v1.5.0).

pdfnative inspect#

Inspects metadata and conformance of an existing PDF. Read-only — never modifies the input.

Composable example:

pdfnative inspect --input dist/q1.pdf \
  --check pdfa --check signed \
  --format json > dist/q1.report.json
echo "exit code: $?"   # 0 if both assertions hold

Behaviour change in v1.4.0: --check signed now counts only actual signatures — unsigned placeholders and /DocTimeStamp revisions no longer satisfy it. A placeholder-only PDF that passed under v1.3.0 fails under v1.4.0; this is a deliberate correctness fix. v1.4.0 also fixes the signatures and formFields counters in the JSON body, which previously always reported 0. Use --check "signatures>=1" together with --signatures when you need the structural inventory.

pdfnative verify#

Verifies CMS/PKCS#7 signatures embedded in a PDF.

Scope (since v1.0.0):

• ✅ Byte-range integrity (SHA-256 recomputed and compared with CMS messageDigest attribute)
• ✅ Signature value verification — RSA-SHA256, ECDSA-SHA256, and (v1.4.0) RSA-SHA384 / RSA-SHA512
• ✅ Certificate chain verification via pdfnative's verifyCertSignature
• ✅ Trust evaluation against --trust roots, with self-signed acceptance for testing
• ✅ RFC 3161 timestamp validation (PAdES-T) — TSA signature, messageImprint binding, chain, genTime
• ✅ OCSP (RFC 6960) + CRL (RFC 5280) revocation — embedded /DSS offline by default, opt-in SSRF-guarded online via AIA / CDP
• ✅ (v1.4.0) /DocTimeStamp revisions validated as RFC 3161 tokens; each signature in the report now carries fieldName and isDocTimestamp (additive fields, no new flags)
• ✅ (v1.5.0) Timestamp digest reporting — each timestamped signature carries timestampDigest (the RFC 3161 messageImprint algorithm, e.g. sha256). A SHA-1 imprint adds the note weak digest: RFC 3161 messageImprint uses SHA-1 (refused under --strict) and fails under --strict (E_VERIFY_FAILED)

Since v1.4.0 the CLI also creates LTV material — sign --timestamp (B-T), ltv (B-LT /DSS), and doc-timestamp (B-LTA) — so verify and the write side now cover the same PAdES ladder.

pdfnative ltv (v1.4.0)#

Embeds long-term-validation material — certificates, OCSP responses, CRLs — into a signed PDF's /DSS dictionary (PAdES B-LT), via the engine's collectValidationInfo / embedValidationInfo / addValidationInfo.

# Connected machine: gather the revocation evidence as replayable JSON
pdfnative ltv collect --input signed.pdf --online --output ltv-data.json

# Air-gapped machine: embed it — no network I/O is even possible here
pdfnative ltv embed --input signed.pdf --data ltv-data.json --output signed.lt.pdf

# Or both in one pass on a connected machine
pdfnative ltv add --input signed.pdf --online --output signed.lt.pdf

The evidence JSON (schema ltv-data, versioned, DER as base64) is the air-gap bridge: collect on a connected machine, transfer the JSON, embed inside the enclave. Network fetches go through the same SSRF guard as verify --revocation online; failures surface as E_NETWORK.

pdfnative doc-timestamp (v1.4.0)#

Appends an RFC 3161 document timestamp revision (/DocTimeStamp, /SubFilter /ETSI.RFC3161 — ISO 32000-2 §12.8.5) covering every byte of the document (PAdES B-LTA). Earlier revisions stay byte-identical; run it again years later to renew the protection before the TSA's certificate expires.

pdfnative doc-timestamp --input signed.lt.pdf \
  --url https://tsa.example.com/rfc3161 --output signed.lta.pdf

pdfnative merge (v1.2.0)#

Concatenates 2–50 PDFs into one document, in order, via mergePdfs.

pdfnative merge a.pdf b.pdf c.pdf --output combined.pdf

Encrypted sources are supported since v1.3.0 via --password (a single password applied to every source), and the output can be re-encrypted via --encrypt. Signatures and /AcroForm are dropped (page edits invalidate /ByteRange); self-contained URI /Link annotations are preserved. Every path — positionals included — is validated against traversal.

pdfnative split (v1.2.0)#

Splits one PDF into many via splitPdf — one output per page (default) or one per comma-separated range.

# One output per page
pdfnative split --input report.pdf --output-dir pages/ --prefix page

# One output per range (1-based, inclusive)
pdfnative split --input report.pdf --output-dir out/ --pages "1-2,3-4"

pdfnative extract (v1.2.0)#

Pulls a selected, order-preserving subset of pages into a single PDF via extractPages.

pdfnative extract --input report.pdf --output cover.pdf --pages "4,1-2"

pdfnative annotate (v1.2.0)#

Attaches markup annotations to an existing PDF via an incremental save, so the original bytes — and any existing signature — stay intact.

pdfnative annotate --input report.pdf --output annotated.pdf \
  --annotations notes.json

notes.json is a JSON array (or { "annotations": […] }), each entry a markup annotation plus a 1-based page:

[
  { "page": 1, "type": "highlight", "rect": [72, 700, 520, 715], "color": "#ffe066", "contents": "Review this clause" },
  { "page": 2, "type": "text", "rect": [80, 640, 100, 660], "contents": "Sticky note" }
]

Supported types: text, highlight, underline, strikeout, squiggly, square, circle, line, freetext, and (v1.5.0) link — { "page": 1, "type": "link", "rect": [72, 700, 300, 715], "url": "https://example.org" }, emitted as a /Link annotation with a /URI action; only http:, https: and mailto: URLs without control characters are accepted (E_INPUT otherwise). Colours accept CMYK since v1.5.0. Only known fields are forwarded (no dictionary injection). Read them back with inspect --annotations. Since v1.4.0, --password <pass> (env PDFNATIVE_PASSWORD) lets you annotate an encrypted PDF — the added objects are encrypted under the document's existing scheme.

Overlay, not redaction. Annotations are a visual review layer; the underlying bytes remain. They do not remove or obscure content for security purposes.

pdfnative metadata (v1.4.0)#

Updates /Info and XMP metadata via an incremental save — the original bytes are kept as a prefix, so existing signatures remain valid for their revision. xmp:ModifyDate and pdf:Keywords stay synchronised. Reading metadata remains inspect's job.

pdfnative metadata --input report.pdf --output revised.pdf \
  --title "Quarterly report (revised)" --keywords "finance,Q2"

pdfnative govern (v1.2.0)#

Surfaces pdfnative's AI-governance / Human-in-the-Loop (HITL) contract. Agents act as draftsmen: a human must always review and submit under their own GitHub identity.

pdfnative govern rules                  # human/agent protocol (AGENT_RULES)
pdfnative govern policy --json          # machine-readable policy JSON
pdfnative govern verify-issue draft.md  # gate a draft (exit 1 / E_POLICY)

verify-issue is a pure, fully offline validator — no GitHub or network access. A passing check is necessary but not sufficient: the human review gate always applies.

pdfnative fill (v1.3.0)#

Fill, flatten or export an AcroForm. The three modes compose into a round trip: export the current values, edit the JSON, feed it back.

pdfnative fill --input form.pdf --export --output values.json   # read
pdfnative fill --input form.pdf --data values.json --output filled.pdf
pdfnative fill --input filled.pdf --flatten --output flat.pdf   # freeze

Flattening a signed document invalidates the signature, which is why --force exists rather than it being silent.

pdfnative encrypt (v1.3.0)#

Re-secure an existing PDF. --owner-password is required; without a --user-password the document opens with no prompt and the owner password only governs permissions.

pdfnative encrypt --input report.pdf --output secure.pdf \
  --owner-password "$OWNER" --user-password "$USER" \
  --algorithm aes-256 --permissions print,extract

pdfnative decrypt (v1.3.0)#

Remove encryption, given the password. Reads RC4, AES-128 and AES-256 sources.

pdfnative decrypt --input secure.pdf --password "$PASS" --output plain.pdf

pdfnative extract-text (v1.3.0)#

Reading-order Unicode text from an existing PDF. ndjson emits one JSON object per page, which makes it a natural feed for a RAG ingestion pipeline.

pdfnative extract-text --input paper.pdf --format ndjson --runs > pages.ndjson
pdfnative extract-text --input paper.pdf --pages 1,3,5-7 --format text

Text comes from the /ToUnicode mapping, so it is real Unicode rather than glyph indices. A page whose content decodes entirely to U+FFFD is reported as not extractable rather than returning noise.

pdfnative compare (v1.4.0)#

Compares two PDFs by extracted text and by structure — page count, page/print boxes, metadata, form fields, annotations, encryption, signatures. Built for CI: identical documents exit 0; differences print the report on stdout first, then exit 1 with E_CHECK_FAILED.

pdfnative compare golden.pdf candidate.pdf --mode both --format json --pretty

Not a visual diff. pdfnative has no rasteriser, so pixel comparison is out of scope by design — compare diffs what the format itself declares (text and structure). Pair it with an external rasteriser if you need pixel-level checks.

pdfnative doctor (v1.3.0)#

Environment and capability preflight. The first thing to run in a new environment, and the first thing an agent should call before planning work.

pdfnative doctor              # human-readable
pdfnative doctor --format json --pretty

Since v1.5.0 the report also carries fonts (the bundled modules and scripts probed on disk), unicode (the Universal Shaping Engine's Unicode version) and conformance (pdfa1b,pdfa2b,pdfa2u,pdfa3b,pdfx4 — the --tagged / --pdfx targets). Fully offline.

pdfnative batch#

Renders every JSON file in a directory to PDF in parallel, reusing the full render pipeline.

pdfnative batch --input-dir inputs/ --output-dir outputs/ --tagged pdfa2b --concurrency 4

Manifest mode (v1.4.0)#

--manifest tasks.json runs a declarative pipeline — { "version": 1, "tasks": [{ "id", "command", "flags" }] } (schema batch-manifest). Flag names are written bare, without the leading dashes (a dashed key is rejected with exit 2). A flag value of "@<id>" references the output of an earlier task; relative paths resolve against the manifest's directory. The whole manifest is validated before anything runs, then executed sequentially and fail-fast (unless --continue-on-error).

{
  "version": 1,
  "tasks": [
    { "id": "report",  "command": "render", "flags": { "input": "report.json", "output": "report.pdf", "tagged": "pdfa2b" } },
    { "id": "stamped", "command": "metadata", "flags": { "input": "@report", "output": "final.pdf", "title": "Q2 report" } }
  ]
}

Only a fixed 14-command whitelist is allowed inside a manifest — render, sign, verify, inspect, merge, split, extract, extract-text, fill, encrypt, decrypt, annotate, metadata, doc-timestamp. ltv and compare are excluded (they take positionals, which manifest tasks — a flat flag map — cannot express), and the meta commands (batch, govern, schema, completion, doctor) can never nest. Manifests are capped at 1 000 tasks with the same path-traversal checks as direct flags. Error classes: a structural violation, an invalid flag name or value type, or a network-reaching flag without --allow-network exits 2/E_USAGE; an invalid or duplicate task id, a non-whitelisted command, or a broken @ref exits 1/E_INPUT; malformed JSON is 1/E_PARSE.

pdfnative schema#

Prints a versioned JSON Schema (Draft 2020-12) for a CLI input/output shape, so agents can self-validate before invoking a command. The $id embeds the CLI version.

pdfnative schema render            # input schema for `render`
pdfnative schema inspect-summary   # compact inspect verdict shape
pdfnative schema list              # enumerate every subject

Subjects (19): render, inspect, verify, batch, annotate (v1.2.0), govern-verify (v1.2.0), extract-text, fill, form-export, status, manifest, doctor (all v1.3.0), metadata, ltv-data, compare, batch-manifest (all v1.4.0), and the compact inspect-summary / verify-summary / batch-summary shapes. pdfnative schema list enumerates them all.

pdfnative completion#

Emits a shell-completion script: pdfnative completion bash|zsh|fish|powershell (PowerShell added in v1.3.0).

Agent-native automation contract#

v1.1.0 makes the CLI deterministic to drive from autonomous AI agents and CI pipelines. Since v1.5.0 the full consumer contract lives in pdfnative-cli docs/AGENT_CONTRACT.md (the repository's AGENTS.md now holds the rules for agents working on the CLI). Architecture-level compositions — reproducible builds, PDF/X-4 press handoff, house fonts, the process contract from any language — are on the CLI use cases page.

• Global --json envelope. Any command run with --json emits a single machine-readable object on stderr: { ok: false, command, error: { code, message } } on failure, and a { ok: true, … } status line for render / sign / batch on success (since v1.3.0, every write command emits the success line). stdout stays reserved for the primary artifact (PDF, report, schema, script).
• Stable E_* error codes on every failure: E_USAGE, E_INPUT, E_PARSE, E_IO, E_SIGN, E_VERIFY_FAILED, E_CHECK_FAILED, E_POLICY (v1.2.0 — governance-gate failure), E_UNSUPPORTED, E_PASSWORD (v1.3.0 — encrypted PDF: password missing or incorrect), E_NETWORK (v1.4.0 — an opt-in network operation failed: TSA / OCSP / CRL fetch), E_RUNTIME. Numeric exit codes (0/1/2) are unchanged.
• --dry-run for render, sign, batch, and — since v1.2.0 — merge, split, extract, and annotate (v1.3.0 extends it to fill, encrypt and decrypt; v1.4.0 to metadata, ltv and doc-timestamp) — fully validate inputs (and, for sign, parse credentials and prepare the PDF) without producing output. A dry run never touches the network.
• Global --max-inflate-size <bytes> (v1.4.0) caps the decompressed size of each PDF stream when parsing untrusted inputs (anti zip-bomb; default 100 MiB).
• Global --creation-date <iso8601> (v1.5.0 — the 10th global flag) pins the creation instant of every PDF written in the run (render, and every task of a batch): /CreationDate, xmp:CreateDate, the {date} placeholder and the trailer /ID derive from it, in UTC, so the same input renders to identical bytes on every host and timezone. Falls back to SOURCE_DATE_EPOCH (integer seconds); an invalid value is a usage error. The envelope carries creationDate. Encrypted output is never byte-reproducible; sign --signing-time and metadata --mod-date stay separate instants.
• Global flags may precede the command (v1.5.0) — pdfnative --json --dry-run render … is equivalent to pdfnative render … --json --dry-run. Arguments without any command now exit 2 (E_USAGE) instead of printing the usage with exit 0; a bare pdfnative still prints the usage.
• schema status pins every envelope field (v1.5.0) — 31 properties, the command-specific ones included; new in v1.5.0: pdfx, creationDate, timestamp.timeoutMs, and dryRun on every dry-run envelope. A parity test in the CLI repository holds the schema to every emitted field.
• Token-economy output projection (inspect / verify / batch / extract-text): stdout JSON is compact by default under --json (--pretty opts back into the human 2-space form), --summary emits a canonical minimal verdict, and --fields a,b.c projects the result to named dot-paths. Typically ~90 % fewer output tokens with no loss of the fields agents branch on. Non---json human output is unchanged.

# Agent-friendly: compact verdict on stdout, structured status on stderr
pdfnative inspect --input report.pdf --json --summary 2>status.json

# Branch on a stable error class
pdfnative verify --input report.pdf --json --strict \
  || echo "failed: $(jq -r .error.code status.json)"

Recipes#

Render → sign → verify → inspect, in a single chain#

cat report.json \
  | pdfnative render --tagged pdfa2b --compress \
  | pdfnative sign --reason "Approved" \
  | tee signed.pdf \
  | pdfnative verify --strict --trust ca.pem
pdfnative inspect --input signed.pdf --check pdfa --check signed

Encrypted PDF/A-3 hybrid invoice (Factur-X / ZUGFeRD)#

pdfnative render \
  --input invoice.json --output invoice.pdf \
  --tagged pdfa3b \
  --attachment factur-x.xml:application/xml:Source:"Structured invoice data" \
  --footer-center "Page {page} / {pages}"

Encrypted distribution copy#

pdfnative render \
  --input contract.json --output contract.encrypted.pdf \
  --encrypt-algorithm aes256 \
  --encrypt-permissions print
# PDFNATIVE_ENCRYPT_OWNER_PASS read from the env — never on the command line

Multilang fonts#

For the 27 bundled scripts (plus latin, emoji, color-emoji, math), no wrapper is needed — --font registers each bundled font inside the CLI process:

echo '{"blocks":[{"type":"paragraph","text":"สวัสดี こんにちは"}]}' \
  | pdfnative render --font th --font ja --lang th,ja -o out.pdf

For a font file you ship yourself, use --font-file (v1.5.0) — see House font + typography flags below. Only a custom loader (a font module registered programmatically) still requires the library: in-memory font registration does not cross a process boundary, so a wrapper that registers fonts and then spawns the CLI does not work. Call the library directly instead:

// render-custom-font.mjs
import { registerFont, loadFontData, buildDocumentPDFBytes } from 'pdfnative';
import { writeFile } from 'node:fs/promises';

registerFont('th', () => import('./fonts/my-thai-data.js'));
const th = await loadFontData('th');
if (!th) throw new Error('Thai font failed to load');
const bytes = buildDocumentPDFBytes({
  title: 'Thai demo',
  blocks: [{ type: 'paragraph', text: 'สวัสดี' }],
  fontEntries: [{ fontData: th, fontRef: '/F3', lang: 'th' }], // /F1 and /F2 are reserved
});
await writeFile('out.pdf', bytes);

CI assertion (GitHub Actions)#

- name: Render and assert PDF/A + signed
  run: |
    pdfnative render --input data/q1.json --output dist/q1.pdf --tagged pdfa2b
    pdfnative sign  --input dist/q1.pdf  --output dist/q1.signed.pdf
    pdfnative verify --input dist/q1.signed.pdf --strict
    pdfnative inspect --input dist/q1.signed.pdf --check pdfa --check signed

Batch-render a directory of JSON files#

for f in inputs/*.json; do
  pdfnative render --input "$f" --output "outputs/$(basename "$f" .json).pdf" --tagged pdfa2b
done

Byte-reproducible build (v1.5.0)#

Pin the creation instant and the same input renders to identical bytes on every host and timezone (not for encrypted output — CSPRNG keys):

pdfnative render --input doc.json --output a.pdf --creation-date 2026-01-01T00:00:00Z
TZ=Asia/Tokyo pdfnative render --input doc.json --output b.pdf --creation-date 2026-01-01T00:00:00Z
sha256sum a.pdf b.pdf                          # identical hashes

# Same thing from the environment (integer seconds), e.g. in a CI job
SOURCE_DATE_EPOCH=1767225600 pdfnative render --input doc.json --output c.pdf

PDF/X-4 press handoff (v1.5.0)#

pdfnative render --input brochure.json --output brochure.pdf \
  --pdfx pdfx4 --output-intent-icc press.icc --font latin --lang latin \
  --trapped false --strict
pdfnative inspect --input brochure.pdf --check pdfx     # exit 0 when the structural claim holds
pdfnative inspect --input brochure.pdf --json --pdfx --fields pdfx.valid,pdfx.errors

press.icc must be a printer (prtr) CMYK profile. Each page gets a TrimBox automatically (from layout.print, else the BleedBox or MediaBox) unless it sets an ArtBox — never both. --strict turns the PDFX_* diagnostics into E_CHECK_FAILED before any byte is written.

House font + typography flags (v1.5.0)#

pdfnative render --input report.json --output report.pdf \
  --font-file fonts/House-Regular.ttf:house --lang house \
  --split-paragraphs --keep-headings-with-next --kerning --font-features onum,smcp

The :house suffix names the font (default: the file stem) and doubles as its --lang code. Repeat --font-file for additional faces; a name that collides with a bundled shortcut is a usage error.

Architecture-level compositions: CLI use cases.

Security model#

pdfnative-cli is built with the same zero-trust posture as the underlying library:

• No eval, no Function, no dynamic code — input JSON is parsed via the standard JSON.parse with a 50 MB cap to prevent memory exhaustion.
• Path traversal protection — all --input / --output / --key / --cert / --cert-chain / --trust / --layout / --attachment / --watermark-image paths are validated against .. segments before any file system access.
• Secrets never logged — loadPem / loadPemChain surface only generic error messages on parse failure; raw key material never appears in CliError messages or stderr. Encryption passwords are never echoed.
• Layout-file injection blocked — attachments[].data fields embedded in --layout JSON are stripped on load. Binary attachment payloads must come from --attachment <path> so the CLI can apply path validation.
• Env-var precedence for secrets — PDFNATIVE_SIGN_KEY / PDFNATIVE_SIGN_CERT / PDFNATIVE_SIGN_CHAIN / PDFNATIVE_ENCRYPT_OWNER_PASS / PDFNATIVE_ENCRYPT_USER_PASS are preferred over file-path flags so secrets never enter shell history.
• Stdin/stdout safe — binary streams are passed through without interpretation; no shell-quoting issues.
• Zip-bomb cap (v1.4.0) — the global --max-inflate-size bounds the decompressed size of every PDF stream (default 100 MiB).
• NPM provenance — every published version is signed via GitHub Actions OIDC. Verify with npm audit signatures.

The CLI opens no network connection unless you explicitly opt in — the only network paths are verify --revocation online, sign --timestamp <url>, ltv --online, doc-timestamp --url <url>, and batch --allow-network, and all of them go through the same SSRF guard: http/https only, private / loopback / metadata addresses blocked, DNS pinning, 10 s timeout, 5 MiB response cap, no redirects. Response bodies are never echoed into CLI output. It never writes to system directories outside the working directory or loads arbitrary code.

Comparison with the library API#

The CLI now covers nearly the full library surface; only Web Worker offloading remains library-only.

Examples — ready-to-run#

The samples/ directory in the CLI repository ships 40+ ready-to-run examples organized by feature:

Render them all at once (since v1.5.0 the sample generator drives the built binary under a pinned date, replacing the former samples/run-all.js):

git clone https://github.com/Nizoka/pdfnative-cli
cd pdfnative-cli
npm ci && npm run build && npm run test:generate

Release history#

What's new in v1.5.0#

v1.5.0 is built on pdfnative 1.8.0 (pin ^1.8.0) and exposes every 1.8.0 engine feature — the typography engine, CMYK colours and colour bars, PDF/X-4 output with a structural validator, five more scripts (27 in all) with latin aliases, custom fonts from disk, and UTC, pinnable creation dates that make output byte-reproducible — plus the roadmap items the engine unblocked. 21 commands, 19 schema subjects and 12 stable error codes are unchanged; the global flag count grows to 10 (--creation-date). 100 % backward-compatible command surface — every envelope field is additive — but the bytes differ from v1.4.0 output (see Compatibility).

Full changelog: pdfnative-cli release notes v1.5.0.

What's new in v1.4.0#

v1.4.0 requires pdfnative ≥ 1.7.0 (pin ^1.7.0) and completes the signature story: the full PAdES ladder (B-B → B-T → B-LT → B-LTA) is now writable from the command line, alongside signature-safe metadata edits, a CI-grade document diff, and a declarative batch pipeline. No contract change — every flag, default, exit code, error code and envelope from 1.x behaves identically on Node ≥ 22.

Full changelog: pdfnative-cli release notes v1.4.0.

What's new in v1.3.0#

v1.3.0 is built on the pdfnative 1.6 engine (pin ^1.6.0) and surfaces its engine additions as five new commands (extract-text, fill, encrypt, decrypt, doctor), native vector charts in render, and password / re-encryption / constant-memory streaming on the page-tree commands. Fixes a silent render --encrypt no-op. 100 % backward-compatible with v1.2.0.

Full changelog: pdfnative-cli release notes v1.3.0.

What's new in v1.2.0#

v1.2.0 lands the pdfnative 1.5.0 engine's page-tree and annotation APIs on the CLI as five new commands, adds document bookmarks, a math font, layout introspection, native constant-time signing, and — for autonomous agents — surfaces pdfnative's AI-governance / Human-in-the-Loop (HITL) contract. 100 % backward-compatible with v1.1.0.

Full changelog: pdfnative-cli release notes v1.2.0.

Previously in v1.1.0#

v1.1.0 is built on pdfnative 1.3.0 and surfaces its new engine capabilities through the CLI, plus a full agent-native automation contract. 100 % backward-compatible with v0.3.0.

Full changelog: pdfnative-cli release notes v1.1.0.

Previously in v0.3.0#

v0.3.0 finished the digital-signature story and added three iteration-friendly render flags. 100 % backward-compatible with v0.2.0.

Previously in v0.2.0#

The v0.2.0 release expanded the CLI from ~10 flags to a near-complete projection of the pdfnative v1.0.5 surface, while remaining 100 % backward-compatible with v0.1.0.

Migration v1.4.0 → v1.5.0#

100 % backward-compatible command surface — no flag, default, exit code or error code changed. The bytes changed with the pdfnative 1.8.0 engine (UTC dates, hinting tables kept in TrueType subsets, corrected Thai and Lao mark ordering), so hash-based consumers rebaseline once and then pin the date:

# 1. Reproducible bytes: rebaseline once, then pin the creation instant (or SOURCE_DATE_EPOCH)
- pdfnative render --input doc.json --output doc.pdf
+ pdfnative render --input doc.json --output doc.pdf --creation-date 2026-01-01T00:00:00Z

# 2. formField blocks: the engine's six types only — unknown values are now E_INPUT
-   { "type": "formField", "fieldType": "textarea", "name": "notes" }
+   { "type": "formField", "fieldType": "multilineText", "name": "notes" }
-   { "type": "formField", "fieldType": "select", "name": "country" }
+   { "type": "formField", "fieldType": "dropdown", "name": "country" }

# 3. Global flags may now precede the command (both forms are equivalent)
  pdfnative render --input doc.json --output doc.pdf --json --dry-run
+ pdfnative --json --dry-run render --input doc.json --output doc.pdf

# 4. A font file of your own, no wrapper script
+ pdfnative render --input doc.json --output doc.pdf --font-file fonts/House.ttf:house --lang house

# 5. PDF/X-4 for print, re-checked structurally
+ pdfnative render --input brochure.json --output brochure.pdf --pdfx pdfx4 --output-intent-icc press.icc --trapped false --strict
+ pdfnative inspect --input brochure.pdf --check pdfx

samples/run-all.js no longer exists in the CLI repository — npm run build && npm run test:generate replaces it.

Migration v0.3.0 → v1.1.0#

100 % backward-compatible. Every v0.3.0 invocation continues to produce a byte-equivalent PDF. New, optional opportunities:

# 1. True constant-memory streaming for very large reports
- pdfnative render --input big.json --output big.pdf --stream
+ pdfnative render --input big.json --output big.pdf --stream-true

# 2. CI accessibility gate (PDF/UA)
+ pdfnative inspect --input report.pdf --check pdfua

# 3. Agent-native, token-frugal output
+ pdfnative inspect --input report.pdf --json --summary

# 4. Parallel directory render
+ pdfnative batch --input-dir inputs/ --output-dir outputs/ --concurrency 4

Migration v0.2.0 → v0.3.0#

100 % backward-compatible. Three forward-looking opportunities:

# 1. ECDSA signing now works without a workaround
- pdfnative sign -i in.pdf -o out.pdf --algorithm rsa-sha256 ...
+ pdfnative sign -i in.pdf -o out.pdf --algorithm ecdsa-sha256 \
+   --key ec-key.pem --cert ec-cert.pem

# 2. Sign without a prior placeholder step
- pdfnative sign -i with-placeholder.pdf -o signed.pdf ...
+ pdfnative sign -i any-pdf.pdf -o signed.pdf ...   # placeholder auto-injected

Migration v0.1.0 → v0.2.0#

100 % backward-compatible — every v0.1.0 invocation continues to produce a byte-equivalent PDF, modulo a one-line stderr notice for --conformance. All v0.1.0 exit codes and JSON shapes are preserved; new inspect JSON fields are additive only.

The only soft change you should plan for:

- pdfnative render --input doc.json --output report.pdf --conformance 2b
+ pdfnative render --input doc.json --output report.pdf --tagged pdfa2b

--conformance will be removed in v1.0.0 of the CLI.

Troubleshooting#

command not found: pdfnative#

You installed via npx (one-shot) and not globally. Either prepend npx to every invocation, or run npm install --global pdfnative-cli.

JSON parse error: input too large#

The CLI caps input JSON at 50 MB to prevent memory exhaustion. For very large documents, either split the document into multiple PDFs or use the library directly with the streaming API.

Error: invalid private key#

Both RSA PKCS#1 and ECDSA P-256 keys are accepted, but they must be PEM-encoded. Convert DER to PEM with openssl pkcs8 -topk8 -in key.der -out key.pem -nocrypt. As of v0.3.0, ECDSA support in sign is fully wired (SEC1 / PKCS#8 P-256 via parseEcPrivateKey).

Encryption requires an owner password. Provide --owner-password <pass> or $PDFNATIVE_ENCRYPT_OWNER_PASS.#

Any encryption flag was set without an owner password. Provide it via --owner-password <pass> (legacy alias: --encrypt-owner-pass) or — recommended — the PDFNATIVE_ENCRYPT_OWNER_PASS env var so it never enters shell history.

Error: --tagged pdfa* and --encrypt-* are mutually exclusive#

ISO 19005-1 §6.3.2 forbids encryption in PDF/A. Pick one — either an archival PDF/A document, or an encrypted distribution copy, but not both.

E_NETWORK: opt-in network operation failed#

A TSA / OCSP / CRL fetch (sign --timestamp, ltv --online, doc-timestamp, verify --revocation online) failed at the transport level. The SSRF guard allows http/https only, blocks private / loopback / metadata addresses, follows no redirects, and enforces a 10 s timeout and a 5 MiB response cap — check the URL is public and reachable, or raise --timeout where the command exposes it (ltv, doc-timestamp; sign --timestamp-timeout <ms> since v1.5.0). Since v1.5.0 the guard also refuses 198.18.0.0/15, 192.0.2.0/24 and 64:ff9b::/96. A malformed TSA response is E_PARSE instead. There is never a silent fallback: either the token is embedded and verified, or the command fails.

E_PARSE on a PDF that other tools open#

If the message mentions an inflate cap, one of the PDF's compressed streams expands past the anti-zip-bomb ceiling (default 100 MiB). For a trusted file, raise it with the global --max-inflate-size <bytes> (v1.4.0).

ENOENT: no such file or directory, 'D\' (Windows)#

This was a v0.1.0 / pre-v0.2.0 regression: --attachment D:\file.xml was split at the drive-letter colon. Fixed in v0.2.0 — make sure you're on pdfnative-cli@^0.2.0.

Layout file is ignored when I also pass CLI flags#

That is the intended precedence: CLI flags > --layout file > pdfnative defaults. To merge nested objects (e.g. a watermark in the layout file plus a --watermark-text on the CLI), the CLI now correctly merges params.layout with CLI-derived flags as of v0.2.0 (previously the JSON-embedded layout could be silently dropped — fixed).

--lang th does not produce Thai glyphs#

--lang only activates fonts that are registered in the CLI process — pass --font th as well so the bundled Noto Thai module is registered (--font covers all 27 bundled scripts, latin, emoji, color-emoji, math). A wrapper script that registers fonts and then spawns the CLI does not work: in-memory registration does not cross a process boundary. For a font file you ship yourself, use --font-file <path.ttf>[:name] (v1.5.0); for a custom loader, call the library directly — see Recipes → Multilang fonts.

Signed PDF fails Adobe verification#

Ensure your certificate's signing-key usage extension includes digitalSignature (key usage 0). Self-signed certificates work for testing but require the validator to trust the issuer — pass --trust ca-root.pem to verify for self-signed setups.

Resources#

• 📦 npm: pdfnative-cli
• 🏛️ Repo: Nizoka/pdfnative-cli
• 📚 Knowledge base: pdfnative-cli/docs/KNOWLEDGE_BASE.md — full architecture, integration patterns, FAQ
• 📁 Samples: pdfnative-cli/samples
• 🧪 Try it interactively: CLI playground — build commands without leaving the browser
• 📐 Use cases: CLI use cases — reproducible builds, PDF/X-4 press handoff, house fonts, the process contract for any-language orchestrators
• 🤝 Agent contract: pdfnative-cli/docs/AGENT_CONTRACT.md — --json envelope, E_* codes, schema status, the recommended agent loop
• 🔧 Underlying library: pdfnative
• 🤖 AI integration: pdfnative-mcp guide — same library exposed as a Model Context Protocol server
• 🐛 Report a bug: Nizoka/pdfnative-cli/issues
• 💬 Discuss: Nizoka/pdfnative-cli/discussions

Citation#

If you use the CLI in research or academic pipelines, cite both repositories:

@software{pdfnative_cli_2026,
  title  = {pdfnative-cli: Official CLI for the pdfnative PDF generation library},
  author = {Nizoka},
  year   = {2026},
  url    = {https://github.com/Nizoka/pdfnative-cli},
  license = {MIT}
}