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

> Understand OfficeCLI's three-layer architecture L1 L2 L3. Learn when to use L1 for inspection, L2 for safe editing, and L3 as a fallback for raw XML operations.

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

---

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

```bash

# 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

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-docx/SKILL.md) file documents raw-set patterns for Word documents:

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) and [`README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md), with practical examples available in format-specific documentation like [`skills/officecli-docx/SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md), helps automation systems make structured decisions about abstraction levels.