How to Use the OfficeCLI Dump Command to Export Document Structure for Debugging

The OfficeCLI dump command serializes Word, PowerPoint, or Excel files into a replay-able JSON batch script that can reconstruct the original document via the batch run command.

The dump command in the iOfficeAI/OfficeCLI repository converts complex Office documents into deterministic, text-based representations. This export capability enables developers to debug document structures, version-control content changes, and create automated testing pipelines for Office file manipulation.

What Is the OfficeCLI Dump Command?

The OfficeCLI dump command is a built-in operation that extracts the internal structure of .docx, .pptx, or .xlsx files and serializes them as a compact JSON array of BatchItem objects. According to the source code in src/officecli/CommandBuilder.Dump.cs (lines 13-37), the command registers with arguments for the target file, an optional subtree path, output format, and destination.

The resulting output serves as a replay-able batch script that the batch run command can consume to reconstruct the original document or any subset of it. This round-trip capability makes dump essential for debugging document generation issues and verifying structural integrity.

Supported File Types and Formats

The command enforces strict file type validation at lines 50-53 of CommandBuilder.Dump.cs, accepting only:

• .docx (Word documents)
• .pptx (PowerPoint presentations)
• .xlsx (Excel spreadsheets)

Currently, the --format parameter supports only the batch format. The implementation explicitly checks if (format != "batch") and raises a CliException for any other value (lines 46-48). This limitation ensures compatibility with the BatchItem schema used by the batch processing system.

How the Dump Command Works Internally

Understanding the internal flow helps troubleshoot export failures and optimize performance for large documents.

Resident Server Routing

To avoid file-lock contention when the target document is already open, the command attempts to reuse an existing OfficeCLI resident process. The TryResident(file.FullName, ...) method (lines 68-79) routes the request through ResidentServer.cs if a matching process holds the file handle.

Handler Selection and Emission

The command opens the document via DocumentHandlerFactory.Open and dispatches to format-specific emitters based on file extension:

• WordBatchEmitter.EmitWordWithWarnings for .docx files
• PptxBatchEmitter.EmitPptx for .pptx files
• ExcelBatchEmitter.EmitExcel for .xlsx files

This routing occurs in the handler selection block (lines 98-160), where each emitter converts the document's OpenXML structure into the standardized BatchItem format.

Warning Handling and Serialization

Unsupported document elements generate CliWarning objects that populate both the internal warning list and stderr (lines 85-102). The final JSON array serializes using JsonSerializer.Serialize with the source-generated context BatchJsonContext.Default.ListBatchItem (lines 186-188), ensuring high-performance serialization without reflection.

Using the Dump Command for Debugging

Export document structures to isolate formatting issues or create reproducible test cases.

Dumping Complete Documents

Generate a full structural export to stdout:

officecli dump mydoc.docx

This outputs a compact JSON array representing every paragraph, table, and formatting instruction in the document.

Exporting Specific Document Subtrees

Use the optional path argument to target specific elements using XPath-like syntax. In CommandBuilder.Dump.cs (lines 18-23), the dumpPathArg supports queries like /body/p[2] for the second paragraph:

officecli dump mydoc.docx "/body/p[0]"

For PowerPoint, target specific slides:

officecli dump presentation.pptx "/slide[2]" -o slide2.dump.json

File Output and JSON Envelopes

Write dumps to files and receive structured success confirmations using --out and --json:

officecli dump mydoc.docx --out mydoc.dump.json --json

The file receives the raw batch JSON, while stdout prints an envelope via OutputFormatter.WrapEnvelope:

{"success":true,"data":{"outputFile":"mydoc.dump.json","itemCount":42}}

Specify --out - to force stdout output even when using other flags.

Round-Trip Testing

Verify dump integrity by piping the output directly into batch run:

officecli dump mydoc.docx | officecli batch run

This recreates the document from the serialized instructions, confirming that the export captured all necessary structural data.

Command Options Reference

The dump command accepts the following arguments defined in the command builder:

Argument	Description	Source Reference
file	Path to the .docx, .pptx, or .xlsx file	Lines 13-15
path	Optional subtree selector (e.g., /body/p[0])	Lines 18-23
--format	Output format (currently only batch)	Lines 46-48
--out	Output destination (- for stdout, or filepath)	Lines 92-105
--json	Wrap output in success envelope with warnings	Lines 124-133

When --out specifies a file path, the implementation uses File.WriteAllText(outPath, output + "\n") to ensure the JSON ends with a newline (lines 104-105). Warnings write to stderr when output redirects to a file or when --json mode is active.

Summary

• The OfficeCLI dump command converts Office documents into JSON batch scripts that batch run can replay to reconstruct the original file.
• Supported formats include .docx, .pptx, and .xlsx, with only the batch format currently available for export.
• The implementation in src/officecli/CommandBuilder.Dump.cs uses DocumentHandlerFactory.Open and specialized emitters (WordBatchEmitter, PptxBatchEmitter, ExcelBatchEmitter) to serialize document structures.
• Use the path argument to export specific subtrees for targeted debugging, and leverage --json for structured output suitable for CI/CD pipelines.
• The TryResident routing prevents file-lock errors when dumping documents that are currently open in other processes.

Frequently Asked Questions

What file types does the OfficeCLI dump command support?

The command validates file extensions in CommandBuilder.Dump.cs (lines 50-53) and accepts only .docx, .pptx, and .xlsx files. Attempting to dump other formats raises a validation error before processing begins.

Can I dump only a specific part of a document?

Yes. The optional path argument accepts XPath-like selectors to target specific document subtrees. For Word documents, use /body/p[N] for paragraphs; for PowerPoint, use /slide[N] for individual slides. This feature isolates specific elements for focused debugging without exporting the entire file structure.

How do I use the dump output to recreate a document?

Pipe the JSON output directly into the batch run command: officecli dump mydoc.docx | officecli batch run. The batch command interprets the BatchItem array and reconstructs the document structure, enabling deterministic round-trip testing and document generation automation.

What is the resident server and why does dump use it?

The resident server is a background process implemented in src/officecli/ResidentServer.cs that holds file handles to avoid repeated application startup costs. The dump command calls TryResident (lines 68-79) to check if the target file is already managed by a resident process, preventing file-lock conflicts and improving performance for repeated operations on the same document.

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