Document conversion CLI reference

Command overview

Start here to choose the command for your task. All commands support --json for machine-readable output.

Install and command shape

The gordon-doc command is installed with the package. Run gordon-doc --help or gordon-doc <command> --help to view the option values accepted by the installed version. Commands print a concise human result by default; add --json whenever another program consumes the output.

python -m pip install gordon-doc-converter
gordon-doc version
gordon-doc convert --help

Diagnostics and version

Use doctor before a production run: it reports the detected platform, whether the session is interactive, and the availability of each renderer. engines lists renderer capabilities without determining overall health. version returns the installed package version. doctor exits with code 3 when no engine is available.

gordon-doc doctor
gordon-doc engines --json
gordon-doc version --json

Convert one document

convert accepts DOCX, ODT, PDF, HTML, and Markdown input. With no --to it creates PDF for DOCX, ODT, HTML, or Markdown; PDF input always requires --to. ODT, HTML, and Markdown input also convert to Markdown, HTML, YAML, and JSON through semantic extraction, with no engine required; ODT page images render through LibreOffice first. Repeat --to to request several artifacts. --output is appropriate for one single-file artifact; without it, the service derives a safe sibling output name and refuses to replace an existing file unless --overwrite is present. For DOCX-to-HTML, --engine word-com renders through Word COM on Windows; omit it or use --mode server for semantic extraction.

gordon-doc convert report.docx --output report.pdf
gordon-doc convert report.docx --to markdown --to html --to yaml --to json
gordon-doc convert report.docx --to html --engine word-com
gordon-doc convert report.pdf --to yaml --to json
gordon-doc convert report.html --to markdown --to yaml --to json
gordon-doc convert notes.md --to html --to yaml --to json
gordon-doc convert report.odt --to docx --engine libreoffice
gordon-doc convert report.odt --to markdown --to yaml --to json
gordon-doc convert report.pdf --to images --dpi 144

Conversion policy and output options

--engine word-com, libreoffice, or gotenberg requires that exact DOCX-to-PDF engine; explicit selection never falls back. For DOCX-to-HTML, --engine word-com renders through Word COM; omit it or use --mode server for semantic extraction. --mode selects automatic policy: desktop, server, container, strict-word, or strict-libreoffice. Tracked changes use --revisions final, original, or markup; comments use --comments omit, appendix, or markup, subject to engine support. --timeout is in seconds. For HTML and Markdown, --orientation portrait or landscape chooses A4 layout. --gotenberg-url supplies the Gotenberg base URL for this invocation.

gordon-doc convert contract.docx --engine word-com --revisions final --comments appendix
gordon-doc convert report.docx --to html --engine word-com
gordon-doc convert report.html --to pdf --orientation landscape
gordon-doc convert report.docx --mode server --gotenberg-url http://renderer:3000

Structured YAML and JSON artifacts

--to yaml and --to json serialize the same versioned semantic document. DOCX, PDF, HTML, and Markdown sources all produce it. Schema 1.5 keeps Markdown-like heading, paragraph, list, and table text, states whether a list is numbered and which counter it starts at, and preserves meaningful links, images, revisions, annotations, source order, metadata, and reverse locators. Repeat --to to extract once and write both formats. --metadata accepts none, basic, or layout; optional values with no data are omitted rather than written as null. --json-lines writes the JSON artifact as newline-delimited records to <stem>.jsonl instead of <stem>.json: a document record first, then every block in source order, then asset, annotation, and warning records, with each block carrying its section_path so the heading hierarchy survives a line stream. It applies to DOCX, PDF, HTML, and Markdown sources and leaves Markdown, HTML, and YAML output unchanged. --to json writes a document artifact, while the separate --json flag writes the CLI result contract to stdout.

gordon-doc convert report.docx --to yaml --to json --metadata basic
gordon-doc convert report.pdf --to yaml --to json --metadata layout
gordon-doc convert report.html --to yaml --to json --metadata basic
gordon-doc convert notes.md --to yaml --to json --metadata basic
gordon-doc convert report.docx --to json --json-lines
gordon-doc convert report.docx --to json --json

Reverse location and source verification

Structured artifacts identify the exact input with source.sha256 and verify each normalized block or table cell with source_anchor.content_sha256. DOCX anchors use the OOXML part and element path, with a native paragraph ID when Word supplies one; table cells extend the path with row and cell indexes. PDF anchors use the one-based physical page. PDF page coordinates are not yet available and can be added by a future layout provider. File offsets are not stable locators: DOCX recompression and PDF optimization or incremental saves change them without changing the visible content.

Conversion progress

convert and batch show phase-based progress automatically on interactive terminals. Progress is emitted only on stderr, so redirected stdout and machine-readable results remain clean. --json disables automatic progress; use --progress to force it or --no-progress to suppress it. Batch progress reports completed files over total files rather than an invented time percentage.

gordon-doc convert report.docx --to yaml --progress
gordon-doc convert report.docx --to json --no-progress
gordon-doc batch one.docx two.docx --output-dir converted --progress

Page images and starter templates

Use --to images to rasterize a PDF source or the PDF produced from a DOCX source. --dpi accepts 1 through 600; --image-format is png or jpeg; --quality applies to JPEG; repeat --page with one-based page numbers to select pages; --background sets the image background colour. Image output is a directory named <stem>.pages containing numbered files. template writes an editable starting point named by the output extension: an A4 HTML document, or a Markdown file whose front matter carries document metadata. It protects existing files unless --overwrite is supplied, and --orientation applies to HTML templates only.

gordon-doc convert report.pdf --to images --image-format jpeg --quality 85 --page 1 --page 3
gordon-doc template report.html --orientation landscape
gordon-doc template notes.md

Compare PDFs and convert batches

compare examines PDF structure, fonts, sizes, and rendered pixels. Set --diff-dir to save PNGs for pages that differ, and use --dpi to control comparison raster resolution. batch converts one or more DOCX files sequentially, isolating each file failure; it always targets PDF. --output-dir stores each generated PDF in the chosen directory. The batch exit code is non-zero when any item fails, while --json retains every item result for CI reporting.

gordon-doc compare expected.pdf actual.pdf --diff-dir differences --json
gordon-doc batch one.docx two.docx --output-dir converted --mode server --json

JSON results and exit codes

All commands accept --json. Successful conversion payloads include the selected and attempted engines, artifact paths and metadata, duration, effective annotation modes, warnings, and fallback information. Failures include a stable error code, safe message, engine when known, and retryable flag. Exit code 0 means success; 2 means invalid input or output already exists; 3 means engine/capability unavailable; 4 means conversion failed, timed out, or produced no output; and 5 means PDF validation failed.

gordon-doc convert report.docx --json
# PowerShell: stop a script if conversion fails
gordon-doc convert report.docx --output report.pdf
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }