# OfficeCLI Document Serialization with `dump` and `batch` Commands: A Complete Guide

> Master OfficeCLI document serialization using dump and batch commands. Export any part of Office docs to JSON and rebuild with guaranteed round-trip fidelity. Learn more.

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

---

**Use the `officecli dump` command to export any portion of a Word, PowerPoint, or Excel document as a reproducible JSON batch script, then replay it with `officecli batch` to rebuild the same document with guaranteed round-trip fidelity."

The **OfficeCLI** toolset provides a powerful document serialization pipeline that lets you treat Office documents as version-controlled, scriptable artifacts. According to the `iOfficeAI/OfficeCLI` source code, the `dump` and `batch` commands work together to enable **round-trip fidelity**, **atomic rollback**, and **consistent warning handling** across `.docx`, `.pptx`, and `.xlsx` files.

## How Document Serialization Works in OfficeCLI

OfficeCLI's serialization architecture separates **extraction** (`dump`) from **reconstruction** (`batch`). Each command is implemented in dedicated builder classes that coordinate with format-specific emitters and a resident server for long-running sessions.

### Core Components of the Serialization Pipeline

| Component | Responsibility | Key Source File |
|-----------|--------------|---------------|
| **CommandBuilder.Dump.cs** | Builds the `dump` verb, validates arguments, marshals subtrees into JSON | [`src/officecli/CommandBuilder.Dump.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Dump.cs) |
| **CommandBuilder.Batch.cs** | Parses JSON payloads, drives replay engine, handles error modes | [`src/officecli/CommandBuilder.Batch.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Batch.cs) |
| **ResidentServer.cs** | Hosts persistent process, dispatches requests, implements atomic rollback | [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) |
| **BatchExecutor** | Shared replay loop for resident and non-resident paths | [`src/officecli/Core/BatchExecutor.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/BatchExecutor.cs) |
| **BatchCompat** | Normalizes legacy dumps, adds meta items, converts newline encodings | [`src/officecli/Core/BatchCompat.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/BatchCompat.cs) |
| **WordBatchEmitter / PptxBatchEmitter / ExcelBatchEmitter** | Walk OOXML DOM, emit raw-set commands, report non-round-trippable elements | `src/officecli/Handlers/*` |

## The `dump` Command: Exporting Document State

The `dump` command extracts a specified subtree of an Office document and serializes it as a compact JSON array of batch commands. This enables **document-as-code** workflows where any structural state can be captured, versioned, and replayed.

### Dump Command Implementation Details

In [`CommandBuilder.Dump.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Dump.cs), the dump flow follows this sequence:

1. **Extension validation** — accepts `.docx`, `.pptx`, `.xlsx` only
2. **Resident routing** — `TryResident` forwards to existing process if file is already open (lines 72-79 in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs))
3. **Handler instantiation** — `DocumentHandlerFactory.Open` creates read-only format handler
4. **Subtree emission** — `WordBatchEmitter`, `PptxBatchEmitter`, or `ExcelBatchEmitter` walks DOM and returns `List<BatchItem>` plus warnings
5. **Meta item prepending** — `BatchCompat.MetaItem()` adds `{"command":"meta","dumpVersion":1}` for version tracking
6. **Warning handling** — emits to **stderr** when `--json` or `--out` is used, preserving clean `dump | batch` pipes
7. **JSON serialization** — compact output via `JsonSerializer.Serialize`

### Practical Dump Examples

Export an entire Word document body to JSON:

```bash
officecli dump report.docx /body -o body.json

```

Stream dump output directly to batch without intermediate file:

```bash
officecli dump report.docx /body --json | officecli batch new.docx --input -

```

Dump with explicit format specification (currently `batch` is the only supported format):

```bash
officecli dump presentation.pptx /slides/slide1 --format batch -o slide1.json

```

## The `batch` Command: Replaying Document Scripts

The `batch` command reconstructs document state by executing a JSON array of batch items. It supports multiple input sources and fine-grained control over error handling and atomicity.

### Batch Command Error Handling Modes

| Flag | Behavior | Source Location |
|------|----------|-----------------|
| *(default)* | **Continue-on-error**: execute all items, collect failures | [`CommandBuilder.Batch.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Batch.cs), lines 64-70 |
| `--stop-on-error` | **Atomic**: abort on first failure, trigger rollback if resident | Lines 38-40 in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) |
| `--best-effort` | **Legacy mode**: apply what succeeds, no rollback | Lines 74-88 in [`CommandBuilder.Batch.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Batch.cs) |

### Batch Command Implementation Details

In [`CommandBuilder.Batch.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Batch.cs), the batch flow handles:

