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. Run the delivery gate in "Verify before you deliver" below before handing anything over. preview publishes the HTML, but nothing in this toolchain renders it to an image — see the ceiling statement in that section.

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.
• edit also has an ADDRESSED text surface, set_run_text, under "schema": "docx.edit/2". Use it when you know which run to change rather than which text to find: {"op": "set_run_text", "params": {"at", "expect","text"}}. at names ONE run — the office query path (/docx/body/p[3]/r[2]) or its body-relative form (p[3]/r[2]). expect must equal that run's entire current text, not a substring; a stale expectation refuses rather than editing the wrong run, because addresses are snapshot-relative and a document you read earlier may have moved. text replaces the run's whole text. Setting a run to its own text validates and changes nothing. A script is entirely set_run_text or entirely another family — never mixed. Prefer this over replace_text when the same literal occurs more than once, or when the text you want to change is short and ambiguous.
• Addressed edits refuse on content whose edit would not survive. This is the surface's main safety property and the most common surprise. A refusal here is not a defect to retry around — it means the write would have been lost, misattributed, or contradicted, and nothing downstream could have told you. set_run_text refuses a run that:
  • holds a field's cached result (a PAGE, DATE, TOC, REF or MERGEFIELD answer). Word recomputes it and discards your text. Edit what the field asks, or flatten the field, rather than its answer.
  • sits in a tracked insertion (w:ins). Writing there makes the document record that the insertion's named author wrote your words. Resolve the revision first with accept_revision, then edit the resulting plain text.
  • sits in a content control (w:sdt). A data-bound one is repopulated from its XML part on open. Change the bound data instead. Plain-text controls refuse too — the reader cannot yet tell them apart, and refusing the safe case is the deliberate side to err on.
  • sits in textbox content or a markup-compatibility fallback, where the same text is commonly stored twice and editing one copy leaves the other disagreeing.
  • owns suppressed content the reader could not model — a picture, an unmappable symbol, an unrecognised element — because replacing the run would leave content beside your text that you never saw.
  • sits in a logical paragraph joined from several physical ones (a deleted paragraph mark joins them), where one address does not name one place in the file.
  • spans a hyperlink boundary, where the rewrite would silently grow or shrink what is linked. Each refusal names the construct it found. Read the message: it tells you which of the above you hit, and therefore what to do instead.
• 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"}}
]}

Verify before you deliver

Minimum cycle before "done"

1. office validate FILE --json — the schema gate. .data.error_count must be 0.
2. office issues FILE --json — bounded actionable findings. This command exits 0 while reporting them, so read .data.findings, never $?.
3. office text FILE --json — the words a reader actually gets: typos, leaked {{placeholders}}, \$/\t/\n escape artefacts. One call covers body paragraphs, table cells, and comment bodies.
4. office outline FILE --json — the structure text cannot show you. On a DOCX: .data.headings[].level for hierarchy, .data.comments[] for open threads, .data.counts.insertions/.deletions for pending redline.

office outline FILE.docx --json |
  jq '[.data.headings[].level] as $l
      | [range(1; $l|length) | select($l[.] - $l[.-1] > 1)] | length'

Delivery gate

# Two shims so the gate runs as written.
office()    { moonx bobzhang/office "$@"; }
xlsx_lint() { moonx bobzhang/mbtexcel/cmd/xlsx lint "$@"; }

FILE="report.docx"          # the file you are about to hand over

fail=0
reject() { fail=$((fail + 1)); printf 'REJECT  %s\n' "$*"; }

FMT=$(office identify "$FILE" --json | jq -r 'select(.success).data.format // empty')
[ -n "$FMT" ] || reject "0 identify: not a readable DOCX/XLSX package"

# Gate 1 - schema. Test `.success` first: a package that fails this early
# carries an `error` object and no `.data` at all, so `.data.error_count`
# would be null, and `null` is not `0`-and-not-an-error to a naive test.
if office validate "$FILE" --json | jq -e '.success and .data.error_count == 0' >/dev/null; then
  echo "OK      1 schema"
else
  reject "1 schema"
  office validate "$FILE" --json | jq -c '.error // .data.findings[]'
fi

# Gate 2 - actionable findings. `issues` exits 0 while reporting them, so the
# finding count is the gate and `$?` is not.
if office issues "$FILE" --json | jq -e '.success and (.data.findings | length) == 0' >/dev/null; then
  echo "OK      2 issues"
else
  reject "2 issues"
  office issues "$FILE" --json | jq -c '.error // .data.findings[]'
