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

> Export document structure with the OfficeCLI dump command. Serialize Word, PowerPoint, or Excel files into a JSON batch script for easy debugging and reconstruction. Learn more today.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-08-08

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Dump.cs) (lines 18-23), the `dumpPathArg` supports queries like `/body/p[2]` for the second paragraph:

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

```

For PowerPoint, target specific slides:

```bash
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`:

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

```

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

```json
{"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`:

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.