How to Debug Document Issues Using OfficeCLI: `view issues` and `validate` Commands

Use officecli view <file> issues to scan for structural problems and officecli validate <file> to check XML schema compliance, combining both for a complete document health check.

OfficeCLI (iOfficeAI/OfficeCLI) is an open-source command-line tool for diagnosing and repairing Word, PowerPoint, and Excel documents. When you need to debug document issues using OfficeCLI, the view issues and validate commands provide a two-layer defense: semantic structural scanning and strict XML schema validation. These commands work across .docx, .pptx, and .xlsx formats to catch errors before they reach production.

How view issues Scans Document Structure

The view issues command operates as a structural analyzer that returns a list of DocumentIssue objects specific to each Office format. Unlike simple XML validation, this scans for semantic problems like duplicate IDs, dangling references, and content inconsistencies that survive manual editing but break automation workflows.

Word Document Issue Detection

In src/officecli/Handlers/Word/WordHandler.View.cs, the Word handler populates a List<DocumentIssue> with problems such as duplicate IDs, dangling references, and style-index mismatches. These issues often originate from copy-paste operations or template merging and can cause rendering inconsistencies across different versions of Microsoft Word.

PowerPoint Issue Detection

The PowerPoint handler in src/officecli/Handlers/Pptx/PowerPointHandler.View.cs checks for slide-level issues, malformed shapes, and missing resources. This catches broken image links, corrupted slide layouts, and shape references that point to deleted objects—problems that cause "repair" dialogs when opening presentations.

Excel Issue Detection

Excel scanning lives in src/officecli/Handlers/Excel/ExcelHandler.View.cs, where the tool identifies formula-cache stalls, overflowed cells, and stale references. These structural defects often trigger calculation errors or file corruption warnings when the spreadsheet is opened in Excel.

Output Formats and JSON Support

Results display in human-readable text by default. Add the --json flag to emit structured JSON for integration with CI/CD pipelines or automated reporting systems.

How validate Checks XML Schema Compliance

The validate command runs the OpenXML SDK's strict schema validation against the document package. In src/officecli/ResidentServer.cs, the request dispatcher recognizes the validation verb and sets a non-zero exit code when schema errors are found. This command validates that the document adheres to the Office Open XML specification, catching malformed XML that might cause compatibility issues or refusal to open in strict-mode applications.

Step-by-Step Debugging Workflow

Follow this systematic approach to debug document issues using OfficeCLI before delivery:

1. Run view issues – Identify high-level structural problems like duplicate IDs or missing resources.
2. Run validate – Confirm the document passes XML schema validation.
3. Iterate – Use set, add, or remove commands to fix reported issues, then repeat steps 1-2 until both commands report clean states.
4. Visual audit – For PowerPoint decks, run view screenshot to catch layout problems not visible in text-based issue reports.

According to src/officecli/McpServer.cs, this sequence forms part of the "delivery gate" that requires both commands to return clean results before a document is considered ready for publishing.

Practical Examples and CI Integration

Here's how to integrate these commands into your debugging workflow:

# Show structural issues in a Word document

officecli view report.docx issues

# Export issues as JSON for automated processing

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

# Validate XML schema with exit code support

officecli validate report.docx

# Combined CI pipeline check

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

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

echo "Document passed both checks"

Summary

• view issues scans for structural defects like duplicate IDs, dangling references, and malformed shapes, implemented separately for Word, PowerPoint, and Excel in their respective Handler.View.cs files.
• validate performs OpenXML SDK schema validation via src/officecli/ResidentServer.cs, returning non-zero exit codes on failure.
• Both commands support --json output for machine-readable integration with CI/CD systems.
• The debugging workflow documented in src/officecli/McpServer.cs requires both checks to pass the "delivery gate" before document delivery.
• These commands support .docx, .pptx, and .xlsx formats.

Frequently Asked Questions

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

view issues performs a semantic scan for structural problems like duplicate IDs, missing resources, and style inconsistencies specific to each Office format. validate runs the OpenXML SDK's XML schema validation to ensure the document conforms to the Office Open XML specification. Use view issues to catch content logic errors and validate to catch malformed XML.

How do I automate OfficeCLI document checks in a CI/CD pipeline?

Add the --json flag to both commands for machine-readable output, then check exit codes. validate returns non-zero on schema errors, while view issues requires parsing JSON to detect error-level entries. Pipe the JSON output to tools like jq to filter for specific issue types and fail the build when defects are found.

Which file handles the validation logic and exit code setting?

The validate command logic resides in src/officecli/ResidentServer.cs, where the request dispatcher processes the validation verb and sets non-zero exit codes when schema errors are detected. This ensures your scripts can reliably detect validation failures.

Can OfficeCLI detect PowerPoint layout issues that aren't XML errors?

Yes. While validate catches XML schema violations, view issues detects higher-level problems like malformed shapes and missing resources in src/officecli/Handlers/Pptx/PowerPointHandler.View.cs. For visual layout verification, use the view screenshot command to render the deck and inspect slide appearance manually.

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