officecli-docx

name officecli-docx description Use this skill any time a .docx file is involved -- as input, output, or both. This includes: creating Word documents, reports, letters, memos, or proposals; reading, parsing, or extracting text from any .docx file; editing, modifying, or updating existing documents; working with templates, tracked changes, comments, headers/footers, or tables of contents. Trigger whenever the user mentions 'Word doc', 'document', 'report', 'letter', 'memo', or references a .docx filename. OfficeCLI DOCX Skill Setup If officecli is missing: macOS / Linux : curl -fsSL https://d.officecli.ai/install.sh | bash Windows (PowerShell) : irm https://d.officecli.ai/install.ps1 | iex Verify with officecli --version (open a new terminal if PATH hasn't picked up). If install fails, download a binary from https://github.com/iOfficeAI/OfficeCLI/releases . ⚠️ Help-First Rule This skill teaches what good docx looks like, not every command flag. When a property name, enum value, or alias is uncertain, consult help BEFORE guessing. officecli help docx # List all docx elements officecli help docx <element> # Full element schema (e.g. paragraph, field, numbering, watermark, toc) officecli help docx <verb> <element> # Verb-scoped (e.g. add field, set section) officecli help docx <element> --json # Machine-readable schema Help is pinned to the installed CLI version. When this skill and help disagree, help is authoritative . Mental Model A .docx is a ZIP of XML parts ( document.xml , styles.xml , numbering.xml , header*.xml , footer*.xml , comments.xml , …). Everything the user sees — headings, tables, page numbers, TOC, tracked changes — is XML inside that ZIP. officecli gives you a semantic-path API ( /body/p[1]/r[2] ) over it, so you almost never touch raw XML; when you must, use raw-set (see the XML appendix). Shell & Execution Discipline docx paths contain [] ; some prop values contain $ . Both are shell metacharacters. Escaping happens at three layers — keep them separate. Shell. ALWAYS quote element paths: "/body/p[1]" , not /body/p[1] (zsh/bash glob [N] ). Single-quote any value containing $ : --prop text='$50M' — at any length, the whole value inside one pair of single quotes. Unquoted $50M is stripped to M ; mixing '…$var…' and "…$50…" on one long string is where the $50 silently vanishes. CLI ( text= ). The two-char escapes \n and \t ARE interpreted in --prop text= — \n becomes a <w:br/> soft line break, \t a <w:tab/> — consistently across docx / pptx / xlsx. Double them ( \\n ) for a literal backslash-n (rarely wanted). This applies to row-level table c1…cN shortcuts too ( \n → <w:br/> within the cell). JSON (batch). A real newline can also be passed as "\n" in the JSON string of a batch heredoc; same result. If in doubt, view text after writing and compare character-for-character. Incremental execution. officecli mutates the file on every call. Run commands one at a time and check each exit code — a 50-command script that fails at command 3 cascades silently. After any structural op (new style, table, TOC, section break) run get on it before stacking more. Open/save lifecycle: officecli open <file> at the start, officecli save <file> at the end to flush to disk — save only writes and leaves the resident warm for follow-up edits; reach for officecli close <file> only to release the resident on a one-shot handoff. Both are always safe (never error or lose work). For many paragraphs of one style, use batch (one pass for the whole array). Flush only at the non-officecli boundary: officecli's own reads always see your edits; run save / close only before a non-officecli program reads the file (python-docx, Word, a renderer, delivery). $FILE convention. All commands use "$FILE" — set it once ( FILE="your-doc.docx" ). Never copy a literal doc.docx / review.docx into output — always substitute your actual target. Requirements for Outputs Deliverable standards every document MUST meet — know these before reaching for a command. Clear hierarchy. Every non-trivial document has Title → Heading 1 → Heading 2 → body, not a wall of unstyled Normal paragraphs. If view outline shows one flat list, the hierarchy is missing. Explicit heading sizes (Word default style sizes drift between templates): H1 ≥ 18pt (20pt for long reports), H2 = 14pt bold, H3 = 12pt bold, body = 11–12pt, line spacing 1.15–1.5x. Prefer style=Heading1 over inline sizes so a retheme touches the definition once — but set explicit sizes when you can't trust the template's styles. One body font, one accent. One readable body font (Calibri, Cambria, Georgia, Times New Roman); accent color for heading emphasis or table headers, not rainbow formatting. Spacing through properties. Use spaceBefore / spaceAfter on paragraphs. Rows of empty paragraphs break pagination and are flagged by view issues . Typographic quality. New content uses curly quotes ( ' ' " " ), not ASCII — Unicode directly or XML entities ( &#x2018; / &#x2019; / &#x201C; / &#x201D; ) inside raw-set . En-dash – for ranges ( 2024–2026 ), em-dash — for parenthetical breaks. Headers, footers, page numbers on any document > 1 page. Page numbers go through a live PAGE field ( --prop field=page ), never the literal text "Page 1" — the CLI injects <w:fldChar> for you (see Headers & Footers). Preserve existing templates. When editing a file that already has a look, match it — existing conventions override these guidelines. Visual delivery floor (applies to EVERY document) Before declaring done, run officecli view "$FILE" html and Read the returned HTML path to confirm ALL of these: No placeholder tokens rendered as data. $xxx$ , {var} , {{name}} , <TODO> , lorem , xxxx must never appear in a heading, body, cover, TOC, caption, header, or footer. A literal {name} meant for a human to fill belongs inside a visible instruction paragraph ("Replace {name} before sending"), never as finished content. No truncated titles or overflowing cells. Widen the column or set wrapText rather than trimming content. TOC present when the document has 3+ headings ( --type toc ). Cover page ≥ 60% filled, last page ≥ 40% filled. Pad a thin cover with subtitle / author / date / scope / key highlights; pad a "Thank you" last page with conclusion / next steps / contact / legal. No \$ , \t , \n literals in document text. If view text shows these, a shell-escape layer leaked — delete the paragraph and re-enter it. If any fails, STOP and fix before declaring done. Common Workflow Six steps. Every non-trivial build follows this shape. Open the file. officecli open "$FILE" (resident default). New file: officecli create "$FILE" first. Orient. Existing file: officecli view "$FILE" outline — heading tree, section count, whether a TOC / watermark / tracked changes already exist. Never edit blind. Build incrementally. Structural first, content next, formatting last: styles & numbering defs → sections / page setup → headings & body → tables / images / fields / TOC → headers / footers → comments. After each structural op, get it back before stacking on top. Format to spec. Explicit heading sizes, spacing, widths, alignment, tabs, list indents — formatting is part of the deliverable, not optional polish. Save, then trust structure over cached text. officecli save "$FILE" writes the XML. TOC / PAGE / NUMPAGES / SEQ / PAGEREF fields carry cached values that may be stale or empty until a human recalculates (F9 in Word). Confirm fields exist ( get --depth 3 finds <w:fldChar> ) rather than trusting the visible text. QA — assume there are problems. You are done after one fix-and-verify cycle finds zero new issues, not when your last command exited 0. See QA. Quick Start Minimal viable docx: a heading, a body paragraph, a subheading, and a footer with a live page-number field. Adapt, don't copy-paste — your file, your content. FILE= "review.docx" officecli create " $FILE " officecli open " $FILE " officecli add " $FILE " /body -- type paragraph --prop text= "Q4 2026 Review" --prop style=Heading1 --prop size=20pt --prop bold= true --prop spaceAfter=12pt officecli add " $FILE " /body -- type paragraph --prop text= "Revenue grew 18% year-over-year, ahead of plan." --prop size=11pt --prop spaceAfter=8pt officecli add " $FILE " /body -- type paragraph --prop text= "Key Drivers" --prop style=Heading2 --prop size=14pt --prop bold= true --prop spaceBefore=12pt --prop spaceAfter=6pt officecli add " $FILE " /body -- type paragraph --prop text= "Enterprise renewals, upsell, and a new EMEA region." --prop size=11pt officecli add " $FILE " / -- type footer --prop type =default --prop size=9pt --prop text= "Page " --prop field=page officecli set " $FILE " "/footer[1]/p[1]" --prop align=center officecli save " $FILE " officecli validate " $FILE " Verified: validate returns no errors found ; get /footer[1] --depth 3 shows the 5-run PAGE field chain (begin / instrText / separate / cached value / end). Reading & Analysis Start wide, then narrow. outline tells you what's already there; jump into view text / get / query once you know where to look. officecli view " $FILE " outline # heading tree, section count, table/image counts, watermark, tracked-changes presence — orient here first officecli view " $FILE " html # Read the returned HTML path: first visual check after a batch of edits (hierarchy, empty-para spacing, missing TOC) officecli view " $FILE " text --start 1 --end 80 # text for content QA; paths shown as [/body/p[N]] so you can jump back with get officecli view " $FILE " annotated # values + style/font/size + warnings per run officecli view " $FILE " stats # paragraph counts, font usage, style distribution officecli view " $FILE " issues # empty paras, missing alt text, spacing anomalies officecli watch "$FILE" keeps a live preview running for the human user to open at their discretion — agent self-check uses view html . Final visual verification is the user opening the .docx in Word / WPS / Pages. Inspect one element. XPath-style semantic paths (1-based). Always quote — shells glob [N] . Use [last()] (with parens) for the last element; [last] errors. Add --json for machine output. officecli get " $FILE " / # document root: metadata, page setup officecli get " $FILE " "/body/p[1]" # one paragraph officecli get " $FILE " "/body/p[1]/r[1]" # one run (character-level formatting) officecli get " $FILE " "/body/tbl[1]" --depth 3 # table with rows and cells officecli get " $FILE " "/footer[1]" --depth 3 # footer — check for fldChar officecli get " $FILE " "/styles/Heading1" # style definition officecli get " $FILE " /numbering --depth 2 # numbering abstractNum + num bindings Query across the document. CSS-like selectors, for systematic checks rather than hand-walking. Operators: = , != , ~= (contains), >= , <= , [attr] (exists). Full reference: officecli query --help . officecli query " $FILE " 'paragraph[style=Heading1]' # all H1s officecli query " $FILE " 'p:contains("quarterly")' # text match officecli query " $FILE " 'p:empty' # empty paragraphs (clutter) officecli query " $FILE " 'image:no-alt' # accessibility gaps officecli query " $FILE " 'paragraph[size>=24pt]' # numeric comparison officecli query " $FILE " 'field[fieldType!=page]' # fields other than PAGE query --json wraps results in .data.results[] — jq '.data.results | length' to count. Large documents. Navigate by heading with view outline and jump with query ; don't dump the whole body into context. Creating & Editing Verbs: add (new element), set (change a prop), remove , move , swap , batch , raw-set (last-resort XML). Ninety percent of a build is paragraphs, runs, tables, a couple of images, a TOC, and a footer. Paragraphs, runs, styles A paragraph ( p ) is a block; a run ( r ) is a span of consistent character formatting inside it. Set paragraph-level props (style, alignment, spacing, indent) on the p ; set font / size / color / bold on the r . officecli add " $FILE " /body -- type paragraph --prop text= "Executive Summary" --prop style=Heading1 --prop size=18pt --prop bold= true --prop spaceAfter=12pt officecli set " $FILE " "/body/p[1]/r[1]" --prop color=1F4E79 Use spaceBefore / spaceAfter for vertical spacing — never chains of empty paragraphs. For left indent use --prop indent=720 (twips), firstLineIndent=360 for first line, hangingIndent=720 for hanging; leading spaces fire view issues . Tables Tables are /body/tbl[N] with rows tr[N] and cells tc[N] . Add with row/column counts, then fill. officecli add " $FILE " /body -- type table --prop rows=4 --prop cols=3 --prop width=100% officecli set " $FILE " "/body/tbl[1]/tr[1]" --prop header= true --prop c1=Quarter --prop c2= "Revenue" --prop c3= "Growth" officecli set " $FILE " "/body/tbl[1]/tr[1]/tc[1]/p[1]/r[1]" --prop bold= true Row-level set supports height , header , and c1 / c2 / … / cN text shortcuts ( cN generalises to any column count). Cell formatting (bold, fill, color) goes on the cell's paragraph / run — not row-level. For per-cell borders, set cell-level border.* on the tc ( --prop border.bottom="single;6;000000;0" ), or paragraph-level pbdr.* on the inner paragraph. Horizontal rule = a paragraph bottom border, never a 1-row table. A table-as-divider renders as an empty min-height box (worst in headers/footers). Use pbdr.bottom ( STYLE;SIZE;COLOR ) on the paragraph instead: officecli set " $FILE " "/body/p[3]" --prop pbdr.bottom= "single;6;2E75B6" Lists (bullets, numbered, multi-level) For single-level bullets/numbers, set listStyle on the paragraph ( listStyle is a paragraph prop, NOT a run prop — common mistake): officecli add " $FILE " /body -- type paragraph --prop text= "First item" --prop listStyle=bullet For multi-level (legal-style 1 / 1.1 / 1.1.1), add an abstractNum , then a num , then reference the numId per paragraph: