pdfnative-cli command builder

Pick a command, fill the form, copy the resulting npx pdfnative-cli invocation. Covers all twenty-one commands of pdfnative-cli v1.5.0 (engine pdfnative ≥ 1.8.0) — authoring (render, fill, annotate, metadata), the page tree (merge, split, extract), the complete PAdES ladder (sign --timestamp B-T, ltv B-LT, doc-timestamp B-LTA, plus encrypt / decrypt and verify), reading (inspect, extract-text, compare), and automation (batch with declarative manifests, doctor, schema, completion, govern). The most-used flags have form fields; the CLI guide is the exhaustive flag reference. The builder runs entirely in your browser — nothing is uploaded.

Quick preset:

--input Path to JSON input. Omit to read from stdin.

--output Output path. Omit to write to stdout.

--variant Selects the renderer variant.

--page-size

--margin Single value or top,right,bottom,left in points.

--tagged

--compress FlateDecode all content streams.

--stream AsyncGenerator streaming output. Chunk it with --chunk-size.

--strict v1.4 Escalate PDF/A and PDF/X diagnostics (unembedded form fonts, DeviceCMYK images, PDFX_ANNOTATIONS, TYPOGRAPHY_FEATURE_INEFFECTIVE… — 9 codes since v1.5.0) into a hard failure before the first byte — exit 1 / E_CHECK_FAILED.

--chunk-size v1.4 Chunk size in bytes for --stream / --stream-true.

--layout (file path) Load any subset of PdfLayoutOptions. CLI flags override the layout file.

--lang Comma-separated language codes. Non-Latin scripts need their font registered — pass the same code to --font (27 bundled scripts; lo, nod, khb, tdd, cjm since v1.5.0). ha, yo, ig, sw are aliases of latin.

--font-file (one per line) v1.5 Register and embed a TrueType/OpenType font you ship: <path.ttf>[:name], repeatable. Path checked, 32 MiB cap, sfnt signature required (no collections, no WOFF), validated by the font compiler; the name defaults to the file stem and is added to --lang.

Iteration helpers

--watch Re-render when the --input file changes (only that file is watched). Requires --input + a file --output.

--template Base document JSON: the input (stdin or --input) is deep-merged on top — caller wins, arrays replace. Not variable substitution.

--font Bundled font codes — besides these, any of the 27 script codes (ar, th, ja… plus lo, nod, khb, tdd, cjm since v1.5.0) works and doubles as the --lang code; 31 bundled font modules in total.

Bookmarks, math & layout v1.2

--outline Add a /Outlines bookmark tree. auto derives it from headings.

--inspect-layout Emit a LayoutInspection JSON report instead of a PDF.

--debug-layout Overlay layout-debug guides on a normal PDF.

Typography v1.5

--split-paragraphs Paragraphs may break across pages (widows/orphans default to 2).

--keep-headings-with-next A heading never ends a page alone.

--kerning Pair kerning — needs a registered font (--font latin --lang latin).

--font-features Comma-separated OpenType features: tnum, pnum, lnum, onum, zero, ordn, sups, subs, smcp, c2sc, case. TYPOGRAPHY_FEATURE_INEFFECTIVE warns when a tag changes nothing in the font.

The full layout.typography set (widows/orphans, unitBinding, punctuationSpacing, opticalMargins, hyphenationLanguage…) lives in the JSON or the --layout file; soft hyphens (U+00AD) are always honoured.

PDF/X-4 & output intent v1.5

--pdfx PDF/X-4 claim. Needs an output ICC profile, every font embedded, --trapped true|false and a TrimBox or ArtBox per page. Exclusive with --tagged pdfa* and encryption.

--output-intent-icc ICC profile for layout.outputIntent (RGB, CMYK or Gray; prtr class for PDF/X-4). 16 MiB cap, acsp signature checked.

--output-intent-id outputConditionIdentifier — defaults to the ICC file's basename. Requires --output-intent-icc, or outputIntent.iccProfile in the --layout file.

--trapped /Info /Trapped. Under --pdfx, unknown is refused and unset means false.

Colours everywhere also accept CMYK — [c, m, y, k] percent or "c m y k" operands 0–1 (DeviceCMYK). Check the result with inspect --check pdfx.

Watermark

--watermark-text

--watermark-image

--watermark-opacity

--watermark-angle

--watermark-color

--watermark-font-size

--watermark-position

Headers / footers

--header-left

--header-center

--header-right

--footer-left

--footer-center

--footer-right

Placeholders: {page}, {pages}, {date}, {title}. {pages} is rejected with --stream.

Encryption (mutually exclusive with --tagged pdfa* and --pdfx)

--encrypt-owner-pass Required if any --encrypt-* flag is set. Prefer the env var.

--encrypt-user-pass

--encrypt-algorithm

--encrypt-permissions

