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

> Explore OfficeCLI's view modes: HTML for browser previews, screenshot for PNGs, and text for raw content. Understand each mode's use for document inspection and automation.

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

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), [`PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.cs), and [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs), producing static layout representations without animations or interactive features.

- **Rasterization**: For screenshot mode, the tool leverages [`HtmlScreenshot.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash

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