# OfficeCLI Dump vs Batch Commands: Understanding Document Round-Tripping in iOfficeAI/OfficeCLI

> Understand OfficeCLI dump vs batch commands for document round-tripping. Serialize and recreate documents losslessly with JSON blueprints in iOfficeAI OfficeCLI.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: deep-dive
- Published: 2026-08-05

---

**OfficeCLI's `dump` command serializes documents into replayable JSON blueprints, while `batch` consumes those JSON files to recreate or modify documents—together enabling lossless document round-tripping.**

Both commands serve complementary roles in the OfficeCLI round-trip pipeline, but they operate at opposite ends of the workflow. The `dump` command extracts a complete structured representation from any `.docx`, `.pptx`, or `.xlsx` file, including verbatim binary blobs and OLE objects. The `batch` command replays that JSON to rebuild the document exactly or apply bulk mutations atomically. Understanding this distinction is essential for automation workflows, AI agent integrations, and document template engineering.

## What Is Document Round-Tripping in OfficeCLI?

**Round-tripping** refers to the ability to convert a binary Office document into an editable intermediate format and back again without data loss. In OfficeCLI, this intermediate format is a **batch JSON** structure that captures every element, property, and binary attachment in a machine-readable schema.

According to the iOfficeAI/OfficeCLI source code, both commands share the **resident-server** architecture ([`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs)), which maintains the OOXML document model in memory and routes operations consistently. This design ensures that `dump` extracts from the same in-memory representation that `batch` writes to, eliminating serialization mismatches.

## The Dump Command: Extracting Document Blueprints

`dump` serializes a document (or any subtree) into a replayable JSON format. This output serves as a inspectable, editable, and storable template.

### Key Capabilities

- **Full or partial extraction**: Dump an entire document or target specific subtrees (single tables, slides, worksheets)
- **Verbatim binary preservation**: OLE objects, images, and custom XML are embedded as base64 blobs
- **Human-readable structure**: Pure JSON replaces opaque OOXML for easier reasoning

### Implementation Details

The command is implemented in [`src/officecli/CommandBuilder.Dump.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Dump.cs), which validates the `--format=batch` flag and emits the structured representation.

```bash

# Dump entire document to JSON blueprint

officecli dump existing.docx -o blueprint.json

# Dump specific slide from presentation

officecli dump presentation.pptx --slide 3 -o slide3.json

```

## The Batch Command: Replaying and Mutating Documents

`batch` consumes batch JSON and reconstructs the original document or applies a series of mutations in a single atomic pass.

### Key Capabilities

- **Lossless reconstruction**: Replays dumps to produce byte-identical documents
- **Atomic operation execution**: Multiple commands execute as one transaction
- **Incremental modifications**: Additional operations can be appended to the JSON before replay

### Implementation Details

The command is implemented in [`src/officecli/CommandBuilder.Batch.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Batch.cs), which parses the JSON, validates each operation, and applies them with configurable error handling.

```bash

# Recreate document from JSON blueprint

officecli batch new.docx --input blueprint.json

# Apply edited JSON with mutations

officecli batch modified.docx --input edited.json

```

## Critical Differences: Dump vs Batch

| Aspect | `dump` | `batch` |
|--------|--------|---------|
| **Direction** | Document → JSON | JSON → Document |
| **Primary purpose** | Extraction and inspection | Reconstruction and modification |
| **Granularity** | Selective subtree or full document | Atomic execution of multiple operations |
| **Output** | Replayable batch JSON | Rebuilt Office document |
| **Fidelity guarantee** | Captures verbatim binary data | Restores byte-identical output for supported formats |
| **AI agent use case** | **Learn** document structure from JSON | **Reproduce** or mutate templates programmatically |

## Practical Round-Trip Workflows

### Workflow 1: Lossless Document Copy

Pipe `dump` directly into `batch` for perfect duplication without intermediate files:

```bash
officecli dump source.pptx --format batch | officecli batch copy.pptx --input -

```

### Workflow 2: Agent-Assisted Template Modification

```bash

# 1. Extract blueprint

officecli dump template.docx -o blueprint.json

# 2. Agent inspects/modifies via jq or programmatic JSON editing

jq '.[] | select(.tag=="paragraph" and .attributes.style=="Heading1") | .attributes.text = "Updated Title"' blueprint.json > edited.json

# 3. Rebuild with modifications

officecli batch customized.docx --input edited.json

```

### Workflow 3: Bulk Operations with Error Control

Both commands support `--best-effort` and `--stop-on-error` flags to control atomicity:

```bash

# Stop entire batch if any operation fails

officecli batch critical.docx --input operations.json --stop-on-error

# Continue partial execution, logging failures

officecli batch resilient.docx --input operations.json --best-effort

```

## Resident Server Architecture

Both commands rely on [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) for consistent behavior. When a document opens in **resident mode**, the CLI maintains the OOXML in memory:

- `dump` extracts from this resident model
- `batch` writes directly to the resident model or a fresh document
- The server handles request routing and unified error handling

This shared plumbing ensures that a `dump → batch` sequence yields identical output for supported formats.

## Summary

- **`dump`** extracts documents into editable JSON blueprints with full binary fidelity
- **`batch`** replays JSON to rebuild documents or execute atomic mutations
- **Together** they enable lossless round-tripping: `dump` learns structure, `batch` reproduces and modifies
- **Implementation** resides in [`CommandBuilder.Dump.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Dump.cs) and [`CommandBuilder.Batch.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Batch.cs) with shared [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) infrastructure
- **AI workflows** benefit from JSON's superior inspectability compared to raw OOXML

## Frequently Asked Questions

### Can `dump` and `batch` handle partial document extraction?

Yes. The `dump` command supports subtree targeting—specify slides, tables, or worksheet ranges instead of entire documents. The resulting JSON contains only the selected elements, and `batch` can replay these partial dumps into new documents or merge them into existing ones.

### Do `dump` and `batch` preserve macros and embedded OLE objects?

Yes. The dump format includes verbatim binary blobs for OLE objects, images, and custom XML parts. When `batch` replays this JSON, these elements restore exactly. This preservation is critical for document templates containing embedded Excel charts or legacy ActiveX controls.

### What error handling options exist for `batch` operations?

`batch` supports two mutually exclusive flags: `--stop-on-error` aborts the entire transaction on any failure, while `--best-effort` continues execution and logs errors. This atomicity control is essential for production automation where partial document corruption must be avoided.

### How does the resident mode improve round-trip performance?

Resident mode keeps documents in memory between commands, eliminating repeated disk I/O and ZIP (OOXML) operations. Both `dump` and `batch` leverage this for sub-second operations on large documents, with [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) managing concurrent access and resource cleanup automatically.