pdfnative-cli

pdfnative-cli

Official CLI for the pdfnative library — render JSON to PDF, apply digital signatures, verify them, and inspect PDF conformance, directly from the terminal. Zero extra runtime dependencies.

What's new in v1.0.0 — Long-Term Validation (LTV) on the verify side: full RFC 3161 timestamp-token validation (PAdES-T), plus OCSP (RFC 6960) and CRL (RFC 5280) revocation checking — offline from the embedded /DSS by default, with opt-in, SSRF-guarded online fetching (verify --revocation online). render exposes pdfnative 1.2.0 smart tables (--table-wrap, --repeat-header, --zebra, --cell-padding, --min-row-height) and page-by-page streaming (--stream-page-by-page, TOC-compatible). New batch and completion commands, a .pdfnativerc.json config file, and global --quiet / --no-color / --version --json flags. Built on pdfnative 1.2.0, dropping the last two upstream workarounds. See release notes.

⭐ Star pdfnative — the zero-dependency PDF engine that powers this CLI.

Highlights

• render — pipe a JSON document into a production-ready PDF. Encryption (AES-128/256), watermarks (text + image), page templates, PDF/A archival, multilingual fonts, streaming, and a hybrid flags + --layout file.json model for the full PdfLayoutOptions surface.
• sign — CMS/PKCS#7 digital signatures with full metadata (--reason, --name, --location, --contact, --signing-time) and intermediate CA chains via --cert-chain (repeatable). Keys loaded from env vars or files; never logged.
• inspect — PDF version, page count, encryption, PDF/A conformance, signature count, metadata. --verbose, --pages, and --check pdfa|signed|encrypted for CI assertions.
• verify — verify every CMS/PKCS#7 signature: byte-range integrity, RSA/ECDSA signature value, certificate chain, trust roots, RFC 3161 timestamp (PAdES-T), and OCSP + CRL revocation (embedded /DSS offline by default, opt-in SSRF-guarded online). JSON & text output, --strict, --revocation, --revocation-policy.
• batch — render every JSON file in a directory to PDF in parallel, reusing the full render pipeline, with a per-file summary and bounded --concurrency.
• completion — emit bash, zsh, or fish shell-completion scripts.
• .pdfnativerc.json — optional config file for default flags (global + per-command); precedence is CLI flags > env > config.
• Zero extra dependencies — pdfnative is the sole runtime dependency.
• Offline by default — no network access unless you explicitly opt in with verify --revocation online, and even then every request passes an SSRF guard.
• Stdin / stdout by default — every command is shell-pipeline friendly.
• Secret-safe — signing keys, certs, encryption passwords never appear in error output or stderr. PEM material redacted; layout-file attachments[].data injection blocked.
• ESM-first, TypeScript strict — built with tsup, typed declarations included.
• NPM provenance — signed builds via GitHub Actions OIDC.

Supported Features

