OfficeCLI Three-Layer Architecture Commands: L1 View vs L2 Get/Set vs L3 Raw Explained

OfficeCLI organizes document operations into three progressive layers—L1 view for high-level reading, L2 get/set for DOM manipulation, and L3 raw for direct XML access—each offering different trade-offs between safety, expressiveness, and token cost.

OfficeCLI, an open-source command-line interface for Microsoft Office documents, implements a progressive-complexity model that splits operations into three logical command layers. This architecture allows AI agents and developers to start with simple, token-efficient operations and escalate to more powerful—but riskier—commands only when necessary. Understanding these OfficeCLI three-layer architecture commands is essential for optimizing both performance and document integrity when automating Word, Excel, and PowerPoint workflows.

Overview of the Progressive Complexity Model

The architecture follows a deliberate escalation pattern where automation scripts begin with the cheapest-to-run commands and advance to lower layers only when higher-level abstractions prove insufficient. According to the repository's README.md, this design reduces token usage and keeps AI interactions deterministic by providing schema-aware safety at L1 and L2, while reserving L3 as a universal fallback for edge cases that violate standard schemas.

L1 View Commands (The Read Layer)

Purpose and Capabilities

The L1 view layer provides high-level, semantically rich views of documents without exposing internal XML structure. Implemented in handlers like src/officecli/Handlers/Word/WordHandler.Helpers.RunFormat.cs, these commands treat documents as abstract entities rather than raw markup. Available operations include view with submodes: text, annotated, outline, stats, issues, html, svg, and screenshot.

When to Use L1 Commands

Use L1 when you need quick inspection, content extraction, or when operating as an AI agent requiring minimal token consumption. This layer is strictly read-only and serves as the default entry point for document analysis.

# Extract plain text with line limits for quick content inspection

officecli view report.docx text --max-lines 200

# Generate a structural outline to verify document hierarchy

officecli view report.docx outline

L2 Get/Set Commands (The DOM Layer)

Purpose and Capabilities

The L2 get/set layer operates on the document object model (DOM), manipulating structured elements through schema-validated operations. This layer exposes commands including get, query, set, add, remove, move, and swap, allowing precise element-level edits while maintaining document integrity through early validation.

The implementation in src/officecli/Handlers/Excel/ExcelHandler.Set.Cells.cs demonstrates how L2 commands validate property assignments against Office Open XML schemas before committing changes, preventing malformed documents.

When to Use L2 Commands

Choose L2 when performing structural edits that require precise element targeting—such as changing paragraph styles, inserting tables, or updating cell values—but can operate within the validated API surface.

# Change a paragraph style using high-level property assignment

officecli set report.docx /body/p[3] --prop style=Heading2

# Add a new row to an Excel worksheet

officecli add data.xlsx /Sheet1 --type row --prop values="Name,Score"

# Remove a specific shape from a PowerPoint slide

officecli remove deck.pptx /slide[2]/shape[5]

L3 Raw Commands (The XML Layer)

Purpose and Capabilities

The L3 raw layer provides direct access to underlying Open XML through XPath queries, bypassing schema validation entirely. Implemented in handlers such as src/officecli/Handlers/Pptx/PowerPointHandler.Raw.cs, these commands—including raw, raw-set, add-part, and validate—offer maximum expressiveness at the cost of safety and token efficiency.

When to Use L3 Commands

Reserve L3 for scenarios where L2 cannot express required operations, such as custom hyperlink attributes, composite fields, or obscure markup elements that fall outside the DOM abstraction.

# Insert a custom hyperlink with attributes unavailable in L2

officecli raw-set report.docx document \
  --xpath "//w:p[1]" \
  --action append \
  --xml '<w:hyperlink r:id="rId5"><w:r><w:t>See details</w:t></w:r></w:hyperlink>'

# Directly modify an obscure XML attribute

officecli raw report.pptx '/slide[1]/shape[3]' --xpath "@flipV='true'"

Key Differences Between OfficeCLI Architecture Layers

The three layers differ fundamentally in scope, safety guarantees, and expressive power:

• Scope: L1 operates on whole-document abstractions; L2 targets individual DOM elements using friendly selectors; L3 manipulates raw XML fragments directly via XPath.
• Safety: L1 and L2 enforce schema validation, rejecting invalid values early in the pipeline. L3 bypasses validation, meaning malformed XML can corrupt the target file or render it unopenable.
• Expressiveness: L3 can set any attribute or structure that higher layers cannot express, but lacks the convenience of property names, type safety, and auto-completion available in L2.

Source Code Implementation

The layer distinctions manifest directly in the codebase organization. The README.md defines the architectural philosophy, while SKILL.md provides an AI-friendly cheat sheet summarizing the escalation strategy for automated agents.

Specific implementation files include:

• src/officecli/Handlers/Word/WordHandler.Helpers.RunFormat.cs – Contains L1 view logic for Word document rendering and text extraction
• src/officecli/Handlers/Excel/ExcelHandler.Set.Cells.cs – Implements L2 DOM operations for Excel cell manipulation and validation
• src/officecli/Handlers/Pptx/PowerPointHandler.Raw.cs – Provides L3 raw XPath access for PowerPoint presentations, enabling direct XML injection

Summary

• L1 view commands offer high-level, read-only document abstraction with minimal token cost, ideal for content inspection and AI agent entry points.
• L2 get/set commands provide schema-validated DOM manipulation for precise element editing without exposing raw XML complexity or risking structural corruption.
• L3 raw commands enable direct Open XML access via XPath when higher layers lack required functionality, trading safety barriers for unlimited expressiveness.
• The progressive escalation from L1 to L3 optimizes token usage while maintaining document integrity through validation barriers at the upper layers.

Frequently Asked Questions

What is the main advantage of using L1 view commands over L2 or L3?

L1 view commands consume the fewest tokens and provide the fastest path to document understanding because they operate on semantic abstractions rather than structural elements or raw XML. According to the OfficeCLI source code in README.md, this makes L1 the default entry point for AI agents that need to read document content without risking accidental modifications or parsing complex markup trees.

When should I escalate from L2 get/set to L3 raw commands?

Escalate to L3 only when L2 cannot express the specific attribute or structure you need to modify, such as custom hyperlink relationships in Word or obscure shape properties in PowerPoint that lack DOM wrappers. While L3 raw commands can manipulate any XML node via XPath as implemented in PowerPointHandler.Raw.cs, they bypass schema validation, significantly increasing the risk of document corruption compared to the validated L2 DOM layer.

Does OfficeCLI validate XML when using L3 raw commands?

No, L3 raw commands intentionally bypass schema validation to provide unrestricted access to the underlying Open XML. These commands accept arbitrary XPath expressions and XML fragments without checking against Office Open XML schemas, making them powerful but potentially dangerous if malformed markup is injected or if required namespace declarations are omitted.

How do the three layers affect token usage in AI applications?

The progressive-complexity model is designed specifically to minimize token consumption in large language model workflows: L1 view commands require the least context (just the semantic view), L2 get/set commands need moderate structural detail (DOM paths), and L3 raw commands demand full XML context and namespace awareness. The architecture encourages agents to succeed at the highest possible layer to reduce API costs and maintain deterministic, reproducible interactions.

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