# How OfficeCLI Handles Different Office Document Formats: DOCX, XLSX, and PPTX

> Discover how OfficeCLI expertly manages DOCX, XLSX, and PPTX files. Learn about its unified command architecture and dedicated handler classes for seamless document processing.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: deep-dive
- Published: 2026-07-26

---

**OfficeCLI normalizes Word, Excel, and PowerPoint files into a unified command architecture while delegating format-specific operations to dedicated handler classes that implement shared interfaces.**

The iOfficeAI/OfficeCLI repository provides a cross-platform command-line interface for manipulating Microsoft Office documents without requiring external dependencies or installed Office suites. Understanding how OfficeCLI handles different Office document formats reveals a sophisticated three-layer architecture (Read → DOM → Raw XML) that treats DOCX, XLSX, and PPTX uniformly through canonical format mapping while preserving each format's unique capabilities.

## Unified Command Architecture

All CLI commands—including `create`, `view`, `get`, `set`, `add`, `remove`, `query`, and `batch`—share a common syntax that works across all three document types:

```bash
officecli <verb> <file> [path] [options]

```

The system determines the appropriate document type by parsing the file extension and normalizing it through the dispatch logic inside [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) and [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs). This architecture allows the same command patterns to manipulate fundamentally different OOXML structures while the heavy lifting occurs in format-specific implementations.

## Format-Specific Handler Classes

OfficeCLI implements three dedicated handler classes, each residing in the `src/officecli/Handlers/` directory and implementing the `IDocumentHandler` and `Rendering.IRenderModelHost` interfaces.

### WordHandler for DOCX Documents

Located at [`src/officecli/Handlers/Word/WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.cs), this class manages Word OOXML parts including the main document, styles, numbering, and themes. **WordHandler** provides element-level operations for:

- Paragraphs and runs (text formatting)
- Tables and table cells
- Images and charts
- Hyperlinks and bookmarks
- Sections, headers, and footers

The handler exposes `WordHandler.HtmlPreview` to generate high-fidelity HTML representations of the document structure, enabling the `view html` command to render Word documents as self-contained HTML files.

### ExcelHandler for XLSX Spreadsheets

The [`src/officecli/Handlers/Excel/ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Excel/ExcelHandler.cs) file contains the logic for Excel document manipulation. **ExcelHandler** manages:

- Worksheets and cell ranges
- Formulas (evaluating 350+ built-in Excel functions during write operations)
- Tables, charts, slicers, and pictures
- Data validation and conditional formatting
- Pivot tables and named ranges

Unlike Word documents, Excel files require calculation engines; OfficeCLI eliminates external dependencies by evaluating formulas internally. The `ExcelHandler.HtmlPreview` method generates HTML that mimics the Excel UI, complete with grid lines and cell formatting.

### PowerPointHandler for PPTX Presentations

Found in [`src/officecli/Handlers/Pptx/PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Pptx/PowerPointHandler.cs), this handler addresses the slide-based structure of PowerPoint files. **PowerPointHandler** processes:

- Slides and slide layouts
- Shapes, pictures, and tables
- Charts and SmartArt
- Animations and transitions
- 3D models and slide-level metadata

The handler generates per-slide PNG screenshots through `PowerPointHandler.HtmlPreview` and produces full-document HTML representations, enabling the `view screenshot` and `view html` commands to work consistently across all three formats.

## Canonical Format Mapping

To ensure the CLI accepts flexible input while maintaining strict internal typing, OfficeCLI implements format normalization in [`src/officecli/Help/SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Help/SchemaHelpLoader.cs). The `NormalizeFormat()` method maps user-friendly aliases to canonical format identifiers:

- `word` → `docx`
- `excel` → `xlsx`
- `ppt` or `powerpoint` → `pptx`

This normalization occurs before handler instantiation, ensuring that `officecli view document.word html` resolves to the WordHandler while `officecli view data.excel html` routes to ExcelHandler, despite the non-standard extensions.

## Shared Rendering Pipeline

