# How OfficeCLI dump and batch Commands Enable Round-Trip Serialization of Documents

> Unlock OfficeCLI's round-trip serialization with dump and batch commands. Export documents to JSON batch instructions and reconstruct them perfectly.

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

---

**OfficeCLI achieves round-trip serialization by using the `dump` command to export a document's complete state into replayable JSON batch instructions, which the `batch` command then executes atomically to reconstruct the exact document structure and content.**

The iOfficeAI/OfficeCLI project provides a robust mechanism for serializing and restoring Office documents through its complementary `dump` and `batch` commands. This round-trip serialization capability allows developers to export document states as structured JSON, store or modify those specifications externally, and later reconstruct identical documents from the serialized data. The implementation relies on a specific `BatchItem` protocol that ensures lossless transformation between binary document formats and textual JSON representations.

## The Round-Trip Serialization Workflow

OfficeCLI implements a "dump-and-replay" pattern that captures the exact sequence of operations needed to recreate a document. This workflow consists of two distinct phases: serialization via `dump` and reconstruction via `batch`.

### Serializing Documents with the dump Command

The `dump` command serializes any document or subtree into a replayable batch JSON format. When invoked, the CLI emits a JSON array where each element represents a **batch-item** describing one operation—such as `set`, `add`, or `remove`—together with its arguments and property mappings.

According to the source code in [`sdk/node/index.d.ts`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.d.ts), the SDK defines a strict `BatchItem` type that structures these operations with properties including `command` (or `op`), `path`, and `props`【/cache/repos/github.com/iOfficeAI/OfficeCLI/main/sdk/node/index.d.ts#L3-L19】. The CLI documentation explicitly describes this capability: "`officecli dump <file> [<path>]` emits a replayable batch JSON for round-trip"【/cache/repos/github.com/iOfficeAI/OfficeCLI/main/README.md#L295-L302】.

The `dump` output includes structural information such as paths, selectors, and raw-set values, making it possible to reconstruct complex objects like worksheets, slides, or document parts. The format matches the shape expected by the SDK's `Document.batch` API, ensuring compatibility between export and import operations.

### Reconstructing Documents with the batch Command

The `batch` command replays the JSON produced by `dump` to restore document state. The SDK's `Document.batch` method forwards the entire list of batch-items in a **single round-trip** to the resident, applying all operations atomically (or with best-effort/stop-on-error options depending on configuration).

In [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js), the `Document.batch` method implements this by sending the `batchJson` argument to the resident【/cache/repos/github.com/iOfficeAI/OfficeCLI/main/sdk/node/index.js#L19-L22】. Because the batch JSON encodes the exact sequence of operations that built the original document, applying it restores the document to the state captured by `dump`, completing the round-trip serialization cycle.

## SDK Implementation Details

The round-trip functionality relies on specific methods within the Node.js SDK that handle the transformation between binary documents and JSON representations.

### Document.send and Raw JSON Output

The `dump` command utilizes the `Document.send` method with specific parameters to yield plain-text JSON output. As implemented in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js), the `send` method accepts an `asJson` parameter; when set to `false`, it returns raw text rather than parsed objects【/cache/repos/github.com/iOfficeAI/OfficeCLI/main/sdk/node/index.js#L96-L104】. This allows the `dump` operation to output the batch JSON as a string that can be written directly to files or transmitted to other systems.

### Atomic Batch Processing

The reconstruction phase depends on the `Document.batch` method, which accepts an array of `BatchItem` objects and transmits them efficiently. This method enables the single round-trip restoration of complex documents by bundling all operations into one RPC call, minimizing network overhead while ensuring structural integrity.

## Practical Implementation Examples

### CLI Round-Trip Workflow

Export a workbook or specific subtree to JSON, then replay it into a fresh document:

