Word (.docx) Manipulation Features in OfficeCLI: Complete API Reference

OfficeCLI provides a comprehensive, AI-friendly command-line API for Word documents, offering path-based element addressing, three-tier operation layers, and support for everything from basic text styling to complex LaTeX equations, diagrams, and watermarks.

OfficeCLI is an open-source document automation framework that exposes rich Word (.docx) manipulation features through a unified CLI interface. The WordHandler class drives all operations, implementing IDocumentHandler to provide both structural queries and live HTML rendering capabilities. Whether you need to insert mathematical expressions, manipulate virtual table columns, or batch-process hundreds of documents, OfficeCLI delivers deterministic access to every OOXML element via human-readable paths.

Core Architecture and Operation Layers

The Word manipulation engine in OfficeCLI is built on a three-layer model that separates read operations from structural DOM manipulation and raw XML access.

L1 (Read Layer) — view commands return plain text, hierarchical outlines, annotated views, or HTML screenshots for AI consumption.

L2 (DOM Layer) — The get, query, set, add, remove, move, and swap commands operate on OOXML parts using stable path syntax such as /body/p[3]/r[2]. This path-based addressing allows agents to navigate documents without handling raw XML.

L3 (Raw XML Layer) — raw and raw-set commands provide fallback access to any document part via XPath for edge cases not covered by the DOM abstraction.

In src/officecli/Handlers/WordHandler.cs, the handler implements a unified render model that powers the HTML preview engine, enabling both programmatic manipulation and visual verification of document changes.

Supported Document Elements and Formatting

OfficeCLI supports a complete range of Word document features, from basic typography to complex layout structures.

Text Formatting and Paragraph Control

The tool provides granular control over character and paragraph formatting through the run and paragraph objects.

• Runs — Control underline colors, half-point positioning, font sizes, bold/italic toggles, and character-based indents.
• Paragraphs — Configure frame properties (framePr), tab stops (tabs), and indentation settings.
• Styles — Full style hierarchy resolution with an O(1) style-lookup cache (_styleByIdCache in WordHandler.cs) for performance-critical documents with heavy styling.

Internationalization and RTL Support

OfficeCLI handles complex global document requirements through dedicated i18n features:

• Per-script font slots and BCP-47 language tags.
• Cascading direction=rtl support for right-to-left scripts.
• Locale-aware page numbering with automatic RTL enablement via create --locale.
• RTL gutter handling in section breaks.

Tables and Layout Manipulation

Table operations go beyond basic insertion, offering virtual column management:

• Virtual column operations — Add, remove, move, or copy columns without re-creating the entire table.
• Horizontal cell merging and flexible cell addressing via paths like /body/p[2]/tbl[1]/row[1]/cell[2].
• Automatic size calculations for inserted content.

Rich Media, Shapes, and Objects

Images — Insert PNG, JPG, GIF, and SVG with automatic size handling and explicit width/height properties.

Textboxes and Shapes — Configure rotation, text direction (eaVert, vert270), gradients, shadows, and opacity at the shape level. The [WordHandler.Helpers.TextEffect.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.Helpers.TextEffect.cs) file handles advanced visual effects.

Equations — Convert LaTeX markup to Office Math Markup Language (OMML) using the --type equation flag with latex="..." properties.

Diagrams — Render Mermaid-based flowcharts and sequence diagrams as native editable shapes or static PNGs.

Charts — Embed OfficeCLI-compatible charts (pie, bar, line) directly into document bodies.

Document Navigation and Metadata

Headers and Footers — Programmatically create and modify repeating page elements across sections.

Table of Contents (TOC) — Automatically generate and refresh TOCs with page-number updates.

Bookmarks — Create named anchors for cross-references throughout the document.

Comments — Insert threaded comments with author attribution, text content, and reply chains.

Footnotes — Create inline footnotes with full formatting support.

Hyperlinks — Add and edit external links with optional display text overrides.

Security and Presentation Features

Watermarks — Apply text or image watermarks to the document body with configurable opacity levels (e.g., watermark.opacity=0.2).

Sections — Manage section breaks, page layout settings, and column configurations.