Since v1.3.0 the CLI also has a unified encryption vocabulary shared by render / merge / split / extract — --encrypt aes-128|aes-256, --owner-password, --user-password, --permissions. See the CLI guide.

PDF/A-3 attachments

--attachment (one per line) Format: path[:mime[:relationship[:description]]]. Repeatable.

--input

--output

--key Or set $PDFNATIVE_SIGN_KEY.

--cert Or set $PDFNATIVE_SIGN_CERT.

--cert-chain (one per line) Repeatable. Or set $PDFNATIVE_SIGN_CHAIN.

--algorithm

--signing-time

--reason

--name

--location

--contact

--pure-crypto v1.2 Force the portable pure-JS CMS path. The default delegates to node:crypto, inheriting its side-channel hardening; the pure-JS path is not constant-time.

PAdES & timestamps v1.4

--timestamp (TSA URL) Embed an RFC 3161 token (PAdES B-T). The only network opt-in on sign — SSRF-guarded, no silent fallback (E_NETWORK / E_PARSE).

--timestamp-timeout (ms) v1.5 Bound on the TSA round-trip; reported as timestamp.timeoutMs in the envelope. Only together with --timestamp.

--timestamp-digest

--digest CMS digest for RSA keys; ECDSA stays SHA-256.

--profile

--allow-multiple Add a signature to an already-signed PDF instead of refusing.

--field-name

--signature-rect Visible widget: x1,y1,x2,y2. Pair with --signature-page.

--signature-page

--placeholder-bytes Reserve a larger /Contents (long chains, big TSA tokens).

--input

--format

--strict Exit 1 on any failure or zero signatures.

--trust (one per line) Trust-anchor PEMs. Repeatable.

--revocation

--revocation-policy

--summary Minimal verdict under --json: { valid, signatures, invalid }.

Scope (since v1.0.0): full CMS/PKCS#7 verification (RSA-SHA256 — plus SHA-384/512 since v1.4.0 — and ECDSA-SHA256), byte-range integrity, certificate chain, trust evaluation against --trust roots, RFC 3161 timestamp validation (PAdES-T) incl. /DocTimeStamp revisions (v1.4.0), and OCSP/CRL revocation checking. See the CLI guide.

--input (one path per line, 2–50) Source PDFs, concatenated in order. Repeatable.

--output

--max-output-size Output ceiling in bytes (default 256 MiB).

--drop-annotations

--dry-run

Encrypted sources are supported since v1.3.0 — decrypt them on ingest with --password, and re-encrypt the merged output with --encrypt. Signatures and /AcroForm are dropped (page edits invalidate /ByteRange); URI /Link annotations are preserved. Every path is validated against traversal.

--input

--output-dir Required. Parts written as <prefix>-<n>.pdf.

--prefix

--pages Comma-separated 1-based inclusive ranges. Omit for one output per page.

--dry-run

--input

--output

--pages 1-based page list/ranges. Order is preserved and repeats are allowed.

--dry-run

--input

--output

--annotations (file path) JSON array (or { "annotations": [...] }): each entry a markup annotation plus a 1-based page. Link entry (v1.5.0): { "type": "link", "page": 1, "rect": [72, 700, 300, 720], "url": "https://pdfnative.dev" } — http:, https: or mailto: only, otherwise E_INPUT.

--password v1.4 Annotate an encrypted PDF — added objects are encrypted under the existing scheme.

--dry-run

Written with an incremental save, so existing signatures stay valid. Types: text, highlight, underline, strikeout, squiggly, square, circle, line, freetext, and link (v1.5.0 — a /Link with a /URI action over a click rectangle). Colours accept CMYK too. Overlay, not redaction.

subcommand rules prints the agent/human protocol; policy the machine-readable JSON; verify-issue gates a draft.

draft file (verify-issue) Path to the local issue draft to gate. Exit 1 / E_POLICY on a violation.

--json Machine-readable output (best with policy).

Agents act as draftsmen: a human must always review and submit. verify-issue is a pure, fully offline validator — no GitHub or network access.

--input

--output

--title

--author

--subject

--keywords

--mod-date

--from-json All fields from a JSON file (schema metadata). Mutually exclusive with the individual flags.

--password

--dry-run

Written as an incremental save — the original bytes stay as a prefix, so existing signatures remain valid for their revision. /Info and XMP stay in sync. Reading metadata remains inspect's job.

subcommand PAdES B-LT: certificates, OCSP responses and CRLs embedded into the /DSS dictionary.

--input

--output collect writes the evidence JSON; embed / add write the PDF.

--online Required for collect / add — the explicit network opt-in (SSRF-guarded). embed is 100 % offline.

--data (for embed) Evidence JSON produced by collect — the air-gap bridge.

--prefer

--timeout (ms)

