# OfficeCLI Dump Command: Round-Trip Document Automation with Batch

> Learn how the OfficeCLI dump command converts Office docs to JSON for AI agents. Easily modify templates and regenerate documents with the batch command for round-trip automation.

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

---

**The `dump` command converts existing Office documents into replayable batch JSON, enabling AI agents and scripts to capture template structures, modify them programmatically, and regenerate documents via the `batch` command.**

The **OfficeCLI** open-source toolkit provides a deterministic bridge between existing Office templates and automated document generation. The `dump` command serves as the export mechanism that serializes `.docx`, `.pptx`, and `.xlsx` files into portable JSON schemas, while the `batch` command acts as the import mechanism that rebuilds documents from these specifications. Together, they form a lossless round-trip workflow that allows developers to learn from real-world templates rather than manipulating raw OOXML.

## What Is the Dump Command?

The `dump` command extracts the structure of any Office document—or a specific subtree within it—and produces a **replayable batch JSON** file. This JSON follows the exact schema expected by the `batch` command, containing an array of items with `command`, `path`, and `props` fields that describe every element of the document.

Unlike raw OOXML parsing, the dump output is deterministic and human-readable. It describes the document as a series of discrete mutations that `batch` can replay, making it ideal for AI-driven automation where agents need to understand structure without learning complex XML schemas.

## How Dump Works Under the Hood

When the CLI receives a `dump` instruction, the resident server invokes `ResidentServer.ExecuteDump` to serialize the document structure. According to the OfficeCLI source code in [`/src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main//src/officecli/ResidentServer.cs) (lines 1126-1128), this method validates the `--format=batch` option and writes the JSON payload directly to the output pipe.

Key implementation details include:

- **`ResidentServer.ExecuteDump`**: Handles the `dump` verb and generates the batch JSON stream.
- **`ReadOnlyBatchVerbs`**: Located at lines 1556-1557 in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), this set includes `"dump"` to ensure that pure dump operations do not trigger unnecessary preview refreshes, treating them as read-only.
- **Batch Schema Compatibility**: The output uses the same item structure that `Document.batch` expects, as defined in [`/sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main//sdk/node/index.js) (lines 19-22), enabling seamless interoperability.

## Round-Trip Operations: From Dump to Batch

The primary purpose of the `dump` command is to enable **round-trip document automation**. This workflow allows you to extract a template, modify its specification programmatically, and regenerate a new document with those modifications.

The process follows three distinct steps:

1. **Export**: Run `officecli dump <file> [<path>] -o <output>.json` to capture the document structure.
2. **Modify**: Edit the generated JSON to change text values, add elements, or adjust properties using standard tools like `jq` or programmatic manipulation.
3. **Import**: Execute `officecli batch <new-file> --input <modified>.json` to replay the modified batch items into a new document.

Because the JSON schema is identical between dump output and batch input, this round-trip is lossless—dumping and immediately batching yields a byte-for-byte identical file (barring intentional edits).

## Code Examples for Round-Trip Workflows

### Command-Line Round-Trip

The following example demonstrates converting a Word template to JSON, modifying the title, and generating a new document:

```bash

# Dump the entire document structure to JSON

officecli dump template.docx -o blueprint.json

# Modify the title using jq

jq '.[] | select(.path=="/body/p[1]") .props.text = "New title"' blueprint.json > edited.json

# Re-create the document with modifications

officecli batch new.docx --input edited.json

```

### Node SDK Implementation

For Node.js applications, use the SDK to dump, modify, and batch programmatically:

```javascript
const { open, batch } = require('@officecli/sdk');

(async () => {
  // Open existing template in resident mode
  const doc = await open('template.pptx');

  // Dump the presentation to batch JSON
  const dumpResult = await doc.send({ command: 'dump', format: 'batch' }, false);
  const batchItems = JSON.parse(dumpResult);

  // Modify the first slide title
  batchItems[0].props.title = 'AI-Generated Deck';

  // Apply the modified batch to create a new file
  await batch(batchItems, { force: true, stopOnError: false });
})();

```

### Python SDK Equivalent

The Python SDK mirrors this functionality for batch automation scripts:

```python
import officecli
import json

doc = officecli.open('template.xlsx')

# Extract the first worksheet as batch items

dump = doc.send({'command': 'dump', 'format': 'batch'}, as_json=False)
batch_items = json.loads(dump)

# Update a specific cell value

for item in batch_items:
    if item['path'] == '/Sheet1/A1':
        item['props']['text'] = '42'

# Generate the new workbook

officecli.batch('new.xlsx', items=batch_items)

```

## Summary

- The **OfficeCLI dump command** converts `.docx`, `.pptx`, and `.xlsx` files into replayable batch JSON, serving as a portable document specification.
- **`ResidentServer.ExecuteDump`** in [`/src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main//src/officecli/ResidentServer.cs) (lines 1126-1128) handles the core serialization logic, while `ReadOnlyBatchVerbs` (lines 1556-1557) optimizes read-only operations.
- The **round-trip workflow** enables template learning: dump existing documents, modify the JSON programmatically, and regenerate via `batch`.
- This approach is **lossless** when no edits are made, producing byte-for-byte identical output because both commands use the same schema defined in [`/sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main//sdk/node/index.js).
- Supported formats include Word documents, PowerPoint presentations, Excel workbooks, and specific subtrees within these files.

## Frequently Asked Questions

### What file formats does the dump command support?

The `dump` command supports modern Office Open XML formats including `.docx` (Word), `.pptx` (PowerPoint), and `.xlsx` (Excel). It can extract either the complete document or a specific subtree by providing an optional path argument, making it flexible for template partials.

### Is the round-trip between dump and batch truly lossless?

Yes, the round-trip is deterministic and lossless when no modifications are made to the intermediate JSON. Because `dump` outputs the exact batch item schema that `batch` expects—including `command`, `path`, and `props` fields—replaying an unedited dump yields a byte-for-byte identical document.

### How does dump handle document subsets or subtrees?

You can dump specific portions of a document by appending a path argument to the dump command. For example, `officecli dump template.docx /body/p[2] -o paragraph.json` extracts only the second paragraph. This subtree dump still produces valid batch JSON that can be replayed into new documents.

### Can I use the dump command without the batch command?

While `dump` functions independently for inspection and analysis, its primary design purpose is to feed the `batch` command. The JSON output is specifically structured as batch items, making it most valuable when used in the round-trip workflow described in [`/README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main//README.md) (lines 295-303). For read-only analysis, the command operates as a standalone exporter.