🚀 Socket Launch Week Day 5:Introducing Repository Access Permissions and Custom Roles.Learn more →
pdfnative-cli
Advanced tools
pdfnative-cli - npm Package Compare versions
+29
-4
| { | ||
| "name": "pdfnative-cli", | ||
| "version": "1.0.0", | ||
| "description": "Official CLI for pdfnative — render JSON to PDF, sign (RSA + ECDSA), inspect, and verify CMS signatures with LTV (RFC 3161 timestamps, OCSP, CRL). Zero extra runtime dependencies.", | ||
| "version": "1.1.0", | ||
| "description": "Official CLI for pdfnative — render JSON to PDF (22 Unicode scripts, COLRv1 colour emoji, true constant-memory streaming), sign (RSA + ECDSA), inspect, validate PDF/UA, and verify CMS signatures with LTV (RFC 3161 timestamps, OCSP, CRL). Zero extra runtime dependencies.", | ||
| "type": "module", | ||
@@ -54,3 +54,25 @@ "bin": { | ||
| "shell-completions", | ||
| "command-line" | ||
| "command-line", | ||
| "pdf-ua", | ||
| "accessibility", | ||
| "colr", | ||
| "color-emoji", | ||
| "unicode", | ||
| "text-shaping", | ||
| "opentype", | ||
| "bidi", | ||
| "streaming", | ||
| "telugu", | ||
| "sinhala", | ||
| "khmer", | ||
| "myanmar", | ||
| "tibetan", | ||
| "amharic", | ||
| "ai-agent", | ||
| "agentic", | ||
| "automation", | ||
| "json-output", | ||
| "json-schema", | ||
| "sbom", | ||
| "supply-chain" | ||
| ], | ||
@@ -79,3 +101,3 @@ "author": "Nizoka <hello@pdfnative.dev> (https://pdfnative.dev)", | ||
| "dependencies": { | ||
| "pdfnative": "^1.2.0" | ||
| "pdfnative": "^1.3.0" | ||
| }, | ||
@@ -90,3 +112,6 @@ "devDependencies": { | ||
| "vitest": "^4.1.7" | ||
| }, | ||
| "overrides": { | ||
| "esbuild": "^0.28.1" | ||
| } | ||
| } |
+95
-22
@@ -11,2 +11,5 @@ # pdfnative-cli | ||
| [](https://docs.npmjs.com/generating-provenance-statements) | ||
| [](https://securityscorecards.dev/viewer/?uri=github.com/Nizoka/pdfnative-cli) | ||
| <!-- After registering the project at https://www.bestpractices.dev, add the badge: | ||
| [](https://www.bestpractices.dev/projects/<ID>) --> | ||
| [](https://www.npmjs.com/package/pdfnative) | ||
@@ -17,12 +20,16 @@ [](https://pdfnative.dev) | ||
| > **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](release-notes/v1.0.0.md). | ||
| > **What's new in v1.1.0** — built on **pdfnative 1.3.0**. `render` now exposes **22 | ||
| > Unicode scripts** (Telugu, Sinhala, Tibetan, Khmer, Myanmar, Amharic/Ethiopic + the | ||
| > existing 16) and **COLRv1 colour emoji** through expanded `--font` / `--lang` shortcuts, | ||
| > plus **true constant-memory streaming** (`--stream-true`) and a `--max-blocks` cap for | ||
| > very large documents. `inspect` gains a **PDF/UA (ISO 14289-1) structural validator** | ||
| > via `--pdfua` and `--check pdfua` for CI accessibility gates. This release also adds an | ||
| > **agent-native contract** — a global `--json` status/error envelope, stable `E_*` error | ||
| > codes, a `--dry-run` validation mode, a new **`schema`** command, and a **token-economy | ||
| > output projection** (`--summary` / `--fields` + compact JSON) that cuts agent output | ||
| > ~90 % — so autonomous AI | ||
| > agents and CI pipelines can drive the CLI deterministically (see | ||
| > [AGENTS.md](AGENTS.md)). A CycloneDX **SBOM** (`sbom.cdx.json`) is now attached to every | ||
| > [GitHub release](https://github.com/Nizoka/pdfnative-cli/releases). | ||
| > 100% backward-compatible. See [release notes](release-notes/v1.1.0.md). | ||
| > | ||
@@ -34,4 +41,6 @@ > ⭐ Star [`pdfnative`](https://github.com/Nizoka/pdfnative) — the zero-dependency PDF engine that powers this CLI. | ||
| - **`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. | ||
| watermarks (text + image), page templates, PDF/A archival, **22 Unicode scripts + COLRv1 | ||
| colour emoji**, streaming (single-pass, page-by-page, or **true constant-memory | ||
| `--stream-true`**), and a hybrid `flags + --layout file.json` model for the full | ||
| `PdfLayoutOptions` surface. | ||
| - **`sign`** — CMS/PKCS#7 digital signatures with full metadata (`--reason`, `--name`, | ||
@@ -41,3 +50,4 @@ `--location`, `--contact`, `--signing-time`) and intermediate CA chains via | ||
| - **`inspect`** — PDF version, page count, encryption, PDF/A conformance, signature count, | ||
| metadata. `--verbose`, `--pages`, and `--check pdfa|signed|encrypted` for CI assertions. | ||
| metadata, and **PDF/UA (ISO 14289-1) structural validation**. `--verbose`, `--pages`, | ||
| `--pdfua`, and `--check pdfa|signed|encrypted|pdfua` for CI assertions. | ||
| - **`verify`** — verify every CMS/PKCS#7 signature: byte-range integrity, RSA/ECDSA | ||
@@ -50,2 +60,9 @@ signature value, certificate chain, trust roots, **RFC 3161 timestamp (PAdES-T)**, and | ||
| - **`completion`** — emit `bash`, `zsh`, or `fish` shell-completion scripts. | ||
| - **`schema`** — print a versioned JSON Schema (Draft 2020-12) for any CLI input/output | ||
| shape, so agents can self-validate before invoking a command. | ||
| - **Agent-native** — a global `--json` status/error envelope, stable `E_*` error codes, and | ||
| a `--dry-run` validation mode let autonomous AI agents and CI drive the CLI | ||
| deterministically. Token-economy levers — **`--summary`** (minimal verdict), **`--fields`** | ||
| (dot-path projection), and compact JSON under `--json` — shrink agent output ~90 %. | ||
| See [AGENTS.md](AGENTS.md). | ||
| - **`.pdfnativerc.json`** — optional config file for default flags (global + per-command); | ||
@@ -69,7 +86,12 @@ precedence is CLI flags > env > config. | ||
| | `sign` digital signatures | ✅ | RSA (CMS/PKCS#7), metadata fields, cert chains | | ||
| | `inspect` PDF metadata | ✅ | `--verbose`, `--pages`, `--check pdfa\|signed\|encrypted` | | ||
| | `inspect` PDF metadata | ✅ | `--verbose`, `--pages`, `--pdfua`, `--check pdfa\|signed\|encrypted\|pdfua` | | ||
| | `verify` signature verification | ✅ | Integrity + chain + trust + timestamp + revocation; `--strict` | | ||
| | `batch` parallel rendering | ✅ | Directory → PDFs, `--concurrency`, `--fail-fast` | | ||
| | `completion` shell scripts | ✅ | `bash` / `zsh` / `fish` | | ||
| | `schema` JSON Schema export | ✅ | `render` / `inspect` / `verify` / `batch` shapes | | ||
| | `.pdfnativerc.json` config file | ✅ | Global + per-command defaults; flags > env > config | | ||
| | **Agent / automation** | | | | ||
| | Global `--json` envelope | ✅ | Status on success, `{ ok, error: { code, message } }` on failure | | ||
| | Stable error codes | ✅ | `E_USAGE`, `E_INPUT`, `E_PARSE`, `E_SIGN`, `E_VERIFY_FAILED`, … | | ||
| | `--dry-run` validation | ✅ | `render` / `sign` / `batch` — validate without writing | | ||
| | **Document Blocks** | | | | ||
@@ -85,3 +107,3 @@ | Headings, paragraphs, lists | ✅ | Full text styling support | | ||
| | PDF/A archival (1b, 2b, 2u, 3b) | ✅ | `--tagged pdfa<level>` (preferred) or `--conformance` (deprecated) | | ||
| | Streaming output | ✅ | `--stream` for large documents | | ||
| | Streaming output | ✅ | `--stream` (single-pass) for large documents | | ||
| | Compression | ✅ | `--compress` flag | | ||
@@ -94,3 +116,3 @@ | Encryption (AES-128/256) | ✅ | `--encrypt-*` flags + env-var precedence | | ||
| | PDF/A-3 attachments | ✅ | `--attachment <path>:<mime>:<rel>:<desc>` (repeatable) | | ||
| | Multilingual fonts | ✅ | `--lang th,ja,ar` (requires `registerFontLoader()` in wrapper; Latin built-in) | | ||
| | Multilingual fonts | ✅ | 22 Unicode scripts via `--font <code> --lang <code>` (e.g. `th`, `ja`, `ar`, `te`, `si`, `km`); Latin built-in | | ||
| | Table-centric variant (`PdfParams`) | ✅ | `--variant table` | | ||
@@ -118,5 +140,8 @@ | Full `PdfLayoutOptions` | ✅ | `--layout <file.json>` | | ||
| | Page-by-page streaming | ✅ | `--stream-page-by-page` (TOC- and `{pages}`-compatible) | | ||
| | True constant-memory streaming | ✅ | `--stream-true` (parts freed as emitted; byte-identical output) | | ||
| | Configurable block cap | ✅ | `--max-blocks <n>` (default 100 000) | | ||
| | PDF/UA structural validation | ✅ | `inspect --pdfua` / `--check pdfua` (ISO 14289-1) — developer-time gate, not a substitute for veraPDF | | ||
| | `--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 | | ||
| | `--font` bundled shortcuts | ✅ | Repeatable allow-list: `latin`, `emoji`, `color-emoji`, 22 script codes | | ||
@@ -162,2 +187,5 @@ **Note:** features marked **⚠️** are tracked in [ROADMAP.md](ROADMAP.md). Everything else | ||
| # True constant-memory streaming (lowest peak memory; byte-identical) | ||
| pdfnative render --input big-doc.json --output report.pdf --stream-true | ||
| # PDF/A conformance | ||
@@ -204,2 +232,8 @@ pdfnative render --input document.json --output archived.pdf --conformance 2b | ||
| # PDF/UA (ISO 14289-1) structural validation report | ||
| pdfnative inspect --input report.pdf --pdfua | ||
| # CI accessibility gate (exit 1 if not PDF/UA-structurally-valid) | ||
| pdfnative inspect --input report.pdf --check pdfua | ||
| # From stdin | ||
@@ -232,3 +266,3 @@ cat report.pdf | pdfnative inspect | ||
| |----------|----------|-------------| | ||
| | [`render/document/`](samples/render/document/) | 5 files | Minimal, report, all-blocks reference, invoice, technical spec | | ||
| | [`render/document/`](samples/render/document/) | 6 files | Minimal, report, all-blocks reference, invoice, technical spec, `--max-blocks` guard | | ||
| | [`render/table/`](samples/render/table/) | 2 files | Project status, financial summary | | ||
@@ -264,3 +298,5 @@ | [`render/barcode/`](samples/render/barcode/) | 3 files | QR code, Code 128 shipping label, EAN-13 product | | ||
| | `--output <file>` | stdout | Output PDF path | | ||
| | `--stream` | false | Use streaming output (`AsyncGenerator`) | | ||
| | `--stream` | false | Single-pass streaming output (`AsyncGenerator`); no TOC, no `{pages}` | | ||
| | `--stream-page-by-page` | false | Stream at PDF object boundaries (TOC- and `{pages}`-compatible) | | ||
| | `--stream-true` | false | True constant-memory streaming; parts freed as emitted; byte-identical; no TOC, no `{pages}` | | ||
| | `--variant <kind>` | `document` | `document` (default) or `table` (selects `buildPDFBytes`) | | ||
@@ -271,2 +307,3 @@ | `--layout <file.json>` | — | Load a `Partial<PdfLayoutOptions>` (CLI flags override) | | ||
| | `--compress` | false | Enable FlateDecode compression | | ||
| | `--max-blocks <n>` | `100000` | Maximum document blocks before pdfnative aborts (large-report guard) | | ||
| | `--tagged <level>` | none | PDF/A: `none`, `pdfa1b`, `pdfa2b`, `pdfa2u`, `pdfa3b` | | ||
@@ -284,3 +321,4 @@ | `--conformance <1b\|2b\|3b>` | — | **Deprecated** — use `--tagged pdfa<level>` | | ||
| | `--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 | | ||
| | `--lang <code,code>` | — | Activate registered font loaders for non-Latin scripts (`th`, `ja`, `ar`, `te`, `si`, `km`, …); Latin is built-in | | ||
| | `--font <name>` _(repeatable)_ | — | Register a bundled font shortcut. Allow-list: `latin`, `emoji`, `color-emoji`, and the 22 script codes `ar hy bn ru hi am ka el he ja km ko my pl zh si ta te th bo tr vi`. The name doubles as the `--lang` code. | | ||
@@ -314,3 +352,4 @@ See `samples/render/` for a working example of every category. | ||
| | `--pages` | false | Add per-page metadata array | | ||
| | `--check pdfa\|signed\|encrypted` _(repeatable)_ | — | CI-friendly assertion; sets exit code (0 = pass, 1 = fail) | | ||
| | `--pdfua` | false | Add a PDF/UA (ISO 14289-1) structural validation report (`valid` + `errors` + `warnings`) | | ||
| | `--check pdfa\|signed\|encrypted\|pdfua` _(repeatable)_ | — | CI-friendly assertion; sets exit code (0 = pass, 1 = fail) | | ||
@@ -356,2 +395,16 @@ ### `pdfnative verify` | ||
| ### `pdfnative schema` | ||
| Print a versioned JSON Schema (Draft 2020-12) for a CLI input/output shape, so an | ||
| agent can self-validate before invoking a command. | ||
| ```bash | ||
| pdfnative schema # render input schema (default) | ||
| pdfnative schema render # render input (document | table variant) | ||
| pdfnative schema inspect # inspect --format json output | ||
| pdfnative schema verify # verify --format json output | ||
| pdfnative schema batch # batch --format json output | ||
| pdfnative schema list # list the available subjects | ||
| ``` | ||
| ### Global options | ||
@@ -365,4 +418,24 @@ | ||
| | `--no-color` | Disable ANSI colour (also respects the `NO_COLOR` env var) | | ||
| | `--json` | Agent mode: emit a JSON status/error envelope on stderr (data stays on stdout) | | ||
| | `--dry-run` | Validate inputs and exit without writing output (`render` / `sign` / `batch`) | | ||
| | `--version --json` | Machine-readable version output | | ||
| ## Driving from AI agents | ||
| `pdfnative-cli` is designed so an autonomous agent (or any program) can drive it | ||
| deterministically — no MCP server, no daemon, just the process contract: | ||
| - **stdout = the artifact** (PDF, JSON report, schema, completion script); | ||
| **stderr = diagnostics.** | ||
| - Pass **`--json`** to get a single machine-readable envelope on stderr. On failure: | ||
| `{ "ok": false, "command": "...", "error": { "code": "E_*", "message": "..." } }`. | ||
| On success for `render` / `sign` / `batch`: a `{ "ok": true, ... }` status line. | ||
| - Branch on the **stable error code** (`E_USAGE`, `E_INPUT`, `E_PARSE`, `E_IO`, `E_SIGN`, | ||
| `E_VERIFY_FAILED`, `E_CHECK_FAILED`, `E_UNSUPPORTED`, `E_RUNTIME`) rather than the | ||
| message text. Numeric **exit codes** stay `0` (success), `1` (runtime), `2` (usage). | ||
| - Use **`--dry-run`** to validate input without producing output. | ||
| - Fetch a **`schema`** to validate input before calling. | ||
| See [AGENTS.md](AGENTS.md) and the [`samples/agent/`](samples/agent) scripts. | ||
| ## Security | ||
@@ -383,3 +456,3 @@ | ||
| **Have a question?** | ||
| - 📖 Check the [FAQ](docs/KNOWLEDGE_BASE.md#11-frequently-asked-questions) first | ||
| - 📖 Check the [FAQ](docs/KNOWLEDGE_BASE.md#12-frequently-asked-questions) first | ||
| - 🔍 Search the samples: `grep -r "your-keyword" samples/` | ||
@@ -386,0 +459,0 @@ - 📚 Read [KNOWLEDGE_BASE.md](docs/KNOWLEDGE_BASE.md) for technical details |
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is too big to display
New alerts
Environment variable access
Supply chain riskPackage accesses environment variables, which may be a sign of credential stuffing or data theft.
Found 2 instances
Long strings
Supply chain riskContains long string literals, which may be a sign of obfuscated or packed code.
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Fixed alerts
Long strings
Supply chain riskContains long string literals, which may be a sign of obfuscated or packed code.
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Improved metrics
- Total package byte prevSize
1173012
16.42%- Lines of code
8846
16.7%- Number of lines in readme file
475
18.16%Worsened metrics
- Number of low supply chain risk alerts
49
32.43%Dependency changes
Updated
pdfnative@^1.3.0