How to Get Document Statistics Using OfficeCLI: Complete Command-Line Guide

Use officecli view <file> stats to generate detailed statistical summaries of Word, Excel, and PowerPoint documents, with optional JSON output via the --json flag.

The OfficeCLI tool from the iOfficeAI/OfficeCLI repository provides a unified command-line interface for analyzing Microsoft Office documents without opening the GUI. The view command with the stats mode enables developers and technical writers to extract comprehensive metadata—including paragraph counts, table structures, font usage, and page counts—directly from the terminal.

The view stats Command Syntax

OfficeCLI exposes document analysis through the view command's stats mode. When you execute officecli view <file> stats, the CLI parses the mode argument in src/officecli/CommandBuilder.View.cs (lines 14–16) and dispatches to a format-specific handler via the DocumentHandlerFactory.

The command structure supports three primary use patterns:

# Basic text statistics

officecli view document.docx stats

# JSON-formatted output

officecli view spreadsheet.xlsx stats --json

# Word documents with page count (Windows only)

officecli view report.docx stats --page-count

Word Document Statistics (DOCX)

For Word documents, the WordHandler.View.cs file implements the statistical analysis starting at line 11. The ViewAsStats() method in WordHandler generates a line-by-line summary that includes:

• Paragraph counts and empty paragraph detection
• Table and image counts
• Style and font usage statistics
• Character totals and double-space detection
• OLE objects and equations

The handler also provides ViewAsStatsJson() for structured output. If you specify the --page-count flag, the CLI attempts to obtain an accurate page count from Word on Windows; if that fails, it falls back to an HTML render extraction (handled in CommandBuilder.View.cs, lines 95–104).

Sample text output:

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)

Excel Spreadsheet Statistics (XLSX)

Excel statistical analysis is implemented in ExcelHandler.View.cs. The ViewAsStats() method aggregates sheet-level metrics including:

• Row and column counts per sheet
• Total non-empty cell counts
• Cell-type breakdowns (numeric vs. string)
• Aggregate totals across all worksheets

Sample JSON output:

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

PowerPoint Presentation Statistics (PPTX)

For PowerPoint files, PowerPointHandler.View.cs provides the ViewAsStats() implementation. This handler tallies presentation-level metrics including:

• Total slide count
• Shape and picture counts
• Table statistics
• Chart objects

Working with JSON Output

By default, all statistics render as human-readable text. To receive structured data suitable for piping to other tools, append the global --json flag to any view command. The JSON path is guarded by the same mode check (modeKey is "stats") in CommandBuilder.View.cs, ensuring consistent output structure across all document types.

# Get JSON statistics for a PowerPoint file

officecli view presentation.pptx stats --json

Understanding the Handler Architecture

The statistics functionality relies on a handler pattern defined in the source code:

• src/officecli/CommandBuilder.View.cs: Parses arguments and routes to the appropriate handler
• src/officecli/Handlers/Word/WordHandler.View.cs: DOCX-specific statistics and optional page counting
• src/officecli/Handlers/Excel/ExcelHandler.View.cs: XLSX spreadsheet metrics
• src/officecli/Handlers/Pptx/PowerPointHandler.View.cs: PPTX presentation data
• src/officecli/Core/Plugins/FormatHandlerProxy.cs: Delegates handling for custom format plugins

Each handler implements the IDocumentHandler interface, providing both ViewAsStats() and ViewAsStatsJson() methods to support dual output formats.

Summary

• Use officecli view <file> stats to extract statistics from any supported Office document
• Word statistics include paragraph counts, style analysis, and optional page counts (Windows only)
• Excel output provides sheet-level metrics with cell-type breakdowns available in JSON format
• PowerPoint statistics cover slides, shapes, pictures, tables, and charts
• Add --json for machine-readable output suitable for automation scripts
• The implementation spans CommandBuilder.View.cs and format-specific handlers in the src/officecli/Handlers/ directory

Frequently Asked Questions

How do I output document statistics as JSON?

Append the --json flag to your view command: officecli view file.docx stats --json. This invokes the ViewAsStatsJson() method in the respective handler, returning structured data instead of plain text.

Why is the page count feature unavailable on my system?

The --page-count option for DOCX files requires Microsoft Word installed on Windows. According to the implementation in CommandBuilder.View.cs (lines 95–104), the CLI first attempts to obtain the count from Word; if Word is unavailable, it falls back to HTML rendering, which may be less accurate.

What statistics are included for Excel versus Word files?

Excel statistics focus on structural grid data: rows, columns, and cell types via ExcelHandler.View.cs. Word statistics emphasize content composition: paragraphs, styles, fonts, and formatting issues like double spaces or empty paragraphs, implemented in WordHandler.View.cs starting at line 11.

Where is the stats mode logic implemented in the OfficeCLI source code?

The mode argument parsing occurs in src/officecli/CommandBuilder.View.cs. Each document type implements specific statistics gathering in dedicated view files: WordHandler.View.cs, ExcelHandler.View.cs, and PowerPointHandler.View.cs. Plugin handlers delegate through FormatHandlerProxy.cs.

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