OfficeCLI View Modes: Differences Between HTML, Screenshot, and Text

OfficeCLI's view command provides three distinct rendering modes—HTML for standalone browser previews, screenshot for PNG rasterization, and text for raw content extraction—each optimized for different document inspection and automation workflows.

The iOfficeAI/OfficeCLI repository offers a powerful command-line interface for Microsoft Office documents, with its view command supporting multiple output formats. Understanding the differences between OfficeCLI view HTML, screenshot, and text modes is essential for choosing the right approach for document inspection, CI pipelines, or content extraction tasks.

Output Formats and Primary Use Cases

Each view mode serves a distinct purpose in the document processing pipeline, with different output formats and default behaviors defined in the source code.

HTML Mode (view html)

The HTML mode generates a standalone HTML file with all assets inlined, making it ideal for quick structural inspection without requiring Microsoft Office installation. According to the source code in src/officecli/CommandBuilder.View.cs (starting at line 143), this mode calls RenderViaRegistry to produce HTML previews through the appropriate document handler—whether PowerPointHandler, ExcelHandler, or WordHandler.

By default, HTML mode renders all pages or slides in the document (or defaults to page "1" for single-slide previews if unspecified). This mode supports .docx, .xlsx, and .pptx files, with other formats falling back to an error. The output writes to a temporary file with a randomized filename when --out is not specified, preventing predictable-path security vulnerabilities.

Screenshot Mode (view screenshot)

Screenshot mode produces PNG images (or contact-sheet PNGs when using the --grid option) for visual quality assurance and documentation. The implementation begins at line 209 in CommandBuilder.View.cs, where the tool first builds the same HTML preview used in HTML mode, then rasterizes it using either a native Office engine (Windows only) or a headless browser via src/officecli/Core/HtmlScreenshot.cs.

Unlike HTML mode, screenshot mode defaults to the first page or slide only unless --page or --grid parameters are provided. This mode supports the same file types as HTML (.docx, .xlsx, .pptx) but offers unique options including --screenshot-width, --screenshot-height, and --range for clipping specific elements. When --grid is supplied, the tool generates a tiled contact sheet of multiple slides.

Text Mode (view text)

Text mode extracts a plain-text representation of the document's content, optimized for automated diffing, data extraction, and lightweight searching. The implementation resides at line 666 in CommandBuilder.View.cs, where the code checks for modeKey is "text" or "t" and calls the handler's ViewAsText… method.

This mode streams the entire document without paging (optionally limited by --start, --end, or --max-lines), emitting cell/value pairs for spreadsheets via ExcelHandler or line-by-line text for Word files via WordHandler. It supports any format that has a registered text handler, making it more flexible than the visual modes for raw content extraction.

Technical Implementation Details

The three modes rely on different rendering pipelines within the OfficeCLI architecture:

• HTML Generation: Uses RenderViaRegistry to invoke format-specific handlers in WordHandler.cs, PowerPointHandler.cs, and ExcelHandler.cs, producing static layout representations without animations or interactive features.

• Rasterization: For screenshot mode, the tool leverages HtmlScreenshot.cs to convert HTML previews into PNG images. On Windows systems, it may utilize a native Office engine for rendering; on other platforms, it falls back to a headless browser approach.

• Text Extraction: Directly calls ViewAsText methods that bypass visual rendering entirely, extracting raw content such as spreadsheet cells or document body text without formatting.

Command-Line Options and Usage Examples

The following examples demonstrate the specific options available for each OfficeCLI view mode:

# HTML preview – write to a file and open in the default browser

officecli view report.docx html --out report.html --browser

# Screenshot – capture the first slide as PNG (default width/height)

officecli view presentation.pptx screenshot --out slide1.png

# Screenshot – create a 3-column contact-sheet thumbnail of all slides

officecli view presentation.pptx screenshot --grid 3 --out deck.png

# Screenshot – clip a specific shape (PowerPoint) to a PNG

officecli view presentation.pptx screenshot --range "/slide[2]/shape[5]" --out shape.png

# Text – export an Excel sheet as tab-separated cell/value pairs

officecli view data.xlsx text --cols A,B,C --out sheet.tsv

Mode-Specific Options

• HTML: --browser to open output automatically, --out to specify filename
• Screenshot: --grid for contact sheets, --range for element clipping, --screenshot-width/height for dimensions
• Text: --cols for Excel column filtering, --range for cell ranges, --max-lines for output limitation

Supported File Types and Limitations

HTML and Screenshot modes strictly support .docx, .xlsx, and .pptx files, with other formats producing errors. Both modes render static content only—animations, morph transitions, and interactive PowerPoint features are not preserved in the output.

Text mode supports any format registered with a text handler, offering broader compatibility for content extraction. However, it provides no visual rendering, making it unsuitable for layout verification or visual regression testing.

All modes that write files (HTML and Screenshot) use temporary randomized filenames when --out is unspecified, mitigating predictable-path security risks.

Summary

• HTML mode generates standalone, browser-ready files with all assets inlined, defaulting to all pages and supporting .docx, .xlsx, and .pptx files.
• Screenshot mode produces PNG images via HTML rasterization, defaults to the first page only, and supports contact-sheet generation with --grid.
• Text mode extracts raw content through handler-specific ViewAsText methods, streaming the entire document without paging and supporting flexible text extraction across multiple formats.
• Source locations: HTML handling begins at line 143, screenshot at line 209, and text at line 666 in src/officecli/CommandBuilder.View.cs.

Frequently Asked Questions

Which OfficeCLI view mode should I use for CI pipelines?

Use HTML mode for CI pipelines requiring human inspection of document structure, as it produces standalone files viewable in any browser without Office dependencies. For automated assertions or diffing, text mode is preferable because it generates lightweight, searchable content without visual overhead.

Can I extract specific cell ranges using OfficeCLI view modes?

Yes, but only in specific modes. Text mode supports --cols and --range parameters for filtering Excel columns and cell ranges, while screenshot mode accepts --range for clipping specific elements (such as individual shapes in PowerPoint). HTML mode does not support granular content filtering.

Why does screenshot mode default to the first page while HTML shows all pages?

This design reflects typical use-case optimization. Screenshot mode targets quick visual verification or thumbnail generation, where rendering the first page prevents unintended resource consumption. HTML mode prioritizes complete document inspection, making all content available immediately for structural analysis.

Does OfficeCLI require Microsoft Office to be installed for view modes?

Not necessarily. While screenshot mode may utilize a native Office engine on Windows systems for rasterization, it falls back to a headless browser on other platforms. HTML and text modes operate entirely through OfficeCLI's internal handlers (WordHandler, ExcelHandler, PowerPointHandler) without requiring Microsoft Office installation.

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