|
| 1 | +# TAGLINE |
| 2 | + |
| 3 | +Read, edit, and comment on .docx files from the command line with full format fidelity |
| 4 | + |
| 5 | +# TLDR |
| 6 | + |
| 7 | +**Read a document** as Markdown with structural locators |
| 8 | + |
| 9 | +```docx read document.docx``` |
| 10 | + |
| 11 | +**Create a new document** from Markdown |
| 12 | + |
| 13 | +```docx create report.docx --from content.md --title "Q3 Report"``` |
| 14 | + |
| 15 | +**Replace text** while preserving formatting and tabs |
| 16 | + |
| 17 | +```docx replace invoice.docx "Amount Due" "$1,250.00"``` |
| 18 | + |
| 19 | +**Find text and add a comment** at the match |
| 20 | + |
| 21 | +```docx comments add contract.docx --at "$(docx find contract.docx 'liability' | head -1)" --text "Review this clause with legal."``` |
| 22 | + |
| 23 | +**Turn on tracked changes** and make a redlined edit |
| 24 | + |
| 25 | +```docx track-changes contract.docx on |
| 26 | +docx replace contract.docx "reasonable efforts" "best efforts" --track``` |
| 27 | +
|
| 28 | +**Render pages visually** for layout verification |
| 29 | +
|
| 30 | +```docx render proposal.docx --out pages/``` |
| 31 | +
|
| 32 | +**Install standalone** (verified binary) |
| 33 | +
|
| 34 | +```curl -fsSL https://raw.githubusercontent.com/kklimuk/docx-cli/main/install.sh | sh``` |
| 35 | +
|
| 36 | +# SYNOPSIS |
| 37 | +
|
| 38 | +**docx** _<command>_ [options] |
| 39 | +
|
| 40 | +# DESCRIPTION |
| 41 | +
|
| 42 | +**docx** is a command-line tool for AI agents and humans to read, edit, comment on, and review Microsoft Word (.docx) documents without losing formatting or breaking files that Word can open. |
| 43 | +
|
| 44 | +It works by mutating the underlying OOXML directly instead of round-tripping through lossy models or re-serializing the document. Agents receive a stable locator system (e.g. `p3:5-20`, `t1:r0c2:p0`) plus an annotated Markdown view, allowing precise, safe edits. |
| 45 | +
|
| 46 | +Key capabilities include: |
| 47 | +
|
| 48 | +- Read as Markdown or lossless JSON AST |
| 49 | +- Create, insert, edit, delete, replace content |
| 50 | +- Add and manage comments, footnotes, endnotes, headers/footers, images, hyperlinks, tables |
| 51 | +- Full tracked-changes (redline) support with accept/reject |
| 52 | +- Style management and page geometry |
| 53 | +- Visual page rendering via Word or LibreOffice |
| 54 | +
|
| 55 | +The tool is designed so that `docx <command> --help` is always authoritative. It ships with an optional Agent Skill for Claude Code, Codex, and similar harnesses. |
| 56 | +
|
| 57 | +# LOCATORS |
| 58 | +
|
| 59 | +Locators address paragraphs (`pN`), tables (`tN`), sections (`sN`), cell paragraphs, character spans (`pN:S-E`), and entity IDs (`cN` for comments, `imgN`, etc.). Use `docx info locators` for the full grammar. |
| 60 | +
|
| 61 | +# COMMON COMMANDS |
| 62 | +
|
| 63 | +**create** FILE [--from PATH.md | --text "..."] [--title T] [--author A] |
| 64 | +
|
| 65 | +> Create a new .docx. `--from` accepts the same Markdown dialect used by insert/edit. |
| 66 | +
|
| 67 | +**read** FILE [--from LOC] [--to LOC] [--ast] [--comments] [--accepted|--current|--baseline] |
| 68 | +
|
| 69 | +> Render body as Markdown (with locator annotations) or JSON AST. Supports tracked-change views. |
| 70 | +
|
| 71 | +**edit** / **insert** / **delete** / **replace** FILE ... |
| 72 | +
|
| 73 | +> Mutate content at locators or via batch JSONL. Replace keeps existing run formatting. |
| 74 | +
|
| 75 | +**find** FILE QUERY [--regex] [--all] |
| 76 | +
|
| 77 | +> Return locators for text or formatting matches (for feeding to --at). |
| 78 | +
|
| 79 | +**track-changes** on|off|list|accept|reject FILE |
| 80 | +
|
| 81 | +> Control and review revisions. |
| 82 | +
|
| 83 | +**comments** / **images** / **tables** / **styles** / **sections** ... |
| 84 | +
|
| 85 | +> Manage the corresponding document parts. |
| 86 | +
|
| 87 | +**render** FILE [--out DIR] |
| 88 | +
|
| 89 | +> Produce page images for visual verification of layout. |
| 90 | +
|
| 91 | +**wc** / **outline** / **info** |
| 92 | +
|
| 93 | +> Word counts, heading trees, and reference material (schema, locators). |
| 94 | +
|
| 95 | +# CAVEATS |
| 96 | +
|
| 97 | +There is no undo inside the CLI — use git or copies. Edits that would corrupt the file (e.g. deleting a referenced relationship) are refused. Rendering requires Microsoft Word (macOS/Windows) or LibreOffice. Batch operations address the document snapshot at read time. |
| 98 | +
|
| 99 | +The Markdown dialect preserves most formatting but literal text channels (`--text-file`) exist for content that GFM would alter. |
| 100 | +
|
| 101 | +# RESOURCES |
| 102 | +
|
| 103 | +```[Source code](https://github.com/kklimuk/docx-cli)``` |
| 104 | +
|
| 105 | +```[Homepage](https://kklimuk.github.io/docx-cli/)``` |
| 106 | +
|
| 107 | +```[Documentation](https://kklimuk.github.io/docx-cli/)``` |
| 108 | +
|
| 109 | +<!-- verified: 2026-07-07 --> |
0 commit comments