How to Use the OfficeCLI Document Validation Command Before Delivery

The OfficeCLI document validation command checks Word, Excel, and PowerPoint files against OpenXML schemas and content-level issues, outputting deterministic JSON that enables automated pre-delivery quality gates in CI/CD pipelines.

OfficeCLI from iOfficeAI/OfficeCLI is a self-contained, cross-platform binary written in .NET that provides programmatic control over Office documents without requiring Microsoft Office itself. The OfficeCLI document validation command operates across the tool's three architectural layers to ensure files are structurally sound and content-complete before distribution.

Understanding the Three-Layer Validation Architecture

OfficeCLI organizes functionality into three layers that work together for comprehensive validation. According to the repository's README.md, this architecture balances ease of use with the power needed for automated pipelines.

• L1 – Read: High-level semantic views including the view command with issues sub-command for detecting text overflow, missing alt text, and broken formulas
• L2 – DOM: Structured element operations using get, set, add, and remove to programmatically fix validation failures
• L3 – Raw XML: Direct XPath access and schema validation via the validate command when DOM shortcuts are insufficient

The validation process typically starts at L3 with schema compliance, then moves to L1 for semantic issue detection, and uses L2 for automated remediation.

Schema Validation with the validate Command

The validate command operates at Layer 3 (Raw XML) to verify document structure against OpenXML schemas. As implemented in src/officecli/officecli.csproj, this catches corruption, malformed XML, or non-standard extensions that could cause compatibility issues in Microsoft Office or other processors.

Run schema validation from the terminal:

officecli validate deck.pptx

This command exits with a non-zero status if the document violates OpenXML standards, making it suitable for pre-commit hooks and build pipeline gates.

Detecting Content Issues with view issues

The view … issues sub-command operates at Layer 1 (Read) to surface semantic problems such as broken formulas in Excel, missing fonts in PowerPoint, or accessibility gaps. As documented in README.md, this produces deterministic JSON output with structured error codes including not_found, invalid_value, and missing_property.

Generate a machine-readable issue report:

officecli view deck.pptx issues --json

The JSON output includes the specific path to each issue (e.g., /slide[1]/shape[2]), allowing automated remediation scripts to target elements without knowledge of underlying OOXML namespaces.

Automated Remediation Workflows

After validation, use Layer 2 DOM operations to fix detected issues automatically. This closes the "render → look → fix" loop for CI/CD pipelines.

Fix missing font properties detected during validation:

officecli view deck.pptx issues --json \
  | jq -r '.[] | select(.code=="missing_property" and .details.property=="font") | .path' \
  | while read -r p; do
      officecli set deck.pptx "$p" --prop font=Arial
    done

This pipeline extracts paths with missing fonts from the validation JSON and applies the set command to each location, ensuring consistent styling before delivery.

Programmatic Validation with OfficeCLI SDKs

OfficeCLI exposes the validation functionality through thin SDK wrappers that communicate with the native binary, enabling integration into existing application codebases.

Python SDK Validation

Using sdk/python/officecli.py:

from officecli import Doc

with Doc("report.docx") as d:
    # Raises exception on schema errors

    d.validate()
    
    # Retrieve structured issues as list of dictionaries

    issues = d.view("issues", json=True)
    for issue in issues:
        print(issue["code"], issue["path"], issue["details"])

Node.js SDK Validation

Using sdk/node/index.js:

import { Doc } from "@officecli/sdk";

await using d = await Doc.open("budget.xlsx");
await d.validate();  // Throws on schema errors
const issues = await d.view("issues", { json: true });
console.log(issues);

Both SDKs mirror the CLI functionality while providing native error handling and data structures for their respective languages.

CI/CD Integration Capabilities

The deterministic JSON output with standardized error codes makes the OfficeCLI document validation command ideal for automated pipelines. Because all operations use path-based syntax (/slide[1]/shape[2], /body/p[3]), scripts can target specific elements without OOXML expertise, as noted in README.md.

The binary embeds the .NET runtime, requiring only a single download with no external dependencies. This architecture—documented in npm/officecli.js and SKILL.md—makes OfficeCLI suitable for containerized build environments where traditional Office installations are impractical.

Summary

• The OfficeCLI document validation command combines schema validation (validate) and content analysis (view issues) to ensure document integrity before delivery.
• Output is deterministic JSON with structured error codes like not_found, invalid_value, and missing_property, enabling automated remediation via the DOM layer.
• Three-layer architecture (Read, DOM, Raw XML) allows path-based operations without requiring OOXML namespace expertise.
• Available via command line and through Python (sdk/python/officecli.py) and Node.js (sdk/node/index.js) SDKs.
• Self-contained .NET binary requires no Microsoft Office installation, making it suitable for Docker containers and CI/CD pipelines.

Frequently Asked Questions

What file formats does the OfficeCLI document validation command support?

The validation command supports modern Office Open XML formats including Word documents (.docx), Excel spreadsheets (.xlsx), and PowerPoint presentations (.pptx). The tool validates against official OpenXML schemas to ensure compliance with the ISO/IEC 29500 standard.

How does OfficeCLI handle validation errors in automated pipelines?

OfficeCLI outputs deterministic JSON with structured error codes when using the --json flag. This allows CI/CD systems to parse validation results programmatically and trigger specific remediation workflows based on error types like missing_property or invalid_value, without requiring human intervention.

Can I fix validation issues automatically without manual editing?

Yes. After running officecli view issues --json, you can pipe the output to the set, add, or remove commands to modify specific paths. For example, you can automatically set missing fonts or remove corrupted elements using the DOM layer (L2) operations after identifying issues through the validation layer (L3).

Is Microsoft Office required to run the validation command?

No. OfficeCLI is a self-contained binary that embeds the .NET runtime and implements its own OpenXML parser and high-fidelity HTML rendering engine. This makes it suitable for headless environments like Docker containers or GitHub Actions where installing Microsoft Office is impractical or impossible.

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