How OfficeCLI's Three-Layer Architecture Works: L1 View, L2 DOM, and L3 Raw XML

OfficeCLI employs a progressive escalation model with three distinct layers—L1 for high-level document viewing, L2 for DOM-based editing, and L3 for raw XML manipulation—to minimize token consumption while shielding users from OpenXML complexity unless absolutely necessary.

The iOfficeAI/OfficeCLI repository implements a sophisticated document manipulation strategy that separates interactions into three logical levels of abstraction. This three-layer architecture allows agents and users to inspect, modify, and transform Word, Excel, and PowerPoint documents through progressively complex interfaces. According to the project's SKILL.md documentation, the design prioritizes token efficiency for LLM-driven workflows while maintaining the flexibility to perform any OpenXML operation.

Understanding the Three-Layer Architecture

OfficeCLI organizes document operations into three distinct layers, each optimized for specific use cases and levels of control.

L1 View Layer: High-Level Inspection

The L1 View layer provides semantic, human-readable representations of Office documents without touching the underlying XML. This read-only layer offers commands like officecli view, officecli get, and officecli query to extract information using modes such as text, annotated, outline, stats, and issues. Because L1 performs zero mutations, it remains the cheapest layer token-wise and serves as the optimal entry point for document inspection and analysis.

L2 DOM Layer: Structured Editing

The L2 DOM layer operates on the document's logical object model, allowing precise manipulation through stable-ID addressing and schema-aware updates. Commands such as officecli set, officecli add, officecli remove, officecli move, and officecli swap support dotted-attribute aliases like font.color and pbdr.top that map directly to OOXML attributes. As implemented in the CLI's core, this layer automatically handles schema validation and generates token-efficient updates, making it the preferred choice for most document modifications.

L3 Raw XML Layer: Direct Access

The L3 Raw XML layer provides direct access to the underlying OpenXML parts through XPath expressions and explicit XML snippets. Using commands like officecli raw and officecli raw-set, users can inject custom XML fragments, modify obscure attributes, or perform specific transformations unavailable in higher layers. This layer requires valid XPath and XML knowledge but offers complete control over the document structure when the DOM abstractions prove insufficient.

Progressive Escalation Strategy

The architecture follows a progressive escalation philosophy designed to optimize AI agent workflows. Users should start with L1 for any read or query operation, escalate to L2 when mutations are required, and fall back to L3 only as a last resort. This approach keeps token consumption minimal and protects users from the intricacies of raw OpenXML unless absolutely necessary, as documented in SKILL.md.

Code Examples by Layer

The following examples demonstrate practical usage patterns for each architectural layer.

L1 View Commands (Read and Query)

Use these commands for inspection and data extraction without modifying the document:

# Extract plain text from a Word document

officecli view report.docx text

# List all shapes on the first slide of a PowerPoint deck

officecli get slides.pptx '/slide[1]' --depth 1

# Find all paragraphs styled as Heading1 using CSS-like selectors

officecli query report.docx 'paragraph[style=Heading1]'

# Display document statistics (pages, words, shapes)

officecli view slides.pptx stats

L2 DOM Commands (Modify and Edit)

Use these commands for structured modifications with automatic validation:

# Change the background color of the first slide

officecli set slides.pptx '/slide[1]' --prop fill=FFCC00

# Add a new heading paragraph to a Word document

officecli add report.docx /body --type paragraph \
  --prop text="Executive Summary" --prop style=Heading1

# Update an Excel cell value and formatting

officecli set data.xlsx '/Sheet1/A1' --prop value="Revenue" --prop bold=true

# Insert a bar chart into a PowerPoint slide

officecli add slides.pptx '/slide[2]' --type chart \
  --prop chartType=bar --prop title="Q4 Sales"

L3 Raw XML Commands (Low-Level Manipulation)

Use these commands when L2 cannot express the required change:

# Inject a custom XML fragment into a Word document's body

officecli raw-set report.docx document \
  --xpath "/w:document/w:body/w:p[last()]" \
  --action append \
  --xml '<w:p><w:r><w:t>Custom XML added</w:t></w:r></w:p>'

# Replace an attribute using XPath when no L2 shortcut exists

officecli raw-set slides.pptx slide \
  --xpath "/p:sld/p:spTree/p:sp[@id='12345']/p:spPr/a:solidFill/a:srgbClr" \
  --action setattr \
  --xml 'val="00FF00"'

Key Documentation and Source References

The authoritative implementation details reside in specific documentation files:

• SKILL.md: Contains the definitive description of the three-layer model, property aliases, and escalation guidelines.
• README.md: Summarizes L1/L2/L3 concepts and provides quick-start examples.
• sdk/node/README.md and sdk/python/README.md: Mirror the layered architecture for programmatic Node.js and Python SDK usage.

Summary

• Three progressive layers separate read operations (L1), DOM edits (L2), and raw XML access (L3) to optimize token usage and complexity.
• L1 View provides zero-mutation inspection through semantic commands like view, get, and query.
• L2 DOM offers the optimal balance of expressiveness and safety, supporting commands like set, add, and remove with automatic schema validation.
• L3 Raw XML delivers complete OpenXML control via raw and raw-set commands using XPath expressions.
• Progressive escalation ensures users start simple and only access complex layers when necessary, as architected in the iOfficeAI/OfficeCLI codebase.

Frequently Asked Questions

What distinguishes L2 DOM editing from L3 Raw XML in OfficeCLI?

L2 DOM editing operates through a logical object model with automatic schema validation and stable-ID addressing, using human-friendly property aliases like font.color. L3 Raw XML requires explicit XPath expressions and raw XML snippets, offering no abstraction—only direct OpenXML part manipulation. According to SKILL.md, L2 handles the majority of use cases automatically, while L3 serves as an escape hatch for unsupported operations.

When should I use L1 View versus L2 DOM commands?

Use L1 View commands (officecli view, officecli query) exclusively for read-only operations such as extracting text, checking statistics, or querying document structure without mutations. Escalate to L2 DOM commands (officecli set, officecli add) immediately when you need to modify content, formatting, or structure, as L2 provides write capabilities with validation and token efficiency.

Does OfficeCLI validate XML at the L3 Raw XML layer?

No, the L3 layer does not provide automatic schema validation. When using officecli raw-set or officecli raw, you must supply valid XPath expressions and well-formed XML fragments yourself. This lack of validation trade-off enables the complete flexibility required for edge cases that the L2 DOM layer cannot express.

Can I combine L2 and L3 operations in the same workflow?

Yes, you can mix layers within a single workflow, though the architecture encourages minimizing L3 usage. A typical pattern involves using L1 to inspect the document, L2 for standard modifications, and L3 only for specific XML tweaks that lack DOM abstractions. The CLI processes these commands sequentially, though each layer maintains independent addressing schemes (DOM paths versus XPath).

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