OfficeCLI Dump and Batch Round-Trip Workflow: Complete Guide to Document Cloning

The OfficeCLI dump and batch round-trip workflow serializes any Office document into a replayable JSON script and re-applies it to a blank document, enabling lossless cloning across Word, PowerPoint, and Excel files.

The iOfficeAI/OfficeCLI repository provides a powerful command-line interface for manipulating Office documents programmatically. The OfficeCLI dump and batch round-trip workflow represents the most reliable method for cloning documents or migrating content between environments by converting document structures into executable batch commands.

How the OfficeCLI Dump and Batch Round-Trip Workflow Works

This four-step process converts document elements into logical commands that can be replayed identically on any target file.

Step 1: Serialize the Source Document with dump

The dump command creates a batch-compatible JSON array describing every element in the requested subtree.

officecli dump source.docx / --format batch --out source.dump.json

• The / argument targets the entire document (default path).
• This command is implemented in CommandBuilder.Dump.cs (lines 13-34), which parses arguments and writes the batch JSON.
• The output contains a list of BatchItem objects representing operations like add, set, and remove.
• Any warnings (e.g., unsupported elements) are emitted on stderr, ensuring the JSON payload remains valid for replay.

Step 2: Initialize a Blank Target Document

Create a fresh document to receive the cloned content. The target must exist before running the batch command.

officecli create target.docx

The blank document can be any supported Office format, though the format must match the source for the batch to replay correctly.

Step 3: Replay Commands with batch

The batch command reads the JSON array and executes each BatchItem in order, rebuilding the original structure inside the new file.

officecli batch target.docx --input source.dump.json

• The implementation resides in CommandBuilder.Batch.cs (lines 18-33).
• Internally, ApplyBatchItems orchestrates the process, calling ExecuteBatchItem for each entry.
• Format-specific handlers (WordHandler, PowerPointHandler, ExcelHandler) recreate the document structure.
• By default, execution uses continue-on-error mode; append --stop-on-error to abort on the first failure.

Step 4: Verify the Cloned Output

Confirm successful cloning using the view command to inspect the document structure.

officecli view target.docx html

Alternatively, use officecli view target.docx outline for a text-based hierarchy check.

Internal Architecture of the Round-Trip Pipeline

The workflow relies on format-specific emitters and a unified batch execution engine.

Dump Phase Components:

• WordBatchEmitter: Walks the Word document DOM and emits batch items.
• PptxBatchEmitter: Handles PowerPoint-specific structures and slide elements.
• ExcelBatchEmitter: Processes worksheets, cells, and spreadsheet metadata.

Batch Phase Components:

• ApplyBatchItems: Orchestrates the replay execution sequence.
• ExecuteBatchItem: Dispatches individual commands to the appropriate handler.
• Format Handlers: Reconstruct document-specific objects (paragraphs, slides, ranges) from the JSON commands.

Resident Mode Integration:

When active, TryResident / ResidentServer proxies dump requests to an in-memory server instance, avoiding file-lock conflicts on the source document. The same resident logic applies during batch replay, ensuring consistency across live editing sessions.

Practical Example: Cloning a PowerPoint Presentation

This complete workflow demonstrates cloning a presentation from start to finish.

# 1. Dump the entire presentation structure

officecli dump deck.pptx / --format batch -o deck.dump.json

# 2. Create a blank target file

officecli create clone.pptx

# 3. Replay the batch to reconstruct the presentation

officecli batch clone.pptx --input deck.dump.json

# 4. Open live preview for verification

officecli watch clone.pptx

Note: This pattern applies identically to Word (.docx) and Excel (.xlsx) files; simply replace the file extension.

Summary

• The OfficeCLI dump and batch round-trip workflow converts documents into replayable JSON command sequences using CommandBuilder.Dump.cs.
• The dump command serializes document structure to BatchItem objects while emitting warnings to stderr, preventing JSON corruption.
• The batch command (implemented in CommandBuilder.Batch.cs) replays these items via ApplyBatchItems and ExecuteBatchItem.
• Format-specific emitters (WordBatchEmitter, PptxBatchEmitter, ExcelBatchEmitter) handle DOM traversal for each Office application.
• Resident Server mode prevents file-lock conflicts during both dump and batch operations by proxying requests through ResidentServer.
• The cloned document recreates the same structure and styling as the original, provided that required resources (fonts, themes, styles) are available in the target environment.

Frequently Asked Questions

What file formats does the OfficeCLI dump and batch workflow support?

The workflow supports Word (.docx), PowerPoint (.pptx), and Excel (.xlsx) documents. Each format uses dedicated emitters—WordBatchEmitter, PptxBatchEmitter, and ExcelBatchEmitter—to handle format-specific DOM structures while producing standardized BatchItem sequences that the batch executor can process.

How does the batch command handle errors during replay?

By default, the batch command runs in continue-on-error mode, logging failures but proceeding with subsequent items. Add the --stop-on-error flag to abort execution immediately when any BatchItem fails to apply, which is useful for debugging structural issues in the dump file or ensuring atomic cloning operations.

Can I use the dump and batch workflow to migrate content between different Office applications?

No, the batch JSON generated by dump is format-specific. While the BatchItem command structure is consistent across the CLI, you cannot replay a Word dump onto a PowerPoint file because the underlying commands reference application-specific elements (e.g., paragraphs vs. slides). The target document must match the source format exactly.

What is the Resident Server mode and when should I use it?

Resident Server mode, implemented via TryResident and ResidentServer, maintains a persistent process that holds documents in memory. Use this when performing rapid sequential operations on the same file to avoid file-lock conflicts and reduce IO overhead. The resident server proxies both dump requests and batch replay operations for consistency across live CLI sessions.

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