Feature	Status	Notes
Commands
render JSON → PDF	✅	Streaming, hybrid layout model, multilingual fonts
sign digital signatures	✅	RSA (CMS/PKCS#7), metadata fields, cert chains
inspect PDF metadata	✅	--verbose, --pages, --check pdfa|signed|encrypted
verify signature verification	✅	Integrity + chain + trust + timestamp + revocation; --strict
batch parallel rendering	✅	Directory → PDFs, --concurrency, --fail-fast
completion shell scripts	✅	bash / zsh / fish
.pdfnativerc.json config file	✅	Global + per-command defaults; flags > env > config
Document Blocks
Headings, paragraphs, lists	✅	Full text styling support
Tables	✅	Headers, rows, multi-page
Barcodes	✅	QR, Code 128, EAN-13, Data Matrix, PDF417
Hyperlinks	✅	URL validation, blue underlined text
Form fields	✅	Text, checkbox, radio, dropdown, listbox
Page breaks, spacers	✅	Explicit pagination control
Table of contents	✅	Auto-generated with /GoTo links
Advanced Layouts (v0.2.0)
PDF/A archival (1b, 2b, 2u, 3b)	✅	--tagged pdfa<level> (preferred) or --conformance (deprecated)
Streaming output	✅	--stream for large documents
Compression	✅	--compress flag
Encryption (AES-128/256)	✅	--encrypt-* flags + env-var precedence
Watermarks (text + image)	✅	--watermark-text, --watermark-image, --watermark-position
Headers / footers with placeholders	✅	--header-{l,c,r}, --footer-{l,c,r}, {page}/{pages}/{date}/{title}
Custom page sizes	✅	--page-size A4|Letter|… or WxH in points
Custom margins	✅	--margin <N> or --margin <t,r,b,l>
PDF/A-3 attachments	✅	--attachment <path>:<mime>:<rel>:<desc> (repeatable)
Multilingual fonts	✅	--lang th,ja,ar (requires registerFontLoader() in wrapper; Latin built-in)
Table-centric variant (PdfParams)	✅	--variant table
Full PdfLayoutOptions	✅	--layout <file.json>
Signing (v0.2.0)
RSA signatures (rsa-sha256)	✅	Default algorithm
ECDSA signatures (ecdsa-sha256)	✅	P-256 SEC1 / PKCS#8 keys (v0.3.0)
Auto signature-placeholder injection	✅	One-command sign of any rendered PDF (v0.3.0)
Signature metadata	✅	--reason, --name, --location, --contact, --signing-time
Cert chains (intermediate CAs)	✅	--cert-chain <pem> (repeatable) or PDFNATIVE_SIGN_CHAIN env
Verification (v0.2.0+)
Byte-range integrity (SHA-256)	✅	Recomputed and compared with CMS messageDigest attribute
CMS signature-value verification	✅	RSA-SHA256 + ECDSA-SHA256 (v0.3.0)
Certificate chain verification	✅	Via pdfnative verifyCertSignature
Trust roots	✅	--trust <root.pem> (repeatable) + self-signed acceptance
RFC 3161 timestamp recognition	✅	Reported as timestampPresent
RFC 3161 timestamp validation (PAdES-T)	✅	TSA signature, messageImprint binding, chain, genTime
OCSP revocation (RFC 6960)	✅	Embedded /DSS + opt-in online via AIA (SSRF-guarded)
CRL revocation (RFC 5280)	✅	Embedded /DSS + opt-in online via CDP (SSRF-guarded)
Revocation policy	✅	--revocation offline|online|disabled, --revocation-policy soft-fail|strict
Sign-side LTV (timestamp embedding / DSS)	⚠️	Upstream-blocked in pdfnative; sign --timestamp reserved
Render iteration
Smart tables	✅	--table-wrap, --repeat-header, --zebra, --cell-padding, --min-row-height
Page-by-page streaming	✅	--stream-page-by-page (TOC- and {pages}-compatible)
--watch re-render on file change	✅	200 ms debounce, requires file --output
--template <file.json>	✅	Deep-merge base under input (caller wins)
--font latin|emoji shortcuts	✅	Repeatable, allow-list bundled font names

Note: features marked ⚠️ are tracked in ROADMAP.md. Everything else works today.

Installation

npm install --global pdfnative-cli

Or run without installing:

npx pdfnative-cli render --input doc.json --output report.pdf

Requirements: Node.js ≥ 20 | Bun | Deno (node dist/cli.cjs)

Documentation

• 📘 Quick Start (below) — Get rendering in 5 minutes
• 🏛️ KNOWLEDGE_BASE.md — Full CLI reference, architecture, integration patterns
• 📚 samples/README.md — 22 sample files organized by feature
• 🔧 pdfnative library — Underlying PDF engine docs
• ❓ FAQ — Common questions & troubleshooting

Quick Start

Render a PDF from JSON

# From a file
pdfnative render --input document.json --output report.pdf

# From stdin
cat document.json | pdfnative render --output report.pdf

# Streaming (large documents)
pdfnative render --input big-doc.json --output report.pdf --stream

# PDF/A conformance
pdfnative render --input document.json --output archived.pdf --conformance 2b

document.json is a DocumentParams object:

{
  "title": "Monthly Report",
  "blocks": [
    { "type": "heading", "text": "Monthly Report", "level": 1 },
    { "type": "paragraph", "text": "Summary for April 2026." },
    { "type": "list", "style": "bullet", "items": ["Revenue: +18%", "NPS: 72"] }
  ],
  "footerText": "Confidential",
  "metadata": { "author": "Finance Team", "subject": "April 2026 Report" }
}

Sign a PDF

# Keys from environment variables (recommended for CI/CD)
export PDFNATIVE_SIGN_KEY="$(cat private.pem)"
export PDFNATIVE_SIGN_CERT="$(cat cert.pem)"
pdfnative sign --input document.pdf --output signed.pdf

# Keys from files
pdfnative sign --input document.pdf --output signed.pdf \
  --key private.pem --cert cert.pem

Inspect a PDF

# JSON output (default)
pdfnative inspect --input report.pdf

# Human-readable
pdfnative inspect --input report.pdf --format text

# From stdin
cat report.pdf | pdfnative inspect

Example output:

{
  "version": "1.7",
  "pageCount": 3,
  "encrypted": false,
  "pdfaConformance": "2b",
  "signatures": 1,
  "metadata": {
    "title": "Monthly Report",
    "author": "Nizoka",
    "creationDate": "2026-04-27T12:00:00+00:00"
  }
}

Examples

Ready-to-run examples are in samples/, organized by feature category:

Category	Examples	Description
render/document/	5 files	Minimal, report, all-blocks reference, invoice, technical spec
render/table/	2 files	Project status, financial summary
render/barcode/	3 files	QR code, Code 128 shipping label, EAN-13 product
render/form/	2 files	Contact form, survey
render/toc/	1 file	Document with auto-generated table of contents
render/link/	1 file	Resource directory with hyperlinks
render/watermark/	2 files	Draft watermark, confidential watermark
render/layout/	3 files	US Letter, A5 portrait, A4 landscape
render/pdfa/	3 files	PDF/A-1b, PDF/A-2b, PDF/A-3b archival conformance
sign/	2 scripts	Digital signature (Bash + PowerShell)
inspect/	4 scripts	JSON & text inspection (Bash + PowerShell)
streaming/	1 script	200-section document via streaming render

Render all samples at once:

node samples/run-all.js

See samples/README.md for full descriptions, block type reference, and integration patterns (GitHub Actions, Docker, TypeScript).

Command Reference

pdfnative render

Flag	Default	Description
--input <file>	stdin	Path to a JSON file (DocumentParams or PdfParams if --variant table)
--output <file>	stdout	Output PDF path
--stream	false	Use streaming output (AsyncGenerator)
--variant <kind>	document	document (default) or table (selects buildPDFBytes)
--layout <file.json>	—	Load a Partial<PdfLayoutOptions> (CLI flags override)
--page-size <size>	from layout file or pdfnative default	Named (a4, letter, legal, a3, tabloid, a5) or WxH in points
--margin <N> or --margin <t,r,b,l>	from layout / default	Page margins in points
--compress	false	Enable FlateDecode compression
--tagged <level>	none	PDF/A: none, pdfa1b, pdfa2b, pdfa2u, pdfa3b
--conformance <1b|2b|3b>	—	Deprecated — use --tagged pdfa<level>
--watermark-text <s> / --watermark-image <path>	—	Text or image watermark
--watermark-opacity <0-1> / --angle <deg> / --color <#hex> / --font-size <pt>	—	Watermark styling
--watermark-position background|foreground	background	Render order
--header-{left,center,right} <tpl>	—	Header template; placeholders {page}, {pages}, {date}, {title}
--footer-{left,center,right} <tpl>	—	Footer template; same placeholders
--encrypt-owner-pass <s>	$PDFNATIVE_ENCRYPT_OWNER_PASS	Owner password (required for any --encrypt-*)
--encrypt-user-pass <s>	$PDFNATIVE_ENCRYPT_USER_PASS	Optional user password
--encrypt-algorithm aes128|aes256	aes128	Encryption algorithm
--encrypt-permissions <list>	all denied	Comma list: print,copy,modify,extractText
--attachment <path>[:mime[:rel[:desc]]] (repeatable)	—	PDF/A-3 file attachment
--lang <code,code>	—	Activate registered font loaders for non-Latin scripts (th, ja, ar, …); Latin is built-in

See samples/render/ for a working example of every category.

pdfnative sign

Flag	Default	Description
--input <file>	— (required)	Path to the input PDF
--output <file>	stdout	Output signed PDF path
--key <file>	$PDFNATIVE_SIGN_KEY	Path to PEM private key (env var takes precedence)
--cert <file>	$PDFNATIVE_SIGN_CERT	Path to PEM certificate (env var takes precedence)
--cert-chain <file> (repeatable)	$PDFNATIVE_SIGN_CHAIN	Intermediate CA PEMs
--algorithm rsa-sha256|ecdsa-sha256	rsa-sha256	Signature algorithm. ECDSA stubbed in v0.2.0; tracked for v0.3.0.
--reason <s>	—	Reason for signing (PDF metadata)
--name <s>	—	Signer name (PDF metadata)
--location <s>	—	Signing location (PDF metadata)
--contact <s>	—	Signer contact (PDF metadata)
--signing-time <ISO 8601>	now	Explicit signing timestamp

pdfnative inspect

Flag	Default	Description
--input <file>	stdin	Path to the PDF to inspect
--output <file>	stdout	Output report path
--format json|text	json	Output format
--verbose	false	Add trailer keys, catalog keys, object count, XMP
--pages	false	Add per-page metadata array
--check pdfa|signed|encrypted (repeatable)	—	CI-friendly assertion; sets exit code (0 = pass, 1 = fail)

pdfnative verify

Flag	Default	Description
--input <file>	stdin	Path to the (possibly signed) PDF
--format json|text	json	Output format
--strict	false	Exit 1 on any failure or zero signatures (CI-friendly)
--trust <root.pem> (repeatable)	self-signed only	Trusted root certificates (PEM)
--revocation offline|online|disabled	offline	Revocation source: embedded /DSS only, also fetch online (SSRF-guarded), or skip
--revocation-policy soft-fail|strict	soft-fail	strict fails the signature on any non-good status; soft-fail only fails on explicit revoked

Scope (v1.0.0): byte-range integrity (SHA-256), full CMS signature value (RSA-PKCS#1 v1.5 SHA-256 + ECDSA-SHA256 over P-256), certificate chain + trust, RFC 3161 timestamp validation (PAdES-T), and OCSP (RFC 6960) + CRL (RFC 5280) revocation — embedded from the PDF /DSS offline by default, with opt-in online fetching through an SSRF-guarded HTTP client. Sign-side LTV (embedding timestamps / DSS at signing time) is upstream-blocked in pdfnative — see ROADMAP.md and SECURITY.md.

pdfnative batch

Flag	Default	Description
--input-dir <dir>	required	Directory of *.json document definitions
--output-dir <dir>	required	Output directory for the rendered *.pdf (created if absent)
--concurrency <n>	4	Maximum parallel renders
--fail-fast	false	Stop at the first failure (default: render all, then report)
--format json|text	text	Summary format

All other flags are forwarded to each render. Exit code 1 if any file fails.

pdfnative completion

pdfnative completion bash > /etc/bash_completion.d/pdfnative
pdfnative completion zsh  > "${fpath[1]}/_pdfnative"
pdfnative completion fish > ~/.config/fish/completions/pdfnative.fish

Global options

Flag	Description
--config <file>	Use a specific .pdfnativerc.json (default: nearest upward from cwd)
--no-config	Ignore any .pdfnativerc.json
--quiet, -q	Suppress progress output on stderr
--no-color	Disable ANSI colour (also respects the NO_COLOR env var)
--version --json	Machine-readable version output

Security

• Offline by default — no network access unless you pass verify --revocation online. Online revocation requests pass an SSRF guard (scheme allow-list, private/loopback/ link-local/CGNAT address blocking, no redirects, timeout + size caps).
• Signing keys are never logged — not in error messages, not in debug output.
• Path traversal protection — all file path arguments are validated against ../ sequences.
• JSON size cap — input is capped at 50 MB before parsing to prevent memory exhaustion.
• Signed builds with NPM provenance — verify at npmjs.com or with npm audit signatures.

See SECURITY.md for the full security policy and vulnerability disclosure procedure.

Getting Help

Have a question?

• 📖 Check the FAQ first
• 🔍 Search the samples: grep -r "your-keyword" samples/
• 📚 Read KNOWLEDGE_BASE.md for technical details
• 💬 Open a discussion: GitHub Discussions

Found a bug?

• 🐛 Open an issue: GitHub Issues
• 🔐 Security issue? See SECURITY.md for responsible disclosure

Want to contribute?

• 🤝 See CONTRIBUTING.md
• 📝 All PRs add value — tests, docs, translations, samples

Related Projects

• pdfnative — the core PDF generation library
• pdfnative-mcp — Model Context Protocol server for AI clients
• pdfnative.dev — documentation, live demos, benchmarks

Citation

If you use pdfnative-cli in research or academic pipelines, please cite it:

@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}
}

See CITATION.cff for the full metadata (auto-detected by GitHub and Zenodo).

License

MIT — see LICENSE.