Office documents through one CLI

moonx bobzhang/office help all --json
moonx bobzhang/office <command> <args...>

The CLI describes itself — prefer that over prose

moonx bobzhang/office help all --json        # every format, command, field, limit
moonx bobzhang/office help schemas --json    # every consumed JSON contract
moonx bobzhang/office help schema ID --json  # one contract, e.g. xlsx.batch/2

Default workflow

1. Discover the surface with help all --json, and help schema ID before authoring any JSON input document.
2. Run identify, then outline --json, before choosing paths or edits.
3. Inspect only what you need with get, text, or query. Reuse the canonical paths the CLI returns; do not invent selectors.
4. For mutations, prefer a separate --out, run --dry-run where supported, and read the transaction preservation report.
5. Read the result back, then run validate and issues. For any XLSX containing formulas, also run the legacy xlsx lint fallback below and require finding_count == 0: newly authored formulas have no cached result, so issues and preview cannot evaluate them. Lint evaluates formula masters but not shared/array slave formulas — treat those slaves as an unresolved residual rather than claiming formula correctness.
6. Generate a preview and visually inspect the HTML before delivery.

Command map

Canonical selectors

/docx/body/p[1]
/docx/body/tbl[1]/tr[1]/tc[2]/p[1]
/docx/comments/comment[id="7"]
/xlsx/workbook
/xlsx/sheet[name="Data"]
/xlsx/sheet[name="Data"]/cell[A1]
/xlsx/sheet[name="Data"]/range[A1:C12]

Mutation contracts

• create is create-new by default; --overwrite explicitly replaces an existing destination. --dry-run validates without publishing.
• XLSX batch consumes xlsx.batch/2; the historical xlsx.batch/1 remains accepted with its exact v1 registry subset. With no --out it rewrites the input after all operations pass; prefer --out when preserving the source matters.
• DOCX batch --format docx consumes docx.batch/2 (and accepts docx.batch/1) and only authors a fresh destination. It does not edit an existing DOCX and does not accept --out.
• template never modifies its template. It substitutes non-executable {{key}} placeholders from flat scalar data and optional marked-row regions into a separate output.
• edit is the literal find & replace surface for an existing DOCX. It consumes docx.edit/1 ({"op": "replace_text", "params": {"find", "replace","occurrence"}}) and publishes a separate output; the input is never touched. find is literal, never a regular expression, and matches across run boundaries. Omitting occurrence replaces every occurrence in document order; occurrence: N replaces only the Nth. Every op is matched against the original snapshot, so two ops whose matches overlap refuse (office.edit.overlapping_matches). A match the byte-span rewriter cannot own — mixed run content, a hyperlink boundary, or a footnote/endnote/comment story — refuses with office.edit.unsupported_context rather than being silently skipped, and an op that finds nothing refuses with office.edit.unmatched_find unless --allow-unmatched is passed.
• edit also RESOLVES tracked changes, through the same docx.edit/1 script: accept_revision and reject_revision with {"id"}, {"author"}, {"type": "ins"|"del"}, or {"all": true}. Spelled selector fields are conjunctive; id is the stable w:id handle outline reports, and ordinal position is never a selector. Accepting an insertion (or rejecting a deletion) unwraps the element and keeps its runs; rejecting an insertion (or accepting a deletion) removes the element and its content. One script is entirely replace_text or entirely revision ops — mixing them is rejected.
• annotate is the preservation-safe existing-DOCX mutation surface. It consumes docx.annotation-batch/1 with comment_add, comment_reply, comment_resolve, and comment_unresolve ops and publishes a separate output. Its ops carry their fields directly, not under a params object — unlike xlsx.batch and docx.batch. comment_add takes anchor: {"at": "/docx/body/p[1]"}, author, and body as an array of strings, plus an optional label that later ops reference via {"label": ...}. Passing params fails with office.annotate.invalid_script. Run office help schemadocx.annotation-batch/1 --json and read its examples before authoring.
• raw replace and raw edit are expert fallbacks. Use --dry-run and a separate --out; semantic commands are safer whenever they can express the task.
• A preservation report is authoritative. Do not infer preservation from the requested operations.
• dump --json is the form accepted by replay. dump --jsonl is a streaming inspection form with a terminal digest, not replay input.
• preview --overwrite and replay --overwrite remove the old destination before staging the replacement; a later write failure can leave it absent. Use a fresh destination, or make and verify a backup before explicit replacement. They do not share the atomic-overwrite guarantee of the transaction-backed mutation commands.

Shapes that are easy to get wrong

{"op": "table", "params": {"header_rows": 1, "rows": [
  [{"text": "Area"}, {"text": "Owner"}],
  [{"text": "Cache"}, {"text": "Dana"}],
  [{"text": "Payments", "col_span": 2}]
]}}

Reviewing a DOCX

office outline FILE --json     # .data.comments[]

{"path": "/docx/comments/comment[id=\"0\"]", "id": "0",
 "author": "Reviewer", "done": true, "anchor": "/docx/body/p[5]"}
{"path": "/docx/comments/comment[id=\"1\"]", "id": "1",
 "author": "Ravi", "done": false, "parent_id": "0"}

# the comment bodies, path-tagged
office text FILE --under '/docx/comments' --json

# one comment in full: every anchor, initials, date, body paragraph count
office get FILE '/docx/comments/comment[id="0"]' --json

{"id": "0", "ordinal": 1, "author": "Reviewer", "done": true,
 "anchors": [{"start": "/docx/body/p[5]", "end": "/docx/body/p[5]"}]}

office outline FILE --json     # .data.counts.insertions / .deletions, .data.revisions[]

{"type": "del", "path": "/docx/body/p[1]", "id": "1",
 "author": "Reviewer", "date": "2026-01-01T00:00:00Z"}
{"type": "ins", "path": "/docx/body/p[1]", "id": "2", "author": "Reviewer"}

{"schema": "docx.edit/1", "ops": [
  {"op": "accept_revision", "params": {"author": "Reviewer"}}
]}

Legacy-only fallbacks