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.4.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 diagnostics (unembedded form fonts, DeviceCMYK images…) 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 (22 bundled scripts).

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 22 script codes (ar, th, ja…) works and doubles as the --lang code.

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.

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*)

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

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

Five offline checks: CLI version, Node (≥ 22 since v1.4.0), WebCrypto CSPRNG, resolved pdfnative engine version, and the command count. 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.4.0.

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

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