OfficeCLI Three-Layer Architecture (L1/L2/L3): When to Use Each Layer

OfficeCLI organizes document operations into three progressive layers—L1 (read), L2 (DOM edit), and L3 (raw XML)—where you should always prefer higher layers for safety and simplicity.

The three-layer architecture in OfficeCLI provides a structured approach to manipulating Word, Excel, and PowerPoint files through progressive complexity. According to the iOfficeAI/OfficeCLI source code, this design ensures schema safety while giving developers escape hatches for advanced scenarios. Understanding when to use L1, L2, or L3 operations is essential for writing maintainable OpenXML automation scripts.

Understanding the Three-Layer Architecture

OfficeCLI implements a progressive-complexity model that explicitly favors higher layers over lower ones. As documented in SKILL.md, the architecture follows the principle: "L1 (read) → L2 (DOM edit) → L3 (raw XML). Always prefer higher layers."

L1 – Read / Inspect

L1 provides read-only access to documents without modifying the underlying file. Commands in this layer include view, get, and query, which return structured JSON or plain-text representations of document elements.

Use L1 when you need to inspect, analyze, or extract information. This covers scenarios like listing paragraphs in a Word document, reading cell values from an Excel sheet, or fetching presentation statistics. The README.md explicitly states that agents should start with these read-only views before attempting modifications.

L2 – DOM Edit

L2 operates on the document object model (DOM) using high-level, typed attributes. Commands like set, add, and remove modify properties through schema-aware operations (e.g., --prop font.color=red or --prop fill=FF0000).

Prefer L2 for most editing tasks because it guarantees schema safety and maintains low token usage. This layer handles typical formatting, styling, and structural changes—such as updating a shape’s fill color in PowerPoint, setting paragraph styles in Word, or adding rows to Excel sheets—while validating changes against the OpenXML schema.

L3 – Raw XML

L3 drops down to direct XPath/XML manipulation using commands like raw, raw-set, and add-part. This layer applies no schema validation; you work directly with raw OpenXML markup.

Use L3 only as a fallback when L2 cannot express the needed change. Valid scenarios include inserting internal hyperlinks, adding custom XML elements, or handling properties that lack dedicated CLI verbs. The documentation in skills/officecli-docx/SKILL.md emphasizes that this layer bypasses safety checks and should be a last resort.

Code Examples for Each Layer

The following examples demonstrate the progression from read-only inspection to raw XML manipulation across different Office document types.

L1: Read-Only Inspection

# Show document structure outline

officecli view report.docx outline

# Get paragraph 3 as JSON

officecli get report.docx /body/p[3] --json

# Query specific properties

officecli query data.xlsx /Sheet1/Table1 --select "row[Revenue>1000]"

L2: DOM-Based Editing

# Modify a shape's fill color in PowerPoint

officecli set deck.pptx /slide[1]/shape[@id=550950021] \
    --prop fill=FF0000

# Add a new row to an Excel sheet

officecli add data.xlsx /Sheet1 \
    --type row --prop index=5 --prop values="Q1,1000,2000"

# Set paragraph style in Word

officecli set report.docx /body/p[2] \
    --prop style=Heading1

L3: Raw XML Fallback

# Insert custom XML element via XPath

officecli raw-set data.xlsx '/Sheet1' \
    --xpath "insert node <custom><value>42</value></custom> after ./row[1]"

# Direct XML manipulation for unsupported features

officecli raw document.docx /word/document.xml \
    --xpath "//w:hyperlink/@r:id" --output xml

Key Source Files and Implementation

The three-layer architecture is explicitly defined across several core documentation files in the repository:

• SKILL.md – Contains the core strategy statement "L1 (read) → L2 (DOM edit) → L3 (raw XML)" and defines the progressive complexity principle.

• README.md – Provides user-facing descriptions of the three layers, emphasizing that agents should start with read-only views and fall back to raw XML only when necessary.

• skills/officecli-docx/SKILL.md – Demonstrates layer-specific examples for Word documents, including raw-set usage for scenarios where L2 verbs are insufficient.

Summary

• L1 (Read/Inspect) – Use view, get, and query for read-only analysis and data extraction without file modification.
• L2 (DOM Edit) – Use set, add, and remove with typed properties for safe, schema-validated editing of document elements.
• L3 (Raw XML) – Use raw, raw-set, and add-part with XPath only when L2 cannot express the required change, as this bypasses all safety validations.

Frequently Asked Questions

What is the OfficeCLI three-layer architecture?

The OfficeCLI three-layer architecture is a progressive-complexity model that categorizes document operations into L1 (read-only inspection), L2 (DOM-based editing with schema validation), and L3 (raw XML/XPath manipulation). As implemented in iOfficeAI/OfficeCLI, this architecture ensures developers use the safest abstraction level possible, reserving low-level XML operations for edge cases.

When should I use L3 instead of L2 in OfficeCLI?

Use L3 only when L2 lacks a specific verb or property for your required change. According to the source documentation, valid L3 scenarios include inserting internal hyperlinks, adding custom XML elements not covered by the DOM API, or manipulating obscure OpenXML attributes that have no high-level mapping. L2 covers 90% of typical editing tasks like formatting changes and structural updates.

Does OfficeCLI validate changes in L1 and L2?

L1 performs no validation because it is read-only and does not modify the document. L2 enforces strict schema validation through typed attributes and DOM operations, ensuring all changes conform to the OpenXML specification. L3 applies zero validation, allowing you to insert malformed XML that may corrupt the document, which is why the README.md explicitly warns to "always prefer higher layers."

Can I mix L1, L2, and L3 operations in the same OfficeCLI workflow?

Yes, you can combine layers in a single workflow, but you should follow the progressive complexity principle: start with L1 commands to inspect the document structure, use L2 for all possible modifications, and resort to L3 only for the specific elements that require raw XML access. This hybrid approach maintains maximum safety while handling complex document automation requirements.

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