Performance Optimizations

The Word handler includes specific architectural optimizations for large-scale document processing:

• Style caching — The _styleByIdCache dictionary (lines 21–76 of WordHandler.cs) provides constant-time style lookups, eliminating the O(N) traversal penalty in heavily styled documents.
• Paragraph ID tracking — A _usedParaIds hash-set guarantees unique paragraph identifiers, enabling reliable move and swap operations without ID collisions.
• Deferred saving — The DeferSave flag enables batch processing where hundreds of mutations are applied in-memory and flushed once, reducing O(N²) serialization overhead during complex automation sequences.

Practical CLI Examples

The following commands demonstrate the breadth of Word (.docx) manipulation features available in OfficeCLI:

Create a new document and add a styled heading:

officecli create report.docx
officecli add report.docx /body --type paragraph \
  --prop text="Quarter-End Report" \
  --prop style=Heading1

Insert a table with data and an image:

officecli add report.docx /body/p[2] --type table \
  --prop rows=3 --prop cols=4
officecli set report.docx '/body/p[2]/tbl[1]/row[1]/cell[1]' \
  --prop text="Region"
officecli add report.docx '/body/p[2]/tbl[1]/row[1]/cell[2]' \
  --type image --prop src=assets/logo.png --prop width=3cm

Add LaTeX equations and comments:

officecli add report.docx /body/p[3] \
  --type equation --prop latex="\frac{a}{b}=c"
officecli add report.docx '/body/p[3]/r[1]' \
  --type comment --prop author="Bob" --prop text="Verify the formula"

Apply watermarks and generate previews:

officecli set report.docx /document \
  --prop watermark.text="CONFIDENTIAL" \
  --prop watermark.opacity=0.2
officecli view report.docx html -o preview.html

Summary

• Unified Handler Architecture — The WordHandler in src/officecli/Handlers/WordHandler.cs implements a three-layer API (Read, DOM, Raw XML) for comprehensive document access.
• Path-Based Addressing — Stable human-readable paths (e.g., /body/p[3]/r[2]) eliminate the need for raw XML navigation in common tasks.
• Complete Feature Coverage — Support includes i18n/RTL, virtual table columns, LaTeX equations, Mermaid diagrams, threaded comments, watermarks, and automatic TOC generation.
• Performance Optimizations — O(1) style caching, unique paragraph ID tracking, and deferred saving enable efficient batch processing of large documents.
• AI-Friendly Output — HTML preview generation and JSON-ready responses facilitate integration with automated agents and CI/CD pipelines.

Frequently Asked Questions

How does OfficeCLI handle complex styling in Word documents?

OfficeCLI resolves style hierarchies through a lazily-built cache (_styleByIdCache) inside WordHandler.cs. This provides O(1) lookups for style definitions, making operations on heavily styled documents as fast as those on plain text files. The tool supports full inheritance chains, allowing you to apply base styles like Heading1 while overriding specific properties such as font size or color at the run level.

Can OfficeCLI convert LaTeX equations to Word format?

Yes. OfficeCLI converts LaTeX markup to Office Math Markup Language (OMML) during insertion. Use the command officecli add <file> <path> --type equation --prop latex="<your-latex>" to embed mathematical expressions. The conversion happens server-side without requiring Microsoft Word to be installed, making it suitable for automated document generation pipelines.

What is path-based addressing in OfficeCLI?

Path-based addressing is a stable navigation system where every OOXML element (paragraphs, runs, tables, cells) is reachable via a human-readable path like /body/p[3]/r[2]. This abstraction layer, implemented in the DOM tier of WordHandler, allows AI agents and scripts to manipulate document structure without parsing raw XML or dealing with unpredictable element IDs.

How does OfficeCLI optimize performance for large document batches?

The tool implements deferred saving via the DeferSave flag, which keeps mutations in memory until all operations complete, then flushes the document once. Combined with the _styleByIdCache for constant-time style lookups and _usedParaIds tracking for collision-free paragraph IDs, OfficeCLI achieves O(N) complexity for batch operations rather than O(N²) per save cycle.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}