How to View Document Statistics with OfficeCLI: Command-Line Document Analysis

Use officecli view <file> stats to generate a statistical summary of any supported Office document, with optional --json for structured output or --page-count for DOCX pagination.

The iOfficeAI/OfficeCLI repository provides a cross-platform command-line interface for analyzing Microsoft Office documents without opening the GUI. When you need to inspect document composition, metadata, or content metrics programmatically, you can view document statistics with OfficeCLI using the specialized stats mode of the view command.

The view stats Command Architecture

The statistics generation follows a three-stage pipeline implemented across the source tree:

1. Command Parsing – In src/officecli/CommandBuilder.View.cs, the CLI collects the mode argument (lines 14-16) and validates that stats is a supported view mode.
2. Handler Dispatch – The DocumentHandlerFactory opens the target file and returns an appropriate handler implementing IDocumentHandler based on file extension.
3. Statistics Execution – Each format-specific handler implements ViewAsStats() for human-readable text and ViewAsStatsJson() for machine-readable output.

Document-Specific Statistics Implementation

Word Documents (DOCX)

For Word files, WordHandler.ViewAsStats() in src/officecli/Handlers/Word/WordHandler.View.cs (starting at line 11) constructs a comprehensive analysis including paragraph counts, table and image tallies, style/font usage statistics, empty paragraph detection, double-space detection, and character totals. When the --page-count flag is present, the handler attempts to retrieve an accurate page count from Word on Windows, falling back to HTML rendering and DOM extraction if necessary (handled in CommandBuilder.View.cs lines 95-104).

Excel Spreadsheets (XLSX)

The ExcelHandler.ViewAsStats() method in src/officecli/Handlers/Excel/ExcelHandler.View.cs aggregates sheet-level metrics including row and column counts, non-empty cell totals, and cell-type breakdowns (numeric vs. string).

PowerPoint Presentations (PPTX)

Located in src/officecli/Handlers/Pptx/PowerPointHandler.View.cs, the PowerPointHandler.ViewAsStats() method tallies slides, shapes, pictures, tables, and chart statistics for presentation files.

Command Syntax and Examples

The basic syntax follows the pattern:

officecli view <filename> stats [options]

Common usage patterns include:

# Basic text statistics for a DOCX file

officecli view report.docx stats

# JSON-formatted statistics for an XLSX file

officecli view data.xlsx stats --json

# DOCX statistics including total page count (requires Windows + Word)

officecli view thesis.docx stats --page-count

Understanding Output Formats

By default, OfficeCLI produces plain text output optimized for terminal reading. For a Word document, this resembles:

File: report.docx | 42 paragraphs | 3 tables | 8 images | 1 OLE object | 2 equations
Watermark: "Confidential"
Header: "Company Name"
Footer: "Page {PAGE} of {NUMPAGES}"
■ [3] "Executive Summary" (Heading1)
├── [7] "Background" (Heading2)
...

When you append the global --json flag, the output transforms into structured JSON suitable for piping to other tools:

{
  "sheets": [
    {
      "name": "Sheet1",
      "rows": 120,
      "columns": 15,
      "nonEmptyCells": 432,
      "numericCells": 300,
      "stringCells": 132
    }
  ],
  "totalRows": 120,
  "totalColumns": 15,
  "totalNonEmptyCells": 432
}

Plugin Architecture Support

The statistics system extends beyond built-in Office formats through src/officecli/Core/Plugins/FormatHandlerProxy.cs. This proxy delegates stats handling to registered format-handler plugins, enabling custom document types to participate in the view command pipeline.

Summary

• Execute officecli view <file> stats to analyze any supported Office document from the command line
• Use the --json flag for structured output suitable for automation and piping
• Access page-count data for Word documents with --page-count (Windows/Word required)
• Each format handler implements ViewAsStats() and ViewAsStatsJson() in dedicated files: WordHandler.View.cs, ExcelHandler.View.cs, and PowerPointHandler.View.cs
• The CommandBuilder.View.cs file orchestrates mode parsing and output formatting

Frequently Asked Questions

Can I view statistics for multiple files at once?

OfficeCLI processes one file per command invocation. To analyze multiple documents, wrap the command in a shell loop or script that iterates over your target files and aggregates the JSON outputs.

Why does the page count feature require Windows?

The --page-count flag relies on the Microsoft Word COM automation API available only on Windows. According to the source code in CommandBuilder.View.cs (lines 95-104), if Word automation fails, the CLI falls back to rendering the document as HTML and parsing the page count from the DOM structure, though this method may be less accurate than native Word calculation.

What statistics are available for Excel files?

The Excel handler in ExcelHandler.View.cs reports per-sheet metrics including total rows, columns, non-empty cells, and cell-type distributions (numeric versus string). It does not calculate formulas or evaluate cell contents, focusing strictly on structural statistics.

How do I integrate OfficeCLI statistics into a CI/CD pipeline?

Use the --json flag to generate machine-readable output that CI systems can parse. For example: officecli view document.docx stats --json | jq '.paragraphCount' extracts specific metrics for automated quality gates or documentation audits.

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