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 v0.2.0 — full coverage of the pdfnative v1.0.5 surface: encryption, watermarks, headers/footers with placeholders, PDF/A-3 attachments, multilingual fonts, table-variant rendering, signing metadata + cert chains, inspect --verbose / --pages / --check, and a brand-new verify command. 100 % backward-compatible with v0.1.0 — see release notes.

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 (new in v0.2.0) — verify integrity, certificate chains, and trust roots of every CMS/PKCS#7 signature embedded in a PDF. JSON & text output, --strict mode.
• Zero extra dependencies — pdfnative is the sole runtime dependency.
• 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 (v0.2.0)	✅	Integrity + chain + trust; --strict, --trust
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	⚠️	--algorithm ecdsa-sha256 parsed; stub error pending pdfnative parseEcPrivateKey (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
Certificate chain verification	✅	Via pdfnative verifyCertSignature
Trust roots	✅	--trust <root.pem> (repeatable) + self-signed acceptance
Full CMS signature-value	⚠️	Deferred to v0.3.0 (pending pdfnative API)
OCSP / CRL revocation	⚠️	Deferred to v0.3.0+
RFC 3161 timestamps	⚠️	Deferred to v0.3.0+

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 (new in v0.2.0)

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)

Scope (v0.2.0): integrity (byte-range SHA-256) + certificate chain signatures + trust evaluation. Full CMS-signature-value verification, OCSP/CRL revocation, and RFC 3161 timestamp validation are deferred — see ROADMAP.md.

Security

• 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.