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

> Understand OfficeCLI's three-layer architecture L1 read L2 DOM and L3 raw XML. Learn when to use each layer for safe and simple document operations.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: architecture
- Published: 2026-07-20

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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

```bash

# 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

```bash

# 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

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md)** – Contains the core strategy statement "L1 (read) → L2 (DOM edit) → L3 (raw XML)" and defines the progressive complexity principle.

- **[`README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.