OfficeCLI Three-Layer Architecture Explained: How to Choose Between L1, L2, and L3

Use L1 for read-only inspection, L2 for safe DOM-based editing, and L3 only as a fallback for raw XML operations that L2 cannot handle.

OfficeCLI implements a three-layer architecture that structures document operations by progressive complexity. Understanding this L1/L2/L3 model is essential for writing efficient, safe automation scripts against Word, Excel, and PowerPoint files. This guide explains each layer's purpose, demonstrates practical commands, and shows you exactly when to use each tier according to the iOfficeAI/OfficeCLI source code.

---

What Is the OfficeCLI Three-Layer Architecture?

The architecture organizes all document interactions into three abstraction levels defined in SKILL.md【/cache/repos/github.com/iOfficeAI/OfficeCLI/main/SKILL.md#L1】:

• L1 (Read/Inspect) — Read-only access without file modification
• L2 (DOM Edit) — Schema-validated object model manipulation
• L3 (Raw XML) — Direct XPath/XML operations with no safety checks

The README.md reinforces this as a progressive complexity principle: "Always prefer higher layers"【/cache/repos/github.com/iOfficeAI/OfficeCLI/main/README.md#L3】.

---

L1: Read and Inspect Documents

L1 commands provide non-destructive access to document content and structure. They return structured data or plain text without writing to the file.

Key L1 Commands

• view — Display document structure or content
• get — Retrieve specific elements as JSON or text
• query — Extract data matching criteria

When to Use L1

Use L1 when you need to:

• Analyze document structure before editing
• Extract statistics or metadata
• Read cell values, paragraph text, or shape properties
• Validate content before processing

L1 Code Examples

# Show document outline structure

officecli view report.docx outline

# Get paragraph 3 as structured JSON

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

# Query all tables in a Word document

officecli query report.docx "//table" --format json

---

L2: DOM-Based Editing

L2 commands manipulate the document through a typed, schema-aware object model. Changes are validated against the OpenXML schema before application.

Key L2 Commands

• set — Modify existing element properties
• add — Insert new elements with structured attributes
• remove — Delete elements safely

When to Use L2

L2 is the default choice for most editing tasks. It provides:

• Schema safety — Invalid operations are rejected
• Low token usage — Efficient for LLM-based automation
• Readable commands — High-level property syntax like --prop font.color=red

Use L2 for formatting, styling, and structural changes that map to defined OpenXML elements.

L2 Code Examples

# Change 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 at position 5

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[4] \
    --prop style="Heading 1"

---

L3: Raw XML Manipulation

L3 commands bypass all abstraction layers to work directly with OpenXML markup. No validation occurs—you operate on raw XML via XPath expressions.

Key L3 Commands

• raw — Read raw XML fragments
• raw-set — Modify XML directly
• add-part — Insert custom XML parts

When to Use L3

Use L3 only as a last resort when:

• L2 lacks a property for your specific need
• You must insert custom elements not covered by the DOM
• You need internal hyperlinks or specialized markup
• You're handling edge cases undefined in the typed API

The tradeoff is complete flexibility at the cost of no safety guarantees. Incorrect XML can corrupt documents.

L3 Code Examples

The skills/officecli-docx/SKILL.md file documents raw-set patterns for Word documents:

# Insert custom XML element after first row (fallback usage)

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

# Modify raw markup for unsupported feature

officecli raw-set report.docx /body \
    --xpath "insert node <w:bookmarkStart w:id='1' w:name='SectionA'/> before ./p[1]"

---

How to Choose the Right Layer

Follow this decision flow based on the repository's guidance:

1. Start with L1 — Can you get the information you need without modifying? Use view, get, or query.

2. Default to L2 — For any editing task, first attempt set, add, or remove with typed properties.

3. Fallback to L3 — Only when L2 properties don't exist or the operation requires direct XML access.

This L1 → L2 → L3 progression minimizes risk while preserving full capability.

---

Summary

• L1 (Read/Inspect) provides safe, non-destructive access for analysis and extraction—use it when you only need to view document content
• L2 (DOM Edit) offers schema-validated editing through high-level properties—this is your default for modifications
• L3 (Raw XML) enables unrestricted XML manipulation—reserve for edge cases that L2 cannot express

The architecture is explicitly codified in SKILL.md and README.md, with practical examples available in format-specific documentation like skills/officecli-docx/SKILL.md.

---

Frequently Asked Questions

What happens if I use L3 incorrectly?

Since L3 bypasses schema validation, malformed XML can corrupt your document or cause applications to reject the file. Always backup files before L3 operations and validate results immediately.

Can I mix L1, L2, and L3 commands in a single workflow?

Yes. A typical script uses L1 to inspect, L2 for standard edits, and falls back to L3 only for specific unsupported operations. The layers are designed to work together in sequence.

Does L2 support all OpenXML properties?

No. L2 covers common formatting and structural properties but intentionally excludes rare or complex elements. When you encounter unsupported properties, the CLI signals this and documentation directs you toward L3 alternatives.

How does OfficeCLI's architecture compare to other document tools?

Most libraries expose either high-level APIs (like L2) or raw XML access (like L3), but rarely both with clear escalation paths. OfficeCLI's explicit three-layer model, as defined in SKILL.md, helps automation systems make structured decisions about abstraction levels.

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