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

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:

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 and 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, 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 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, 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. 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. 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:

# 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 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, 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. This method maps aliases and extensions to canonical format names (docx, xlsx, pptx), which the dispatch logic in ResidentServer.cs and 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: 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.

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