How to Perform Round-Trip Document Serialization and Replay with OfficeCLI dump and batch Commands

OfficeCLI converts Word, Excel, and PowerPoint documents into deterministic, replayable batch JSON via the dump command, allowing verbatim reconstruction using the batch command for reliable round-trip document serialization.

The iOfficeAI/OfficeCLI repository provides a robust command-line toolkit for Office document automation, with round-trip document serialization serving as its core architectural pattern. This two-step workflow enables developers to serialize complex document structures—including charts, OLE objects, SmartArt, and conditional formatting—into structured JSON, manipulate that representation programmatically or through version control, and replay the exact state into new or existing files without data loss.

Understanding the dump Command

The dump command serializes any Office document (.docx, .pptx, or .xlsx) into a JSONL stream (one JSON object per batch item) that follows the OfficeCLI batch-item format. This output encodes the precise sequence of operations required to reconstruct the document's structure and content.

Command Syntax and JSONL Output

By default, dump processes the entire document root (/). You can limit scope by specifying a subtree path, such as a specific worksheet, slide, or table. The -o flag directs output to a file, while omitting it streams to STDOUT for piping.

# Dump entire document

officecli dump my-template.docx -o blueprint.json

# Dump specific worksheet from Excel

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

# Dump single slide from PowerPoint

officecli dump pitch.pptx /slide[3] -o slide3.json

Implementation in the Node SDK

The dump verb is implemented in sdk/node/index.js, where the --json switch maps to a "plain-text dump" request that generates the replayable batch JSON. According to the source code at lines 503–507, this implementation handles all three document types uniformly, ensuring consistent serialization behavior across Word, Excel, and PowerPoint files.

Reference documentation in README.md (lines 295–302) and skills/officecli-xlsx/SKILL.md (lines 210–214) provides concrete usage examples for Excel workbooks, demonstrating how the command captures workbook-level resources such as named ranges and settings.

Replaying Documents with the batch Command

The batch command consumes the JSONL produced by dump and re-executes each item as if the user had typed the equivalent CLI commands individually. Because the JSON encodes exact OfficeCLI operations, the replay is deterministic and lossless.

Targeting New vs Existing Files

The batch command accepts either a new file path (creating the document) or an existing file path (applying changes to the current state). Use the --input flag to specify the JSON source.

# Create new document from dump

officecli batch new.docx --input blueprint.json

# Apply dumped worksheet to existing workbook

officecli batch financials-copy.xlsx --input sheet.json

STDIN Piping for Direct Round-Trips

For immediate round-trip document serialization without intermediate files, pipe the dump output directly into batch. When --input is omitted, the command reads from STDIN.

officecli dump source.pptx | officecli batch copy.pptx

This piped workflow is documented in README.md (lines 527–529) under the "Round-trip dump → batch JSON" section, emphasizing its utility for automated pipelines and shell scripts.

Practical Round-Trip Workflows

The dump-batch pipeline supports three primary enterprise use cases that leverage round-trip document serialization for automation and governance.

Template Cloning

Dump an existing template to JSON, edit the structured data (e.g., replacing placeholder text or updating sheet names), then batch the modified JSON into hundreds of new files. This approach eliminates manual template corruption risks and ensures consistent formatting across generated documents.

LLM-Driven Document Generation

Large language models read the structured JSON to understand human-authored document architectures, modify the serialized representation according to business rules, and feed the altered JSON back to OfficeCLI via the batch command. This enables AI-assisted document generation while preserving complex formatting and object relationships.

Version Control and Diffing

Store the dump JSON in Git or other VCS systems to track document evolution through code review workflows. Because the JSON is human-readable text, diffs reveal precise structural changes (e.g., "added conditional formatting to cell B4") rather than binary blob differences, enabling precise rollbacks and audit trails.

Extending Serialization with Plugins

The plugin architecture defined in plugins/plugin-protocol.md (lines 30–33) supports a dump-reader plugin kind that allows third-party converters to emit batch JSON for the batch runner. This extensibility ensures the dump-batch pipeline can consume foreign formats and legacy document types while maintaining the same replayable output format.

Summary

• OfficeCLI enables deterministic round-trip document serialization through the dump and batch command pair.
• The dump command outputs JSONL (one JSON object per line) that encodes exact document structure, implemented in sdk/node/index.js with the --json flag.
• The batch command replays JSONL into new or existing files deterministically, supporting both --input file paths and STDIN piping.
• Subtree paths (e.g., /Sheet1, /slide[3]) allow partial document serialization for targeted updates.
• Plugin support via the dump-reader kind in plugins/plugin-protocol.md extends the pipeline to custom formats.

Frequently Asked Questions

What file formats does round-trip document serialization support?

OfficeCLI supports round-trip document serialization for Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files. According to the source code in sdk/node/index.js, the dump implementation handles all three formats uniformly through the Node SDK, capturing complex objects like charts, OLE objects, SmartArt, and conditional formatting.

Can I edit the JSON between dump and batch operations?

Yes. The JSONL output from dump is human-readable and editable. You can modify sheet names, replace placeholder text, adjust cell values, or transform structural elements using any text editor or programmatic JSON manipulation library before feeding the modified file to the batch command.

Is the batch replay operation lossless?

The replay is deterministic and lossless provided the target file already contains any required workbook-level resources (such as named ranges, global settings, or themes) when applying partial dumps. The batch command re-executes each JSON item as if typing the original CLI commands, preserving formatting and object relationships exactly as captured in the serialization.

How do I dump only a specific part of a document?

Append a subtree path to the dump command. For Excel, use paths like /Sheet1 or /Sheet1/tables[0]. For PowerPoint, use /slide[3] to target specific slides. This limits the JSONL output to the specified subtree, enabling lightweight serialization of large documents or targeted updates to specific sections.

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