- **Input source detection** — warns when both `--commands` and stdin are supplied (conflicting sources raise errors at lines 74-88)
- **Inline help** — `BatchHelpDescription` documents JSON shape directly in CLI
- **Resident dispatch** — routes to `ResidentServer.ExecuteBatch` for active sessions

The `ResidentServer.ExecuteBatch` method (lines 38-58) implements **atomic rollback**:

1. Flush pre-batch state to disk
2. Apply batch in-memory
3. On any failure, discard poisoned DOM and reload from saved state
4. Restore pending whole-part payloads
5. Set `_lastBatchHadFailure` for exit code propagation

### Practical Batch Examples

Atomic batch with automatic rollback:

```bash
officecli batch report.docx --input body.json --stop-on-error

```

Best-effort application with partial success:

```bash
officecli batch report.docx --input body.json --best-effort

```

Inline commands without file:

```bash
officecli batch template.docx --commands '[{"command":"meta","dumpVersion":1},{"command":"raw-set","path":"/body/p[1]","value":"Updated"}]'

```

## Batch File Format and Structure

The JSON batch format is an ordered array of `BatchItem` objects. The `BatchCompat` class in [`src/officecli/Core/BatchCompat.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/BatchCompat.cs) ensures forward and backward compatibility.

### Example Batch File Structure

```json
[
  { "command": "meta", "dumpVersion": 1 },
  { "command": "raw-set", "path": "/body/p[1]/r[1]", "value": "Hello World" },
  { "command": "raw-set", "path": "/body/p[2]/r[1]", "value": "Second paragraph" },
  { "command": "raw-set", "path": "/body/p[2]/r[1]/rPr/b", "value": "1" }
]

```

### Compatibility Features

- **Meta item**: Required first element; declares `dumpVersion` for newline handling decisions
- **Newline encoding**: Legacy `\n` rewritten to `\v` (vertical tab) to avoid JSON serialization issues
- **Warning accumulation**: Non-fatal issues (unrecognized LaTeX, unsupported elements) collected per-item

## Format-Specific Emitters

Each Office format has dedicated emitter logic in `src/officecli/Handlers/`:

### WordBatchEmitter.cs

- Walks WordprocessingML DOM
- Emits `raw-set` for text runs, paragraph properties, and styles
- Reports **custom XML parts** and **OLE objects** as warnings (non-round-trippable)

### PowerPointBatchEmitter.cs

- Handles SlideML and DrawingML subtrees
- Emits shape modifications, text frame updates, and slide layout changes
- Tracks **embedded media** and **legacy VML shapes** for warning output

### ExcelBatchEmitter.cs

- Processes SpreadsheetML worksheets, shared strings, and styles
- Emits cell value sets, formula updates, and formatting commands
- Reports **external links** and **pivot cache** elements as warnings

All emitters return both the `List<BatchItem>` and `List<CliWarning>` to the dump orchestrator in [`CommandBuilder.Dump.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Dump.cs).

## Using the Resident Server for Document Serialization

The **resident server** eliminates file lock contention and enables **true atomic transactions**. When a document is opened in resident mode, subsequent `dump` and `batch` commands operate on the in-memory DOM.

### Resident Flow for Dump