fi

# Gate 3 - one complete text scan, captured once. Gate 4 means nothing unless
# this succeeded AND covered the whole document: a truncated or failed scan
# yields an empty stream, and an empty stream matches no leak pattern.
TEXT=$(office text "$FILE" --limit 10000 --json)
if printf '%s' "$TEXT" | jq -e '.success and .data.truncated == false' >/dev/null; then
  echo "OK      3 text scan complete"

  # Gate 4 - leaked template tokens and shell-escape artefacts. `grep -c`
  # prints a count on every path, including the empty stream, so it cannot
  # false-PASS the way `grep -q` silently does.
  LEAK_RE='\{\{[^}]*\}\}|\\[nt]|\\\$|<TODO>|TODO|TBD|FIXME|[Ll]orem ipsum'
  LEAK=$(printf '%s' "$TEXT" | jq -r '.data.entries[].text' | grep -cE "$LEAK_RE" || true)
  if [ "${LEAK:-1}" -eq 0 ]; then
    echo "OK      4 no leaked tokens"
  else
    reject "4 leaked token/escape artefact on $LEAK line(s)"
    printf '%s' "$TEXT" | jq -r '.data.entries[] | "\(.path)\t\(.text)"' | grep -E "$LEAK_RE"
  fi
else
  reject "3 text scan incomplete - page with --offset, or scope with --under"
  reject "4 not evaluated: gate 3 produced no trustworthy text"
  printf '%s' "$TEXT" | jq -c '.error // (.data | {truncated, returned, matched_total})'
fi

if [ "$FMT" = docx ]; then
  # Gate 5 - unresolved comment threads. An unresolved comment spells no
  # `done` key at all, so the test is `!= true` and never `== false`.
  if office outline "$FILE" --json | jq -e '.success and ([.data.comments[] | select(.done != true)] | length) == 0' >/dev/null; then
    echo "OK      5 comment threads resolved"
  else
    reject "5 unresolved comment thread(s)"
    office outline "$FILE" --json | jq -c '.error // (.data.comments[] | select(.done != true))'
  fi

  # Gate 6 - pending tracked changes. `text` renders the accepted view, so
  # redline is invisible to every other check in this gate.
  if office outline "$FILE" --json | jq -e '.success and .data.counts.insertions == 0 and .data.counts.deletions == 0' >/dev/null; then
    echo "OK      6 no pending revisions"
  else
    reject "6 unaccepted tracked changes"
    office outline "$FILE" --json | jq -c '.error // (.data.counts | {insertions, deletions})'
  fi
fi

if [ "$FMT" = xlsx ]; then
  # Gate 7 - formulas, run unconditionally. A formula-free workbook reports
  # finding_count 0 anyway, and no `=` heuristic over `text` is reliable: a
  # formula carrying a cached value surfaces as that value, not its source.
  if xlsx_lint "$FILE" | jq -e '.finding_count == 0' >/dev/null 2>&1; then
    echo "OK      7 formulas evaluate clean"
  else
    reject "7 formula error(s)"
    xlsx_lint "$FILE" 2>&1 | jq -c '.findings[]' 2>/dev/null || xlsx_lint "$FILE" 2>&1
  fi
fi

if [ "$fail" -eq 0 ]; then
  echo "GATE PASS - structurally verified. NOT visually verified."
else
  echo "GATE FAIL - $fail check(s) rejected. Do not deliver."
fi
# Last command on purpose: it sets the exit status without `exit`, so
# `bash gate.sh && deliver` cannot deliver a rejected document, and pasting
# the block into an interactive shell does not close it.
[ "$fail" -eq 0 ]

• .data can be absent entirely. A package that fails to open returns {"success": false, "error": {...}} with no .data. jq -e '.success and...' rejects that; jq '.data.error_count' alone yields null.
• An empty stream matches nothing. If text fails, piping its output into grep -q finds no tokens and looks like a pass. Gate 4 therefore runs only inside gate 3's success branch, and counts with grep -c.
• Exit codes are not findings. issues and xlsx lint both exit 0 while reporting problems. Only the counts decide.

What this gate does not cover

• pagination — page count, page breaks, orphaned headings, blank pages
• layout and fit — column widths, truncated cells, overflowing tables, margins
• typography as seen — font substitution, actual rendered sizes, spacing rhythm
• anything a viewer computes at open time, including field results such as PAGE or a table-of-contents page column

Legacy-only fallbacks