# Round-Trip Document Serialization in OfficeCLI: Using the Dump and Batch Feature

> Master round-trip document serialization with OfficeCLI's dump and batch commands. Extract OOXML into replayable streams and reconstruct documents losslessly for efficient workflow.

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

---

**OfficeCLI's `dump` and `batch` commands enable lossless round-trip document serialization by extracting OOXML documents into replayable command streams and reconstructing them atomically.**

The `iOfficeAI/OfficeCLI` repository provides a powerful **round-trip document serialization** system that converts Word, PowerPoint, and Excel files into flat, grep-friendly command scripts. These scripts can be version-controlled, inspected, and replayed to recreate identical documents. This guide explains how the `dump` and `batch` pipeline works, with references to the actual implementation in the source code.

## How the Dump Command Extracts Documents

The `dump` command transforms a document into a series of JSON-encoded batch commands. This process starts in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) around lines 1975-1979, where the server validates that `--format batch` is specified—currently the only supported output format.

When executed, `dump` walks through every OOXML part in the source file and emits **declarative `set`/`add`/`remove` commands** that fully describe the document's structure. The [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) file (lines 504-527) contains extensive implementation details for how complex elements are captured:

- **OLE objects, pictures, and ActiveX controls** — serialized with special carriers that preserve binary data
- **Styles, borders, and numbering** — emitted as raw-set or raw-replace commands
- **Custom XML and footnotes** — captured with their full semantic context

Each output line is a self-contained JSON batch item. The format is intentionally **flat and grep-friendly**, making it suitable for diffing, searching, and version control.

## How the Batch Command Reconstructs Documents

The `batch` command serves as the inverse operation, reading dump scripts and rebuilding documents. The entry point in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) (lines 1152-1156) initializes the batch engine, which accepts input from either a file path or stdin via `--input -`.

Key characteristics of the batch engine:

- **Deferred writes** — All changes accumulate in memory until the final commit
- **Atomic rollback** — If any command fails, the entire batch is discarded and original disk state restored (see lines 1312-1315 in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs))
- **Handler-based replay** — The same `WordBatchEmitter` classes that produced the dump interpret each command and recreate exact OOXML parts

This architecture guarantees that a valid dump script will always produce a **bit-for-bit identical reconstruction** when executed against a fresh document.

## The Complete Round-Trip Pipeline

Combining `dump` and `batch` creates a declarative, reversible workflow:

```bash

# Step 1: Extract the document to a batch script

officecli dump source.docx --format batch > source.dump.txt

# Step 2: Replay the script to rebuild the document

officecli batch --input source.dump.txt rebuilt.docx

```

The pipeline supports **streaming without intermediate files**. In [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) (lines 1984-1989), the implementation ensures `dump` writes to stdout and `batch` reads from stdin, enabling this pattern:

```bash
officecli dump source.docx --format batch 2>&1 | \
  officecli batch --input - rebuilt.docx

```

### Verifying Lossless Serialization

A proper round-trip should reach **fixed-point**: dumping the rebuilt document produces identical output to the original dump. This property confirms that the serialization captured all document state without loss.

## Supported Document Formats

The `dump` command currently handles three Office formats. The validation in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) (lines 2027-2029) throws a `CliException` for unsupported extensions:

| Extension | Description |
|-----------|-------------|
| `.docx` | Word documents (full feature support) |
| `.pptx` | PowerPoint presentations |
| `.xlsx` | Excel workbooks |

## Practical Usage Examples

### Example 1: Basic Word Document Round-Trip

```bash
officecli dump resume.docx --format batch > resume.dump
officecli batch --input resume.dump rebuilt-resume.docx

```

### Example 2: Pipe-Based Reconstruction (No Temp Files)

```bash
officecli dump deck.pptx --format batch 2>&1 | \
  officecli batch --input - rebuilt-deck.pptx

```

### Example 3: Inspecting Document Structure

```bash
officecli dump budget.xlsx --format batch | grep 'set /sheet[1]/cell'

```

All commands accept `--json` for machine-readable responses, though the dump-to-batch flow works natively with plain text.

## Key Implementation Files

Understanding these source files clarifies how the round-trip works:

| File | Role |
|------|------|
| [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) | Command dispatcher; validates dump format, streams output, orchestrates batch execution with rollback |
| [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) | Emits detailed OOXML commands; contains "dump→batch" annotations explaining serialization decisions |
| [`SchemaHelpFlatRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpFlatRenderer.cs) | Generates flat schema output used by both `help` and `dump --format batch` |
| [`CommandBuilder.Dump.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Dump.cs) | Command-line parser for `dump`; enforces supported format constraints |
| [`Core/Plugins/DumpReaderInvoker.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Core/Plugins/DumpReaderInvoker.cs) | Plugin hook converting dump files into batch items for execution |

## Summary

- **`dump --format batch`** extracts OOXML documents into JSON-encoded command streams that are flat, grep-friendly, and version-controllable
- **`batch --input`** replays these commands atomically, with automatic rollback on failure
- **Streaming support** allows pipe-based workflows without intermediate files (`2>&1 | --input -`)
- **Fixed-point verification** confirms lossless serialization by re-dumping the rebuilt document
- The implementation spans [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) for orchestration and [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) for format-specific ooXML handling

## Frequently Asked Questions

### What makes the batch format "grep-friendly"?

The dump output uses a flat structure with one JSON object per line and consistent path notation like `set /document/body/p[1]`. This design lets standard Unix tools filter and search document content without parsing complex XML hierarchies. The [`SchemaHelpFlatRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpFlatRenderer.cs) file generates this representation specifically for human and tool consumption.

### Can I edit a dump file manually and still rebuild successfully?

Yes, provided you maintain valid JSON syntax and valid command paths. The batch engine validates each command against the document schema. Invalid commands trigger the rollback mechanism in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) (lines 1312-1315), preventing partial or corrupted rebuilds.

### Does the round-trip preserve all document metadata?

According to the [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) implementation (lines 504-527), the dump captures OLE objects, embedded images, ActiveX controls, styles, borders, custom XML, footnotes, and numbering. The "dump→batch round‑trip" comments throughout the file indicate comprehensive coverage, though password protection and certain legacy formats may require verification.

### How does atomic rollback work in practice?

The batch engine accumulates all changes in memory until the final commit point. If any command throws an exception, the engine discards the in-memory document and leaves any existing disk file untouched. This design, visible in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) lines 1312-1315, ensures that failed batches never produce partially written files.