```bash

# Start resident (document stays open in background)

officecli resident start report.docx

# Multiple dumps without reopening

officecli dump report.docx /body -o body.json
officecli dump report.docx /tables/tbl1 -o table.json

```

### Resident Flow for Atomic Batch

```bash
officecli resident start report.docx

# This batch is atomic: any failure triggers full rollback

officecli batch report.docx --input body.json --stop-on-error

# Exit code reflects batch success/failure

echo $?

```

In [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) (lines 12-38), rollback is implemented by:

1. Saving current DOM state to temporary file
2. Executing batch items via `ApplyBatchItems`
3. On failure: disposing corrupted DOM, reloading from temp file, restoring payloads

## Pipeline Patterns and Best Practices

### Version Control Integration

```bash

# Extract document structure for git tracking

officecli dump spec.docx / -o spec-structure.json
git add spec-structure.json

# Later: reconstruct for review

officecli batch spec.docx --input spec-structure.json

```

### CI/CD Document Generation

```bash

# Template + data = rendered document (non-resident, best-effort)

officecli dump template.docx / -o template.json
cat template.json | sed 's/{{VERSION}}/'"$VERSION"'/g' | \
  officecli batch output.docx --input -

```

### Cross-Format Migration

```bash

# Extract content from Word

officecli dump source.docx /body -o content.json

# Transform JSON (custom script)

python transform_json.py content.json > excel-items.json

# Apply to Excel (structure-aware adapter required)

officecli batch target.xlsx --input excel-items.json --best-effort

```

## Summary

- **The `dump` command** extracts any document subtree as a reproducible JSON batch script, with warnings routed to stderr to preserve pipe cleanliness
- **The `batch` command** replays batch items with three error modes: default continue-on-error, strict `--stop-on-error` with atomic rollback, and legacy `--best-effort`
- **Atomic rollback** in resident mode guarantees document integrity: pre-batch state is preserved, failures trigger DOM reload from disk
- **Format-specific emitters** in [`WordBatchEmitter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordBatchEmitter.cs), [`PowerPointBatchEmitter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointBatchEmitter.cs), and [`ExcelBatchEmitter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelBatchEmitter.cs) handle OOXML DOM walking and warn about non-round-trippable elements
- **Pipeline compatibility** is designed into warning handling: `dump --json | batch --input -` works reliably because warnings bypass stdout

## Frequently Asked Questions

### What file formats does OfficeCLI document serialization support?

OfficeCLI supports **Word** (`.docx`), **PowerPoint** (`.pptx`), and **Excel** (`.xlsx`) files. The `dump` command validates extensions in [`CommandBuilder.Dump.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Dump.cs) and routes to the appropriate emitter. Other Office formats like `.doc`, `.ppt`, and `.xls` (binary formats) are not supported.

### Why does `dump` output go to stdout but warnings go to stderr?

This design enables **reliable shell pipelines**. When you run `officecli dump ... --json | officecli batch ... --input -`, the JSON stream must be clean. Warnings are diverted to stderr (triggered by `--json` flag or `--out` to file) so they don't corrupt the piped data. See lines 85-99 in [`CommandBuilder.Dump.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Dump.cs) for the `warnToStderr` logic.

### How does atomic rollback work in resident mode?

When `--stop-on-error` is used with a resident server, `ResidentServer.ExecuteBatch` (lines 38-58) saves the pre-batch DOM to a temporary file, executes all items in memory, and monitors for failures. If any item fails, it disposes the corrupted in-memory document, reloads from the temporary file, and restores any pending whole-part payloads—leaving the original document completely unchanged.

### Can I edit a batch JSON file manually?

Yes. The format is intentionally human-readable: each `raw-set` command specifies a DOM path and value. However, be aware that `BatchCompat.PrepareForReplay` in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) validates and normalizes the input. Invalid paths will generate errors during replay, and `--best-effort` mode will skip them rather than fail.