Format-specific handlers integrate into a unified rendering system through [`src/officecli/Handlers/Rendering/BasicRenderers.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Rendering/BasicRenderers.cs). This dispatcher selects the appropriate handler based on the normalized document type and supports three output modes:

1. **HTML View**: Generates self-contained HTML files via the `view html` command
2. **Screenshot View**: Produces per-page PNG images via `view screenshot`
3. **Live Preview**: Spawns a lightweight HTTP server using the `watch` command that refreshes automatically after mutations

Because each handler implements `Rendering.IRenderModelHost`, the rendering engine treats DOCX, XLSX, and PPTX documents polymorphically while still accessing format-specific preview logic.

## Practical Command Examples

The following workflow demonstrates how the same command syntax applies across all three document formats:

```bash

# Create fresh documents of each type

officecli create report.docx
officecli create data.xlsx
officecli create deck.pptx

# Add content using unified path syntax

officecli add report.docx / --type paragraph --prop text="Executive Summary"
officecli add data.xlsx / --type sheet --prop name="Q4"
officecli add deck.pptx / --type slide --prop title="Q4 Results"

# Modify elements with format-specific paths

officecli set report.docx /body/p[1]/r[1] --prop bold=true
officecli set data.xlsx /Sheet1!A1 --prop value=123
officecli set deck.pptx /slide[1]/shape[1] --prop text="Revenue ↑"

# Render output (works for all three formats)

officecli view report.docx html -o report.html
officecli view data.xlsx screenshot -o data.png
officecli view deck.pptx html -o deck.html

```

All commands accept the `--json` flag to return structured responses, making the CLI suitable for AI agent integration and automated workflows.

## Summary

- **OfficeCLI** routes commands to format-specific handlers (`WordHandler`, `ExcelHandler`, `PowerPointHandler`) while exposing a unified command syntax across DOCX, XLSX, and PPTX files.
- Canonical format mapping in [`SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs) normalizes user input aliases (word, excel, ppt) to standard extensions before dispatch.
- Each handler implements shared interfaces (`IDocumentHandler`, `IRenderModelHost`) that enable polymorphic rendering through [`BasicRenderers.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/BasicRenderers.cs), supporting HTML, PNG screenshot, and live preview outputs.
- The architecture maintains format-specific capabilities—such as Excel formula evaluation and PowerPoint slide management—without requiring external Office installations or dependencies.

## Frequently Asked Questions

### How does OfficeCLI determine which handler to use for a document?

OfficeCLI extracts the file extension from the provided path and passes it through the `NormalizeFormat()` method in [`src/officecli/Help/SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Help/SchemaHelpLoader.cs). This method maps aliases and extensions to canonical format names (`docx`, `xlsx`, `pptx`), which the dispatch logic in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) and [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs) uses to instantiate the appropriate handler class (`WordHandler`, `ExcelHandler`, or `PowerPointHandler`).

### Can I use OfficeCLI to convert between document formats?

No, OfficeCLI does not implement cross-format conversion. The architecture treats each format distinctly through specialized handlers that understand specific OOXML schemas. While the CLI provides `view html` and `view screenshot` commands that create visual representations, these outputs are renderings rather than native format conversions. The three-layer architecture (Read → DOM → Raw XML) preserves format-specific data structures that do not translate directly between document types.

### What rendering options are available for each document type?

All three formats support three rendering modes through [`BasicRenderers.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/BasicRenderers.cs): HTML generation (`view html`), PNG screenshot capture (`view screenshot`), and live HTTP server preview (`watch`). Word documents render as paginated HTML with preserved formatting; Excel produces grid-based HTML mimicking the spreadsheet interface; PowerPoint generates per-slide PNGs and sequential HTML slides. Each handler implements its own `HtmlPreview` method to handle format-specific layout requirements.

### Are there format-specific commands that don't work across all three types?

Yes, while core verbs (`create`, `view`, `set`, `add`) work universally, certain path syntaxes and element types are format-specific. For example, Word documents use XPath-like navigation (`/body/p[1]/r[1]`) for paragraph runs, Excel uses cell reference notation (`/Sheet1!A1`), and PowerPoint uses slide indexing (`/slide[1]/shape[1]`). Additionally, Excel-specific features like formula evaluation and worksheet manipulation have no equivalent in Word or PowerPoint handlers, though the base command structure remains consistent.