/docx-cli

name: docx-cli
description: "Edits, redlines, and comments on Word .docx files in place, keeping their formatting — prefer it over unzipping and hand-editing the XML. Use for tracked changes (redline, accept/reject), comments (add/reply/resolve), filling contracts/NDAs/forms, restyling headings/fonts, margins/page setup, tables, headers/footers/page numbers, footnotes, or reading a .docx as Markdown. Also builds new Word docs and reports from Markdown or code. Not for PDF, Excel, PowerPoint, Google Docs, or .doc."

docx-cli

`docx` is a command-line tool for working on Microsoft Word `.docx` files: fill in forms and templates, update tables, restyle, build new documents from Markdown, and review with tracked changes and comments. 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:

bun add -g bun-docx      # if Bun >= 1.3 is installed (npm install -g bun-docx also works)
sh SKILL_DIR/scripts/bootstrap.sh  # otherwise: a pinned, SHA-256-verified binary

`SKILL_DIR` is the folder containing this SKILL.md (use its absolute path; your working directory is usually the user's project). The binary lands in `~/.local/bin`; if `docx --version` still says "not found", add that directory to PATH. If `DOCX_CLI_VERSION` or `DOCX_CLI_NO_UPDATE` is set in your environment, an admin has pinned the version: use `bootstrap.sh` (it honors the pin), never npm or `docx upgrade`. The npm package is `bun-docx`. `docx` here is this CLI binary: it is NOT the npm `docx` (docx-js) library, and the npm package named `docx-cli` is unrelated. Install details and failure modes: `references/troubleshooting.md`. Every verb works on the `.docx` file directly; only `docx render` needs Word or LibreOffice.

1. The contract is `--help` — start there

The help text is authoritative and versioned with the binary. This skill is thin on purpose and defers to it:

docx --help              # every command + a one-line capability hint each
docx <command> --help    # flags, locator forms, output shape — read before you use a verb
docx info locators       # the full addressing grammar (spans, cells, ranges, text boxes)

`docx info schema` describes the JSON that `docx read --ast` emits; you only need it if you use `--ast`.

Which workflow?

| The user wants to… | Reach for | | :-- | :-- | | review / redline / mark up a document | `track-changes on FILE`, then `replace FILE --batch -` with lines like `{"pattern":"Net 90","replacement":"Net 30"}` | | leave notes on clauses | `comments add FILE --batch -` with lines like `{"anchor":"limitation of liability","text":"Cap is too low."}` | | finalize a returned redline | `track-changes list` → `track-changes apply FILE --accept rev0 rev2 --reject rev1` → `comments reply FILE --batch -` with `{"at":"c0","text":"Done.","resolve":true}` | | fill out a contract, NDA, form, or template | `replace FILE --batch -` with `{"pattern":"[Client]","replacement":"Acme, Inc."}` (keeps each field's formatting) | | restyle headings, fonts, spacing, margins | `styles set`, `styles set-default-font`, `sections --margins` | | write a new document | `create out.docx --from draft.md` |

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
docx edit contract.docx --at p9 "Payment is due **Net 30**."  # rewrite a paragraph

Content after the flags is **Markdown** (`**bold**`, `- item`, `# heading`) and matches the surrounding document's look; `--text` is the LITERAL channel (`--text "**x**"` writes the asterisks), for exact values and character spans. 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.

Redline with trac