```bash

# Export entire workbook to JSON

officecli dump myWorkbook.xlsx -o blueprint.json

# Export specific worksheet only

officecli dump myWorkbook.xlsx /Sheet1 -o sheet.json

# Create new document and replay the dump

officecli create newWorkbook.xlsx
officecli batch newWorkbook.xlsx --input blueprint.json

```

### Node.js SDK Implementation

Programmatically serialize and deserialize documents using the SDK:

```javascript
import { open, create } from '@officecli/sdk';
import fs from 'fs';

// Open existing document and dump to JSON
const doc = await open('report.xlsx');
const dumpJson = await doc.send(
  { command: 'dump', path: '/' },
  false  // asJson = false returns raw text
);

await fs.promises.writeFile('report-dump.json', dumpJson);

// Create fresh document and restore from dump
const fresh = await create('report-copy.xlsx');
await fresh.batch(JSON.parse(dumpJson));

```

### Python SDK Implementation

The Python SDK follows an identical pattern for round-trip serialization:

```python
from officecli import open, create
import json

# Serialize existing document

doc = open("report.xlsx")
dump = doc.send({"command": "dump", "path": "/"}, as_json=False)

with open("report-dump.json", "w") as f:
    f.write(dump)

# Deserialize to new document

fresh = create("report-copy.xlsx")
fresh.batch(json.loads(dump))

```

## Use Cases for Round-Trip Serialization

**Template Generation and Cloning**: Export a master document's structure as JSON to create templating systems where base configurations are stored as code rather than binary files.

**LLM-Driven Document Manipulation**: Feed the structured JSON output to language models for intelligent modification of document properties, then replay the modified batch instructions to generate updated documents.

**Version Control Integration**: Store document specifications as human-readable JSON in version control systems, enabling diff-based reviews of structural changes before regenerating binary Office files.

## Summary

- **Round-trip serialization** in OfficeCLI relies on the `dump` command exporting documents to replayable JSON batch instructions and the `batch` command reconstructing documents from those instructions.
- The `BatchItem` type in [`sdk/node/index.d.ts`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.d.ts) defines the structured format that enables lossless serialization of complex document elements【/cache/repos/github.com/iOfficeAI/OfficeCLI/main/sdk/node/index.d.ts#L3-L19】.
- **Document.send** with `asJson=false` captures raw JSON output during the dump phase, while **Document.batch** transmits operations atomically during reconstruction【/cache/repos/github.com/iOfficeAI/OfficeCLI/main/sdk/node/index.js#L96-L104】【/cache/repos/github.com/iOfficeAI/OfficeCLI/main/sdk/node/index.js#L19-L22】.
- This architecture supports templating, cloning, and automated document generation workflows across CLI, Node.js, and Python environments.

## Frequently Asked Questions

### What file formats support round-trip serialization in OfficeCLI?

OfficeCLI supports round-trip serialization for `.docx`, `.xlsx`, and `.pptx` formats, with full coverage for Word documents and comprehensive worksheet support for Excel files. The [`skills/officecli-xlsx/SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/skills/officecli-xlsx/SKILL.md) file provides specific examples for Excel workbook serialization【/cache/repos/github.com/iOfficeAI/OfficeCLI/main/skills/officecli-xlsx/SKILL.md#L210-L214】.

### Can I modify the JSON between dump and batch operations?

Yes, the JSON output from `dump` is standard JSON that can be edited, filtered, or programmatically modified before being fed to `batch`. This enables workflows like removing specific sheets from a workbook, changing formatting properties, or merging multiple dumps into a single document specification.

### How does batch processing handle errors during reconstruction?

The `Document.batch` method supports atomic or best-effort execution modes. When replaying batch items, you can configure whether the operation should stop on the first error or continue with remaining instructions, providing flexibility for partial document reconstruction scenarios.

### Is the round-trip serialization lossless for complex formatting?

According to the CLI documentation and source implementation, the serialization captures paths, selectors, and raw-set values necessary to reconstruct complex objects. While the system aims for lossless round-trips, specific binary embeddings or proprietary metadata may require verification against the target Office application version.