--extra-cert (one per line) Additional certificates for the /DSS. Repeatable.

--dry-run

Air-gapped workflow: ltv collect --online on a connected machine → transfer the JSON → ltv embed --data inside the enclave, where no network I/O is even possible. Continue to B-LTA with doc-timestamp.

--input

--output

--url (TSA endpoint) Required — making the network use an explicit opt-in. SSRF-guarded, 10 s timeout, 5 MiB cap, no redirects.

--digest

--field-name

--placeholder-bytes

--timeout (ms)

--dry-run Never touches the network.

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

--input

--output

--owner-password Required. Prefer the env var — never shell history.

--user-password Without it the document opens with no prompt; the owner password only governs permissions.

--algorithm

--permissions Comma list: print, copy, modify, extract.

--password (source) Open an already-encrypted source (password rotation).

--stream

--dry-run

--input

--output

--password Reads RC4, AES-128 and AES-256 sources.

--drop-annotations

--stream

--dry-run

--input

--format

--pages

--runs Include positioned runs { text, x, y, fontSize, fontName }.

--password

--max-length Hard cap on total characters; 0 disables.

--summary (json) Emit only { pages, characters }.

--pretty

Real Unicode from the /ToUnicode mapping in reading order — ndjson is a natural feed for a RAG ingestion pipeline.

document A (positional)

document B (positional)

--mode Structure = page count, page/print boxes, metadata, form fields, annotations, encryption, signatures.

--format

--tolerance (pt)

--ignore-whitespace

--pages

--password-a

--password-b

--pretty

CI contract: identical → exit 0; different → the report prints on stdout first, then exit 1 / E_CHECK_FAILED. Not a visual diff — pdfnative has no rasteriser; compare diffs what the format declares.

--input

--output

--data Required unless --flatten or --export.

--on-unknown

--flatten Freeze the values into page content.

--export Read-only: dump current values in --data shape.

--force Flatten even when a signed signature field is present (invalidates it).

--need-appearances

--password

--dry-run

The three modes compose into a round trip: --export the current values, edit the JSON, feed it back with --data, optionally --flatten.

--input-dir Directory of *.json documents (directory mode).

--output-dir

--concurrency

--fail-fast

--manifest v1.4 Declarative pipeline: { "version": 1, "tasks": [{ "id", "command", "flags" }] }. "@<id>" references an earlier task's output; a 14-command whitelist applies (never ltv / compare / the meta commands); validated in full before anything runs; max 1 000 tasks.

--allow-network Required before any network flag inside the manifest (--timestamp, --url, --online, --revocation online).

--continue-on-error Keep going after a failure; @id-dependent tasks are skipped.

--dry-run

--summary Emit { total, succeeded, failed }.

--format

--pretty

Eight offline checks: cli version, node (≥ 22 since v1.4.0), webcrypto CSPRNG, the resolved pdfnative engine version, the commands count, and since v1.5.0 fonts (31 modules / 27 scripts, probed on disk), unicode (the USE database version) and conformance (pdfa1b,pdfa2b,pdfa2u,pdfa3b,pdfx4). --json emits { ok, checks: [{ name, status, value, detail }] }. The first thing to run in a new environment — and the first thing an agent should call.

subject (positional) Versioned JSON Schemas (Draft 2020-12) — the $id embeds the CLI version, so agents can self-validate before invoking a command. 19 subjects in v1.5.0.

shell (positional) Emits a completion script covering all 21 commands and their flags. Pipe it into your shell's completion directory.

Global flags (any command) v1.5

placement Since v1.5.0 global flags may precede the command name (pdfnative --json inspect …). Arguments without any command exit 2 / E_USAGE.

--creation-date Pin the creation instant of every PDF written in this run (render, batch): /CreationDate, xmp:CreateDate, {date} and the trailer /ID derive from it, in UTC — identical SHA-256 on every host. Falls back to $SOURCE_DATE_EPOCH. Encrypted output is never reproducible.

--dry-run Validate and exit without writing. render pre-flights the real build in memory; never performs network I/O.

--json Agent mode: JSON status/error envelope on stderr with a stable E_* code; data stays on stdout.

--quiet Suppress progress output on stderr.

--no-color Disable ANSI colour (also respects NO_COLOR).

Generated command

npx pdfnative-cli render

Paste this in any shell. Secrets are never sent — the entire builder runs client-side.

What this playground does not do

It does not execute the CLI in your browser — signing real PDFs requires real private keys, and we will not pretend to. For an in-browser demo of render output, see the homepage live demo. To exercise the full CLI on your machine: npx pdfnative-cli <your built command>.

Resources

CLI guide — full command reference, security model, recipes
pdfnative-cli on GitHub
pdfnative-cli release notes
MCP guide · MCP playground

pdfnative-cli command builder

Generated command Copy

What this playground does not do

Resources

Generated command