OfficeCLI Dump Command: Round-Trip Document Automation with Batch

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 (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, 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 (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:

# 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:

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:

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 (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.
• 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 (lines 295-303). For read-only analysis, the command operates as a standalone exporter.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}