OfficeCLI Three-Layer Architecture: L1 Views, L2 DOM, and L3 Raw XML Explained

OfficeCLI implements a progressive-complexity three-layer architecture where L1 provides read-only semantic views, L2 manipulates structured DOM elements with high-level commands, and L3 enables direct OOXML editing for unsupported edge cases.

The iOfficeAI/OfficeCLI repository introduces a three-layer architecture designed to optimize token consumption and reduce error rates when AI agents interact with Office documents. This progressive-complexity model, documented in SKILL.md and README.md, allows users to start with abstract, high-level operations and only descend to verbose low-level commands when necessary, balancing ease of use with granular control over OOXML documents.

Layer 1 (L1) – High-Level Views for Document Inspection

L1 focuses on read-only operations that extract semantic meaning without modifying the underlying document structure. These commands are handled by the dispatch logic in src/officecli/Program.cs, which routes view requests to the appropriate document handler.

Available L1 View Commands

The view verb supports multiple output formats for different analysis needs:

• view text – Extracts plain text content from the document body
• view annotated – Text with inline markup for comments and revision marks
• view outline – Hierarchical structure of headings and sections
• view html / view svg – Visual renderings for browser-based inspection
• view stats – Document metadata, word counts, and structural statistics
• view issues – Validation reports and compatibility warnings

When to Use L1 Views

Use L1 commands when you need to understand document content before deciding on edits. According to the repository documentation, these views return concise, human-readable output that agents can parse quickly, abstracting away the underlying XML complexity and minimizing token usage during initial analysis.

officecli view text report.docx
officecli view html report.docx --output report.html

Layer 2 (L2) – DOM Editing and Structured Operations

L2 provides element-level manipulation through a Document Object Model (DOM) interface. This layer is implemented primarily in src/officecli/Handlers/WordHandler.cs for Word documents, with equivalent handlers for other Office formats.

Core DOM Manipulation Verbs

The L2 layer supports full CRUD operations via specific CLI verbs:

• get – Retrieve properties of specific elements
• query – Search documents using CSS-like selectors (e.g., query "p[style=Heading1]")
• set – Modify existing element properties (e.g., set /body/p[1] --prop bold=true)
• add – Insert new elements (e.g., add /slide[2] --type shape --prop text="Hello")
• remove – Delete elements from the document tree
• move – Relocate elements to different positions
• swap – Exchange positions of two elements

Dotted-Attribute Syntax

The DOM layer uses dotted-attribute notation to map high-level properties to schema-valid XML without manual namespace handling. This abstraction prevents common OOXML errors while maintaining precision.

officecli set report.docx /body/p[3] --prop font.size=14
officecli set report.docx /body/p[1] --prop pbdr.top=single
officecli add report.docx /body --type table --prop rows=5 cols=3

These commands automatically translate to the appropriate Open XML markup, handling namespace complexities and schema validation internally.

Layer 3 (L3) – Raw XML Fallback for Edge Cases

When L2's high-level schema cannot express a specific attribute or element structure, OfficeCLI provides L3 for verbatim OOXML manipulation. This layer serves as an escape hatch when the DOM abstraction proves insufficient.

Raw XML Commands

The L3 layer exposes two primary commands for direct markup access:

• raw-get – Retrieve exact XML fragments from specific package parts (e.g., raw-get /word/document.xml)
• raw-set – Inject arbitrary XML directly into document parts, bypassing the DOM validation layer

officecli raw-set report.docx /word/document.xml --xml "<w:p><w:r><w:t>Raw text</w:t></w:r></w:p>"
officecli raw-set report.docx /docProps/custom.xml --xml "<custom:property name=\"MyProp\" fmtid=\"{...}\">value</custom:property>"

Risks and Considerations

Because L3 bypasses schema validation and type checking, you must manually manage XML namespaces (w:, custom:, etc.) and ensure OOXML validity. The SKILL.md documentation emphasizes using L3 as a last resort when the DOM layer lacks required functionality, as improper XML can corrupt the document package.

Architecture Flow and Token Optimization

The three-layer architecture follows a progressive-complexity model defined in the central skill documentation. The system encourages agents to prefer higher layers because they generate significantly fewer tokens and reduce error rates compared to raw XML manipulation.

The command dispatch logic in src/officecli/Program.cs enforces this hierarchy by routing verbs to the appropriate handler layer. When a property cannot be expressed via the high-level schema in L2, the system automatically flags the need for L3 fallback, ensuring users only descend to raw XML when absolutely necessary.

Summary

• L1 Views provide read-only semantic extraction via commands like view text and view outline, ideal for document inspection and initial content analysis.
• L2 DOM enables structured editing using verbs like set, add, and query with dotted-attribute syntax, implemented in src/officecli/Handlers/WordHandler.cs for type-safe OOXML generation.
• L3 Raw XML offers direct OOXML manipulation through raw-set and raw-get for edge cases unsupported by the DOM layer, requiring manual namespace management.
• The architecture prioritizes higher layers for token efficiency and reliability, descending to lower layers only when semantic abstraction proves insufficient.

Frequently Asked Questions

What is the difference between L2 DOM and L3 Raw XML in OfficeCLI?

L2 DOM operations use high-level commands with dotted-attribute syntax (e.g., --prop font.size=14) that automatically handle OOXML namespaces and schema validation through WordHandler.cs. L3 Raw XML requires you to write complete XML fragments manually, bypassing validation and requiring explicit namespace management. Use L2 for standard edits and reserve L3 for unsupported edge cases where the DOM schema lacks specific attributes.

When should I use L1 Views instead of L2 DOM operations?

Use L1 Views when you need to inspect or extract content without modifying the document. Commands like view text or view outline are optimized for reading and generate minimal tokens, making them ideal for AI agent context gathering. Switch to L2 only when you need to modify specific elements, such as updating paragraph styles, inserting tables, or restructuring document sections.

How does OfficeCLI handle namespaces in L3 Raw XML mode?

In L3 mode, OfficeCLI does not automatically handle namespaces. You must include proper namespace prefixes and declarations in your XML fragments. When using raw-set on /word/document.xml, you must include the w: prefix for WordprocessingML elements, and any custom document properties require the appropriate custom: namespace schema declarations.

Can I mix L2 and L3 commands in the same OfficeCLI workflow?

Yes, workflows can combine layers strategically. Typically, you would use L1 to inspect the document, L2 for standard modifications, and L3 only for specific fragments requiring raw XML access. However, once you modify a document section with raw-set, subsequent L2 operations on that section may not recognize manual XML changes if they break the expected DOM structure or introduce invalid markup.

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