pdfnative-cli

pdfnative-cli

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

Highlights

• render — pipe a JSON document definition into a production-ready PDF (streaming supported)
• sign — apply RSA or ECDSA digital signatures (CMS/PKCS#7) using key files or environment variables
• inspect — analyse any PDF: version, page count, encryption, PDF/A conformance, signature count, metadata
• Zero extra dependencies — pdfnative is the only runtime dependency; all PDF logic lives there
• Streaming output — --stream on render emits PDF chunks progressively for large documents
• Stdin / stdout — every command reads from stdin and writes to stdout by default, composable in shell pipelines
• Secret-safe — signing keys are loaded from env vars (PDFNATIVE_SIGN_KEY/PDFNATIVE_SIGN_CERT) and never logged
• 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, PDF/A conformance, stdin/stdout
sign digital signatures	✅	RSA + ECDSA, CMS/PKCS#7, env var secrets
inspect PDF metadata	✅	Version, pages, encryption, signatures, PDFA
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
PDF/A archival (1b, 2b, 3b)	✅	--conformance flag
Streaming output	✅	--stream for large documents
Compression	✅	Via pdfnative API (50–90% reduction)
Encryption (AES-128/256)	⚠️	Not exposed via CLI; use Node.js API
Watermarks	⚠️	Not exposed via CLI; use Node.js API
Custom headers/footers	⚠️	Not exposed via CLI; use footerText property
Custom page sizes	⚠️	Not exposed via CLI; use Node.js API

Note: Features marked ⚠️ are supported by pdfnative but not yet exposed through the CLI JSON interface. Use the pdfnative Node.js library directly for these features.

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 containing DocumentParams
--output <file>	stdout	Output PDF path
--stream	false	Use streaming output (AsyncGenerator)
--conformance <level>	—	PDF/A conformance level: 1b, 2b, or 3b

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 env	Path to PEM private key (env var takes precedence)
--cert <file>	PDFNATIVE_SIGN_CERT env	Path to PEM certificate (env var takes precedence)

pdfnative inspect

Flag	Default	Description
--input <file>	stdin	Path to the PDF to inspect
--format <fmt>	json	Output format: json or text

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.