Markdown to Word CLI

Not on npm yet. The CLI is finished and its 184 tests pass, but it has not been published: the conversion engine it depends on has an unresolved licence question, and a public package that depends on an unpublished private one would not install. So the commands below are the commands you will run when it ships, not commands that work today — npx @mdtodocx/cli currently returns a 404 from the registry, and there is no public repository to install from either. We would rather write that plainly than point you at a URL that does not exist. Meanwhile the same engine runs in your browser on the Markdown to Word converter, and the package name is being reserved so the command below is the one that will be correct.

Install (once it is published)

npx @mdtodocx/cli file.md            # no install at all
npm i -g @mdtodocx/cli               # then: mdtodocx file.md
npm i -D @mdtodocx/cli               # then: npx mdtodocx file.md

The command is md2word; the package is scoped as @mdtodocx/cli. If you ever see an unscoped md2word package on npm, check where it points before installing it — we publish under the scope, and the unscoped name is not ours.

The commands

mdtodocx input.md -o output.docx              # Word, the default
mdtodocx input.md -o output.pdf               # PDF, needs a headless Chromium
md2word README.md --to html                  # standalone print-ready HTML
md2word "docs/*.md" --out-dir dist/          # batch a folder
md2word doc.docx --to md                     # Word back to Markdown
cat answer.md | md2word --to docx > out.docx  # stdin to stdout

The direction is inferred from the extensions: .md in means Word out, .docx or .html in means Markdown out. Both --to and the extension of -o override the guess, and if the two disagree the explicit --to wins. A glob is expanded by the CLI itself rather than relying on the shell, so "docs/*.md" behaves the same in PowerShell as in bash when you quote it.

Options

Exit codes and error output

Separating "you typed it wrong" from "the conversion failed" is what makes the tool usable in a Makefile or a CI job: a 2 means stop and fix the pipeline, a 1 means look at the document. Errors are one line plus an actionable hint:; stack traces never reach the terminal.

Pipes, batches and scripting

When bytes are being written to stdout, as in cat x.md | md2word > out.docx, the human-readable summary is redirected to stderr so it can never corrupt the document. That one rule is what makes the CLI safe inside a shell pipeline. For anything scripted, add --json and you get a single object with ok, the tool version, a files array carrying the input path, output path, format, byte count, per-file warnings and metadata (title, word count, heading count, image count, equation count, front matter), an errors array, and durationMs. A batch keeps going after a file fails and reports the failure in errors while still writing the ones that worked, so a folder of a hundred documents is not held hostage by one broken table.

Warnings are never swallowed. A skipped remote image, an unrendered diagram, an equation that could not be parsed — each produces a named warning attached to the file it came from, both in the terminal summary and in the JSON. Nothing degrades quietly.

The two optional dependencies

PDF is produced by printing the HTML output with a headless Chromium, which is deliberately not bundled — it would add hundreds of megabytes to a text converter. Install playwright (then npx playwright install chromium) or puppeteer as a dev dependency. Without one, --to pdf fails with an explicit message pointing you at --to html plus your browser's "Print to PDF"; it never writes a broken file. Mermaid works the same way: --mermaid shells out to mmdc from @mermaid-js/mermaid-cli, and without it diagrams stay as code blocks and the CLI prints a note saying exactly that.

How it relates to everything else here

The CLI, the Markdown to Word MCP server, the Markdown to Word skill and this website all run the same conversion engine, so a document converted in a terminal is byte-for-byte comparable to one converted in a browser tab. The difference is the entry point: the CLI is for scripts and CI, the MCP server is for AI agents that need to hand a user a file, and the website is for one document right now. Free and Pro tiering belongs to the hosted service described on pricing; a locally installed CLI runs the whole engine with no entitlement check, so every flag works. If you are migrating from Pandoc, the flag-by-flag mapping is on Markdown to Word with Pandoc, and the Python equivalents are compared on Markdown to PDF with Python.

Related tools and guides