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

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

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

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:

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 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 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.

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