# How to Debug Document Issues Using the view Command with Different Modes in OfficeCLI > Debug document issues with OfficeCLI view command. Inspect validation, content, structural, or visual layers using modes like issues, text, html, or screenshot without altering source files. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: how-to-guide - Published: 2026-08-07 --- **Use `officecli view ` with modes like `issues`, `text`, `html`, or `screenshot` to inspect documents at the validation, content, structural, or visual layer without modifying the source file.** The **iOfficeAI/OfficeCLI** repository provides a command-line interface for Office document manipulation, and its `view` verb serves as the primary diagnostic tool for debugging document issues using the view command with different modes in OfficeCLI. This non-destructive inspection capability allows developers to validate file integrity, examine raw content, and render visual previews directly from the terminal. ## Understanding the view Command Architecture The `view` command is implemented in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), which acts as the core dispatcher for parsing modes and delegating to specific preview generators. When you invoke `officecli view`, the tool analyzes the file extension and selected mode to route processing through specialized handlers. For HTML generation, the system utilizes [`HtmlPreviewHelper.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/HtmlPreviewHelper.cs) alongside format-specific handlers including [`PowerPointHandler.HtmlPreview.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.HtmlPreview.cs), [`WordHandler.HtmlPreview.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.HtmlPreview.cs), and [`ExcelHandler.HtmlPreview.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.HtmlPreview.cs). Native rendering for screenshots leverages [`PowerPointPngBackend.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointPngBackend.cs) and [`WordPdfBackend.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordPdfBackend.cs), though these require Windows and the Office native engine. ## Available View Modes for Document Debugging OfficeCLI exposes nine distinct modes, each targeting a specific debugging layer. The implementation comment `// CONSISTENCY(view-html-stdout)` at lines 1514-1516 in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) ensures HTML output streams correctly to stdout unless redirected. ### issues Mode The `issues` mode surfaces validation problems reported by the format-handler plugin, including missing document parts and broken relationships. Run this command to spot hidden corruption before editing: ```bash officecli view document.docx issues ``` Add `--json` for machine-readable output suitable for CI/CD integration. This mode catches structural errors that often prevent documents from opening in native applications. ### text Mode Use `text` mode to extract a plain-text representation of the document’s content, streamed line-by-line. This is ideal for detecting stray placeholders like `{{...}}`, `$VAR$`, or "lorem ipsum" text that should have been replaced during template processing. ```bash officecli view template.docx text ``` ### annotated Mode The `annotated` mode extends the text view by injecting structural markers such as paragraph numbers and heading levels. This helps you understand how the underlying XML structure maps to displayed content, making it easier to identify where formatting breaks occur in the markup hierarchy. ### outline Mode Use `outline` mode to generate a hierarchical view of headings, sections, or slides. This validates that the logical document hierarchy is correct and that headings nest properly according to outline specifications. ```bash officecli view presentation.pptx outline ``` ### stats Mode The `stats` mode provides simple statistics including element counts, page numbers, slide counts, and file size. Use this for sanity-checking that a document contains the expected number of tables or slides before processing. ### html Mode The `html` mode generates a self-contained HTML preview for `*.pptx`, `*.xlsx`, and `*.docx` files. According to the source code in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), you can automatically open the preview in your system browser using `ProcessStartInfo` (lines 1518-1532). ```bash officecli view report.xlsx html --browser ``` Pipe the output to a file for manual inspection: ```bash officecli view document.docx html --out preview.html ``` ### svg Mode For slide decks, `svg` mode produces a vector-graphics preview that scales without quality loss. This is useful for inspecting layout-independent graphics or verifying that vector elements render correctly across different zoom levels. ### screenshot Mode The `screenshot` mode renders raster images (PNG) of specific pages or slides. The handling logic begins at line 1533 in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) with the check `if (mode!.ToLowerInvariant() is "screenshot" ...)`. Capture a specific page: ```bash officecli view deck.pptx screenshot --page 2 --out slide2.png ``` Generate a contact-sheet grid of the entire document: ```bash officecli view document.pptx screenshot --grid 3 --out contact_sheet.png ``` Use `--grid -1` to automatically calculate the optimal column count via `HtmlScreenshot.AutoGridColumns`. ### forms Mode For `*.docx` files containing interactive controls, `forms` mode displays form field definitions and their placements. This verifies that content controls exist and are correctly positioned before attempting automated data injection. ```bash officecli view form.docx forms ``` ## Essential Flags and Options The `view` command supports several modifiers that enhance debugging capabilities: - **`--page N`**: Selects a specific page or slide for HTML, SVG, or screenshot modes - **`--grid N`**: Creates a contact-sheet grid with N columns; use `-1` for automatic column selection - **`--out `**: Writes preview output (HTML, SVG, or PNG) to a file instead of stdout - **`--browser`**: Automatically opens HTML previews in the system default browser - **`--json`**: Returns structured output for `issues`, `stats`, or element queries, enabling scriptable analysis - **`--range `**: Limits HTML previews to specific data-path regions - **`--render native|html|auto`**: Chooses the rendering backend for screenshots; `native` requires Windows and the Office rendering engine ## Step-by-Step Debugging Workflow Follow this systematic approach to isolate document problems using the available modes: 1. **Validate file integrity**: Run `officecli view issues --json` to detect corruption or broken relationships before processing 2. **Inspect raw content**: Execute `officecli view text` to identify stray placeholders or malformed markup 3. **Check structural hierarchy**: Use `officecli view outline` or `annotated` to verify proper nesting of headings and sections 4. **Generate visual preview**: Create `officecli view html --browser` for a quick visual check without opening heavy Office applications 5. **Capture specific rendering**: Run `officecli view screenshot --page 1 --out debug.png` to see exactly how a page renders 6. **Verify form controls**: If applicable, execute `officecli view forms` to confirm field definitions and placements By combining these modes, you can pinpoint whether issues reside in data-path errors (`issues`), content problems (`text`), structural mis-nesting (`outline`/`annotated`), or visual rendering faults (`html`/`screenshot`/`svg`). ## Summary - **The `view` verb** in iOfficeAI/OfficeCLI provides non-destructive document inspection through nine specialized modes - **Validation debugging** uses `issues` mode to catch corruption early, while `stats` mode provides quantitative sanity checks - **Content debugging** relies on `text` and `annotated` modes to expose raw document data and structural mappings - **Visual debugging** leverages `html`, `svg`, and `screenshot` modes, with screenshot handling implemented in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) starting at line 1533 - **Specialized inspection** includes `outline` for hierarchy validation and `forms` for interactive field verification - **Output control** via `--out`, `--json`, and `--browser` flags enables integration with automated pipelines and manual review workflows ## Frequently Asked Questions ### What is the difference between text mode and annotated mode? **`text` mode** extracts clean, readable content without markup, making it ideal for spotting placeholder text or content errors. **`annotated` mode** adds structural markers like paragraph numbers and heading levels, revealing how the underlying XML structure maps to the visible text, which helps debug formatting issues where the structure itself is suspect. ### How do I save a preview to a file instead of printing to the terminal? Use the **`--out `** flag to write output directly to a file. This works for HTML, SVG, and PNG outputs. For example: `officecli view presentation.pptx html --out preview.html` or `officecli view document.docx screenshot --page 1 --out slide1.png`. ### Why does screenshot mode sometimes generate HTML instead of a PNG image? Screenshot mode uses a **`--render`** option that accepts `native`, `html`, or `auto` values. The `native` renderer requires Windows and the Office rendering engine (implemented in [`PowerPointPngBackend.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointPngBackend.cs) and [`WordPdfBackend.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordPdfBackend.cs)). If native rendering is unavailable or you specify `html`, the tool falls back to generating an HTML preview and converting it, which is handled through [`HtmlPreviewHelper.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/HtmlPreviewHelper.cs). ### Can I automate issue detection in CI/CD pipelines? Yes. Run `officecli view issues --json` to output validation results in JSON format. This structured output can be parsed by CI/CD systems to fail builds when documents contain broken relationships, missing parts, or other corruption detected by the format-handler plugin.