How to Debug Document Issues Using the OfficeCLI View Issues Command

Use the officecli view <file> issues command to scan Word, PowerPoint, and Excel documents for structural problems, and combine it with officecli validate to verify XML schema compliance before delivery.

OfficeCLI is an open-source command-line tool from the iOfficeAI/OfficeCLI repository that diagnoses and repairs Office documents. When you need to debug document issues using the OfficeCLI view issues command, you gain access to deep structural analysis for Word (.docx), PowerPoint (.pptx), and Excel (.xlsx) files. This tool inspects document internals beyond what typical Office applications reveal, identifying problems like duplicate IDs, dangling references, and schema violations.

Understanding the OfficeCLI View Issues Command

The view issues command operates as a diagnostic scanner that returns a list of DocumentIssue objects specific to each Office format. Unlike simple error checking, this command performs handler-specific scans that understand the unique architecture of each document type.

Word Document Issue Detection in WordHandler.View.cs

For Word documents, the scan logic resides in src/officecli/Handlers/Word/WordHandler.View.cs. This handler populates a List<DocumentIssue> with structural problems including duplicate IDs, dangling references, and style-index mismatches. These issues often remain hidden until documents are processed programmatically or opened in strict compliance modes.

PowerPoint and Excel Issue Detection

PowerPoint diagnostics are implemented in src/officecli/Handlers/Pptx/PowerPointHandler.View.cs, which checks for slide-level issues, malformed shapes, and missing resources. For Excel workbooks, src/officecli/Handlers/Excel/ExcelHandler.View.cs detects formula-cache stalls, overflowed cells, and stale references that could cause calculation errors or corruption warnings.

Validating XML Schema with the Validate Command

While view issues detects logical and structural problems, the validate command performs OpenXML SDK schema validation to catch XML-level errors. According to the source code in src/officecli/ResidentServer.cs, this command sets a non-zero exit code when schema violations are detected, making it ideal for CI/CD pipelines. Validation is also invoked implicitly after batch mutations to guarantee schema compliance.

Step-by-Step Debugging Workflow

Follow this systematic approach to diagnose and resolve document problems:

1. Run view issues – Execute officecli view <file> issues to identify high-level structural problems like duplicate IDs or missing resources.
2. Run validate – Execute officecli validate <file> to confirm the document passes XML schema validation.
3. Iterate repairs – Use OfficeCLI commands like set, add, or remove to fix reported issues, then repeat steps 1-2 until both commands report clean states.
4. Visual verification – For PowerPoint decks, optionally run view screenshot to catch layout problems not visible in textual issue reports.

As documented in src/officecli/McpServer.cs, this sequence forms part of the "delivery gate" that requires both view issues and validate to be clean before a document is considered ready for delivery.

Practical Code Examples

Use these commands to integrate OfficeCLI debugging into your workflow:

# Display all structural issues in a Word document

officecli view report.docx issues

# Export issues to JSON for automated processing

officecli view report.docx issues --json > issues.json

# Validate XML schema compliance with error exit codes

officecli validate report.docx

# CI pipeline integration example

if ! officecli validate report.docx; then
  echo "Schema validation failed"
  exit 1
fi

if officecli view report.docx issues --json | jq '.[] | select(.type=="error")'; then
  echo "Document issues detected"
  exit 1
fi

echo "Document passed both checks"

Summary

• The officecli view issues command scans documents for format-specific structural problems via dedicated handlers in WordHandler.View.cs, PowerPointHandler.View.cs, and ExcelHandler.View.cs.
• The validate command performs OpenXML SDK schema validation and returns non-zero exit codes for failures, as implemented in ResidentServer.cs.
• Both commands support --json output for machine-readable integration and form the "delivery gate" documented in McpServer.cs to ensure production-ready documents.
• Combining both commands creates a robust debugging workflow for Word, PowerPoint, and Excel files.

Frequently Asked Questions

What types of issues does OfficeCLI view issues detect?

The command detects format-specific structural problems: Word documents are checked for duplicate IDs, dangling references, and style-index mismatches; PowerPoint files are scanned for slide-level issues, malformed shapes, and missing resources; Excel workbooks are analyzed for formula-cache stalls, overflowed cells, and stale references.

How do I export OfficeCLI issue reports to JSON?

Append the --json flag to either the view issues or validate commands. For example, officecli view document.docx issues --json outputs a structured JSON array of DocumentIssue objects suitable for piping into tools like jq or for automated CI/CD processing.

What is the difference between view issues and validate in OfficeCLI?

view issues performs semantic analysis of document structure using format-specific handlers to find logical problems like broken references, while validate uses the OpenXML SDK to verify XML schema compliance. The former catches content logic errors; the latter catches markup syntax violations. Both are required for the delivery gate documented in McpServer.cs.

How does OfficeCLI handle exit codes for validation failures?

According to ResidentServer.cs, the validate command returns a non-zero exit code when schema errors are detected, enabling reliable error handling in shell scripts and CI pipelines. The view issues command similarly indicates problem severity through its output, though explicit exit code behavior for issues should be checked against your specific OfficeCLI version.

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