OfficeCLI Dump vs Batch Commands: Understanding Document Round-Tripping in iOfficeAI/OfficeCLI

OfficeCLI's dump command serializes documents into replayable JSON blueprints, while batch consumes those JSON files to recreate or modify documents—together enabling lossless document round-tripping.

Both commands serve complementary roles in the OfficeCLI round-trip pipeline, but they operate at opposite ends of the workflow. The dump command extracts a complete structured representation from any .docx, .pptx, or .xlsx file, including verbatim binary blobs and OLE objects. The batch command replays that JSON to rebuild the document exactly or apply bulk mutations atomically. Understanding this distinction is essential for automation workflows, AI agent integrations, and document template engineering.

What Is Document Round-Tripping in OfficeCLI?

Round-tripping refers to the ability to convert a binary Office document into an editable intermediate format and back again without data loss. In OfficeCLI, this intermediate format is a batch JSON structure that captures every element, property, and binary attachment in a machine-readable schema.

According to the iOfficeAI/OfficeCLI source code, both commands share the resident-server architecture (ResidentServer.cs), which maintains the OOXML document model in memory and routes operations consistently. This design ensures that dump extracts from the same in-memory representation that batch writes to, eliminating serialization mismatches.

The Dump Command: Extracting Document Blueprints

dump serializes a document (or any subtree) into a replayable JSON format. This output serves as a inspectable, editable, and storable template.

Key Capabilities

• Full or partial extraction: Dump an entire document or target specific subtrees (single tables, slides, worksheets)
• Verbatim binary preservation: OLE objects, images, and custom XML are embedded as base64 blobs
• Human-readable structure: Pure JSON replaces opaque OOXML for easier reasoning

Implementation Details

The command is implemented in src/officecli/CommandBuilder.Dump.cs, which validates the --format=batch flag and emits the structured representation.

# Dump entire document to JSON blueprint

officecli dump existing.docx -o blueprint.json

# Dump specific slide from presentation

officecli dump presentation.pptx --slide 3 -o slide3.json

The Batch Command: Replaying and Mutating Documents

batch consumes batch JSON and reconstructs the original document or applies a series of mutations in a single atomic pass.

Key Capabilities

• Lossless reconstruction: Replays dumps to produce byte-identical documents
• Atomic operation execution: Multiple commands execute as one transaction
• Incremental modifications: Additional operations can be appended to the JSON before replay

Implementation Details

The command is implemented in src/officecli/CommandBuilder.Batch.cs, which parses the JSON, validates each operation, and applies them with configurable error handling.

# Recreate document from JSON blueprint

officecli batch new.docx --input blueprint.json

# Apply edited JSON with mutations

officecli batch modified.docx --input edited.json

Critical Differences: Dump vs Batch

Aspect	dump	batch
Direction	Document → JSON	JSON → Document
Primary purpose	Extraction and inspection	Reconstruction and modification
Granularity	Selective subtree or full document	Atomic execution of multiple operations
Output	Replayable batch JSON	Rebuilt Office document
Fidelity guarantee	Captures verbatim binary data	Restores byte-identical output for supported formats
AI agent use case	Learn document structure from JSON	Reproduce or mutate templates programmatically

Practical Round-Trip Workflows

Workflow 1: Lossless Document Copy

Pipe dump directly into batch for perfect duplication without intermediate files:

officecli dump source.pptx --format batch | officecli batch copy.pptx --input -

Workflow 2: Agent-Assisted Template Modification

# 1. Extract blueprint

officecli dump template.docx -o blueprint.json

# 2. Agent inspects/modifies via jq or programmatic JSON editing

jq '.[] | select(.tag=="paragraph" and .attributes.style=="Heading1") | .attributes.text = "Updated Title"' blueprint.json > edited.json

# 3. Rebuild with modifications

officecli batch customized.docx --input edited.json

Workflow 3: Bulk Operations with Error Control

Both commands support --best-effort and --stop-on-error flags to control atomicity:

# Stop entire batch if any operation fails

officecli batch critical.docx --input operations.json --stop-on-error

# Continue partial execution, logging failures

officecli batch resilient.docx --input operations.json --best-effort

Resident Server Architecture

Both commands rely on ResidentServer.cs for consistent behavior. When a document opens in resident mode, the CLI maintains the OOXML in memory:

• dump extracts from this resident model
• batch writes directly to the resident model or a fresh document
• The server handles request routing and unified error handling

This shared plumbing ensures that a dump → batch sequence yields identical output for supported formats.

Summary

• dump extracts documents into editable JSON blueprints with full binary fidelity
• batch replays JSON to rebuild documents or execute atomic mutations
• Together they enable lossless round-tripping: dump learns structure, batch reproduces and modifies
• Implementation resides in CommandBuilder.Dump.cs and CommandBuilder.Batch.cs with shared ResidentServer.cs infrastructure
• AI workflows benefit from JSON's superior inspectability compared to raw OOXML

Frequently Asked Questions

Can dump and batch handle partial document extraction?

Yes. The dump command supports subtree targeting—specify slides, tables, or worksheet ranges instead of entire documents. The resulting JSON contains only the selected elements, and batch can replay these partial dumps into new documents or merge them into existing ones.

Do dump and batch preserve macros and embedded OLE objects?

Yes. The dump format includes verbatim binary blobs for OLE objects, images, and custom XML parts. When batch replays this JSON, these elements restore exactly. This preservation is critical for document templates containing embedded Excel charts or legacy ActiveX controls.

What error handling options exist for batch operations?

batch supports two mutually exclusive flags: --stop-on-error aborts the entire transaction on any failure, while --best-effort continues execution and logs errors. This atomicity control is essential for production automation where partial document corruption must be avoided.

How does the resident mode improve round-trip performance?

Resident mode keeps documents in memory between commands, eliminating repeated disk I/O and ZIP (OOXML) operations. Both dump and batch leverage this for sub-second operations on large documents, with ResidentServer.cs managing concurrent access and resource cleanup automatically.

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