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:

```sh
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):

```sh
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.
- 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.
```sh
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.

### Redline with tracked changes
```sh
docx track-changes contract.docx on       # turn tracking on (doc-level)
docx replace contract.docx "Net 90" "Net 30"   # now auto-emits <w:ins>/<w:del>
docx edit --at p12:0-40 contract.docx --text "…" --track   # or redline one edit
docx track-changes list contract.docx     # the tcN handles
docx read contract.docx --current         # view redlines as CriticMarkup
docx track-changes accept contract.docx --at tc3   # or --all / reject
```

### Comment on clauses
```sh
docx comments add contract.docx --anchor "limitation of liability" --text "Cap is too low."
docx comments list contract.docx
docx comments reply contract.docx --at c0 --text "Agreed, raising to \$5M."
docx comments resolve contract.docx --at c0
```

### Read / extract
```sh
docx read FILE            # Markdown (default; tracked changes shown accepted-clean)
docx read FILE --ast      # lossless JSON AST
docx find FILE --batch queries.jsonl --json   # many text/format queries, one read
docx wc FILE              # word count (whole doc or a slice)
docx outline FILE         # headings as a locator tree
docx diff FILE --against OLD.docx   # what changed vs another version (snapshot OLD first)
```

### Build from scratch / verify layout
```sh
docx create out.docx --from draft.md      # GFM + math + CriticMarkup + inline HTML
docx render FILE --out pages/             # PNG per page — only when LAYOUT is the question
```

## 4. Apply many changes from one read — `--batch`

`edit`, `insert`, `replace`, `delete`, and the `comments` verbs take
`--batch FILE.jsonl` (one JSON change per line; `-` reads stdin). Every locator
in the batch addresses the document **as read**, so ids stay valid across the whole
batch — one read, one write, no re-reading between changes. Keys mirror the
command's flags. This is the right tool for filling a form or applying a review.

## 5. Output & safety contract

- **Exit code is the success signal:** `0` ok, `1` error, `2` usage, `3`
  not-found. Every command also prints a one-line text confirmation — you never
  have to re-read just to learn whether a mutation landed.
- Mutators overwrite `FILE` **in place** (git is your history). `-o/--output PATH`
  writes a copy instead; `--dry-ru