DOCX CLI

docx-cli

docx is a command-line tool for reading, editing, redlining, and commenting on Microsoft Word .docx files. It edits the underlying OOXML in place (it never rebuilds the document from a lossy view), addresses everything with stable locators, and signals success through an exit code plus a one-line confirmation — so even small, cheap models can drive it reliably.

0. Make sure the binary is on PATH

Run docx --version. If you get "command not found", install it. Prefer the npm registry — no shell piping, and the package runs no install scripts:

bun add -g bun-docx      # or: npm install -g bun-docx   (needs Bun >= 1.3)

No Bun? From this skill folder run sh scripts/bootstrap.sh. It downloads no scripts and runs no remote code — it resolves the latest release tag from the GitHub API, downloads that release's prebuilt binary pinned to the tag, and verifies its SHA-256 against the release's published SHA256SUMS before installing. (By hand: download docx-<platform> + SHA256SUMS from https://github.com/kklimuk/docx-cli/releases/latest, verify, chmod +x, put it on PATH.) Every verb works against the .docx zip directly; only docx render needs Word (macOS/Windows) or LibreOffice installed.

1. The contract is --help / docx info — start there

The help text is authoritative and versioned with the binary. This skill is thin on purpose and defers to it. Before doing anything, run (none of these need a FILE):

docx --help              # every command + a one-line capability hint each
docx info locators       # the addressing grammar — READ THIS, it is the backbone
docx info schema         # the JSON-AST shape that "docx read --ast" emits

Then docx <command> --help for any verb before you use it.

2. Locators — how you address things

• pN paragraph, tN table, sN section; p3:5-20 = characters 5..19 of p3; pN-pM a block range; tN:rRcC a table cell; tbxN:pK paragraph K inside text box N (a floating stamp / pull quote / letterhead box — read prints its story right after the anchor paragraph between docx:textbox tbxN hints, and find / replace --all include it).
• Entities: cN comment, imgN image, linkN hyperlink, fnN/enN foot/endnote, tcN tracked change, eqN equation.
• Get them from docx read FILE (locators ride the Markdown as <!-- pN --> comments; a plain empty cell appears as <!-- tN:rRcC -->) or docx read FILE --ast (lossless JSON).
• Ids are positional and SHIFT after structural edits. Re-read between mutations — OR apply many changes from ONE read with --batch (below).
• Pass a locator with --at (including insert: after a block, into a bare cell), --after/--before when insert's side matters, or --from/--to (read a slice). A bare cell edit requires one direct paragraph; merged/complex cells need an explicit tN:rRcC:pK.
• Don't hand-count character offsets: docx find FILE "phrase" returns the exact span locator (e.g. p3:5-20) to paste into --at.

3. Golden workflows

Fill out a form or contract (keeps formatting)

docx replace swaps only the text and preserves the run's bold/font and any tab stops — so it fills bold, tabbed template lines without rebuilding runs.

docx read contract.docx                                  # see content + locators
docx replace contract.docx "[Client Name]" "Acme, Inc."  # one field
docx replace contract.docx "[Status]" "Approved" --bold --clear highlight
docx edit contract.docx --at t2:r2c1 --text "Charlie Darwin" # fill a blank cell
docx replace contract.docx --batch fills.jsonl           # many fields, one read/write

Replacement text inherits the matched run's formatting unless you overlay --bold/--color/--font/… or strip inherited properties with --clear. A replacement defaults to the first match; pass --all (or "all":true in its JSONL entry) when every occurrence should change.