How to Debug Document Issues Using the view Command with Different Modes in OfficeCLI

Use officecli view <file> <mode> 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, 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 alongside format-specific handlers including PowerPointHandler.HtmlPreview.cs, WordHandler.HtmlPreview.cs, and ExcelHandler.HtmlPreview.cs. Native rendering for screenshots leverages PowerPointPngBackend.cs and 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 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:

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.

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.

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, you can automatically open the preview in your system browser using ProcessStartInfo (lines 1518-1532).

officecli view report.xlsx html --browser

Pipe the output to a file for manual inspection:

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 with the check if (mode!.ToLowerInvariant() is "screenshot" ...).

Capture a specific page:

officecli view deck.pptx screenshot --page 2 --out slide2.png

Generate a contact-sheet grid of the entire document:

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.

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 <path>: 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 <data-path>: 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 <file> issues --json to detect corruption or broken relationships before processing
2. Inspect raw content: Execute officecli view <file> text to identify stray placeholders or malformed markup
3. Check structural hierarchy: Use officecli view <file> outline or annotated to verify proper nesting of headings and sections
4. Generate visual preview: Create officecli view <file> html --browser for a quick visual check without opening heavy Office applications
5. Capture specific rendering: Run officecli view <file> screenshot --page 1 --out debug.png to see exactly how a page renders
6. Verify form controls: If applicable, execute officecli view <file> 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 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 <path> 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 and 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.

Can I automate issue detection in CI/CD pipelines?

Yes. Run officecli view <file> 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.

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