Tool · Node.js

docx2pdf-cli

Convert Word documents to PDF, one file at a time or by the thousand. Hybrid backend strategy picks the right converter for what's installed on your machine. No silent fallbacks; missing fonts get flagged before they cost you a re-render.

What it does

• Single-file or batch conversion. One file in, one file out — or point at a folder of .docx files and an output directory.
• Parallel processing with NDJSON output. --concurrency N runs N conversions simultaneously; --json emits one structured line per file (with outputBytes, durationMs, and on failure exitCode) so an agent or CI pipe doesn't have to scrape prose.
• Six hybrid backends. LibreOffice, Gotenberg, ConvertAPI, Apple Pages, Microsoft Word, and a text-only textutil-cups fallback. The tool picks the best available unless you override with --backend. Add --strict-fidelity to refuse the text-only downgrade.
• Smart doctor. --doctor walks every backend candidate and reports which are usable on this machine. The JSON output includes per-backend install commands (platform-aware: apt, dnf, brew, …) and a top-level recommendation — single best next step for this host. If Docker is installed, leads with docker run gotenberg/gotenberg:8 so you don't need 700 MB of LibreOffice.
• Capability discovery. --capabilities emits a machine-readable manifest: capability-spec version, tool version, backend fidelity map, supported flags, strict-fidelity policy hints. Agents validate the contract before relying on it.
• Network retries. --retries N on the network backends (gotenberg, convertapi) retries transient failures with a non-busy backoff.
• Font validation. --check-fonts verifies the document's referenced fonts are present before converting, so you don't get silent substitutions in the rendered PDF.
• Backend transparency. --why prints the full selection decision tree — no opaque "auto" mode that silently picks a low-fidelity fallback.
• Honest failure. Structured error envelopes carry an optional kind (e.g. NO_BACKEND) so library callers branch on error type, not message text. Non-zero exits; nothing gets quietly mangled.

Quickstart

# Install
npm i -g docx2pdf-cli
docx2pdf --version

# What backends does this machine have?
docx2pdf --doctor
docx2pdf --list-backends

# Machine-readable capability manifest (for agents)
docx2pdf --capabilities

# Single file
docx2pdf contract.docx contract.pdf

# Whole folder, in parallel, into a different output directory, NDJSON per file
docx2pdf --concurrency 4 --json --out-dir ./pdfs ./drafts/*.docx

# Pin a specific backend; retry network failures
docx2pdf --backend gotenberg --retries 3 contract.docx contract.pdf

# Check fonts before rendering
docx2pdf --check-fonts contract.docx

Why hybrid backends matter

There is no single DOCX-to-PDF converter that works perfectly everywhere. LibreOffice is the most reliable open-source option but produces slightly different output than Word. Pandoc is great for content-heavy documents but has known limitations with complex Word features. Gotenberg is a containerized service that's perfect when you need consistent output across a fleet, but requires running a server.

Rather than pretend any single backend is universally correct, this tool lets you pick. The --doctor probe makes the choice explicit; the --backend flag makes it auditable.

For agents and automation

The agent affordances are first-class, not bolted on. AGENTS.md documents the full contract (output envelope, exit codes, discovery, failure → recovery). llms.txt and examples/agent-defaults.json ship recommended invocations. The schemas/ directory holds formal JSON schemas for both --capabilities and --doctor output, so an agent can validate against the schema rather than parse prose. Concept deep-dives live in docs/reference/; per-backend setup in docs/setup/.

docx2pdf --strict-fidelity --json --out-dir ./pdfs *.docx

The discovery loop for a fresh-host agent: call --capabilities to learn the feature set, call --doctor to find an installed backend (or read the recommendation field to install one), then invoke with --strict-fidelity --json and branch on exitCode per file.

Where it fits in the workflow

The middle step in the three-CLI workflow: take the agreed .docx from nda-review-cli's finalize step and produce a PDF for sign-cli to sign. See the full workflow for the chained commands.

It's also useful on its own for any DOCX-to-PDF need — invoices, board materials, internal docs, anything. The contract pipeline is just one application.

Repo

github.com/DrBaher/docx2pdf-cli · MIT licensed · Node.js · npm-installable.