OfficeCLI Dump Batch Round-Trip Learning from Documents: AI-Driven Document Automation

OfficeCLI enables AI agents to learn document structure via dump, modify JSON blueprints, and replay changes atomically with batch—a complete round-trip workflow that never requires parsing raw OOXML.

The iOfficeAI/OfficeCLI repository provides a schema-driven, AI-native command line interface for Microsoft Office documents. Its dump-batch round-trip capability lets large language models inspect, learn from, and regenerate Word, Excel, and PowerPoint files through deterministic JSON intermediaries rather than fragile XML manipulation.

Three-Layer Architecture for AI-Friendly Operations

OfficeCLI organizes commands into three abstraction layers, keeping simple tasks accessible while preserving full control for complex automation.

Layer	Purpose	Primary Implementation
L1 – Read	Semantic views: view, outline, html, screenshot	[CommandBuilder.View.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.View.cs)
L2 – DOM	Structured CRUD: get, query, set, add, remove, move, swap	[CommandBuilder.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs)
L3 – Raw XML	Direct XPath fallback: raw, raw-set	[CommandBuilder.Raw.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Raw.cs)

The entry point in [Program.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs) constructs a single RootCommand using System.CommandLine, registering all subcommands for Word, Excel, and PowerPoint handlers.

Format	Handler	Key Responsibilities
Word	[WordHandler.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/WordHandler.cs)	Paragraph/run processing, styles, TOC, equations
Excel	[ExcelHandler.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/ExcelHandler.cs)	Cell storage, 350+ functions, pivot tables, charts
PowerPoint	[PowerPointHandler.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/PowerPointHandler.cs)	Slides, shapes, transitions, 3D models, animations

The core engine in OfficeCli.Core provides shared utilities: [Units.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Units.cs) parses flexible dimensions like 2cm or 720000 EMU, while [TemplateMerger.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/TemplateMerger.cs) handles placeholder replacement.

The Dump-Batch Round-Trip Workflow

OfficeCLI dump batch round-trip learning from documents follows a four-stage pattern: capture, edit, replay, validate. Each stage produces or consumes deterministic JSON that AI systems can generate and parse reliably.

Stage 1: Dump to JSON Blueprint

The officecli dump command serializes any document or subtree into a schema-stable JSON representation. This captures element tags, XPath-style paths, and all attributes without exposing raw OOXML complexity.

# Dump complete document

officecli dump report.docx -o report-blueprint.json

# Dump specific subtree (single slide)

officecli dump deck.pptx /slide[2] -o slide2.json

# Dump Excel sheet with formulas preserved

officecli dump sales.xlsx '/Sheet1' -o sheet-structure.json

The dump implementation traverses the OOXML DOM and emits the batch schema. Excel-specific logic resides in [ExcelHandler.DumpSupport.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Excel/ExcelHandler.DumpSupport.cs), with parallel implementations in WordHandler and PowerPointHandler.

Stage 2: Modify the JSON Blueprint

Edit the dumped JSON programmatically or feed it to an LLM for transformation. The structure is intentionally flat and path-addressable:

{
  "operations": [
    {
      "tag": "shape",
      "path": "/slide[2]/shape[1]",
      "attributes": {
        "text": "Quarterly Results – Revised",
        "font": "Arial",
        "size": 28,
        "color": "#2E75B6"
      }
    },
    {
      "tag": "cell",
      "path": "/Sheet1/r[5]/c[3]",
      "attributes": {
        "value": "=SUM(C2:C4)",
        "format": "0.00%"
      }
    }
  ]
}

Stage 3: Batch Replay

The officecli batch command applies the modified blueprint atomically (or with --best-effort for partial success). The batch engine defined in [CommandBuilder.Batch.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Batch.cs) validates each operation, rolls back on error, and executes DOM commands identical to interactive use.

# Create fresh document and replay modifications

officecli create refreshed-report.docx
officecli batch refreshed-report.docx --input report-blueprint.json

# In-place update with atomic guarantees

officecli batch sales.xlsx --input sheet-modified.json

# Best-effort mode: apply all valid operations, skip failures

officecli batch presentation.pptx --input deck-updated.json --best-effort

Stage 4: Validate and Preview

Verify structural integrity and inspect results visually:

# Schema validation against Office Open XML spec

officecli validate refreshed-report.docx

# Generate self-contained HTML preview

officecli view refreshed-report.docx html

# Live browser preview that updates on file change

officecli watch refreshed-report.docx  # Serves http://localhost:26315

The watch server implementation in [WatchServer.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Watch/WatchServer.cs) renders documents to HTML without Microsoft Office installed.

Practical Code Examples

Example 1: PowerPoint Title Update via Round-Trip

# 1. Capture original structure

officecli dump annual-deck.pptx -o deck-orig.json

# 2. Modify title (using jq for demonstration)

jq '(.operations[] | select(.path == "/slide[1]/shape[1]") | .attributes.text) = "FY2026 Strategic Plan"' \
  deck-orig.json > deck-modified.json

# 3. Replay to new file

officecli create fy2026-deck.pptx
officecli batch fy2026-deck.pptx --input deck-modified.json

# 4. Validate and preview

officecli validate fy2026-deck.pptx
officecli view fy2026-deck.pptx html

Example 2: Bulk Excel Formula Injection

# Dump source sheet

officecli dump sales-q3.xlsx '/Sheet1' -o q3-structure.json

# Inject growth calculation column via Python script

python3 << 'EOF'
import json
with open('q3-structure.json') as f:
    data = json.load(f)

# Add computed cells for rows 2-20

for row in range(2, 21):
    data['operations'].append({
        "tag": "cell",
        "path": f"/Sheet1/r[{row}]/c[5]",
        "attributes": {
            "value": f"=C{row}/D{row}-1",
            "format": "0.0%",
            "style": "Growth"
        }
    })

with open('q3-with-growth.json', 'w') as f:
    json.dump(data, f, indent=2)
EOF

# Atomic batch application

officecli batch sales-q3.xlsx --input q3-with-growth.json

Example 3: Resident Mode for Iterative Development

# Initialize resident mode (document stays in RAM)

officecli open proposal.docx

# Rapid successive edits with zero disk I/O

officecli set proposal.docx /body/p[1]/r[1] --prop bold=true
officecli set proposal.docx /body/p[2]/r[1] --prop color=FF0000
officecli add proposal.docx /body -t table --rows 3 --cols 4

# Live preview updates automatically

officecli watch proposal.docx &

# Finalize and persist

officecli close proposal.docx

The resident mode plumbing spans [ResidentServer.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) and [ResidentClient.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentClient.cs), implementing inter-process communication between the CLI and a background document host.

Core Implementation Files

File	Function	GitHub Link
CommandBuilder.Dump.cs	dump command registration and argument parsing	source
CommandBuilder.Batch.cs	Batch replay engine with transaction support	source
ExcelHandler.DumpSupport.cs	Excel-specific DOM traversal and JSON serialization	source
WordHandler.cs	Word document manipulation and dump generation	source
PowerPointHandler.cs	PowerPoint slide/shape dump and rebuild	source
Units.cs	Dimension parsing (cm, inches, EMU, points)	source
TemplateMerger.cs	Placeholder replacement for mail-merge scenarios	source
WatchServer.cs	HTTP server for live HTML preview	source

Summary

• Dump-batch round-trip transforms Office documents into editable JSON and back, eliminating direct OOXML manipulation
• Three-layer architecture (Read/DOM/Raw) provides appropriate abstraction for every automation scenario
• Atomic batch execution in CommandBuilder.Batch.cs guarantees consistency or clean rollback
• Resident mode eliminates I/O overhead for high-frequency editing sessions
• Live preview via watch enables visual verification without Microsoft Office installed
• All handlers implement identical dump schema, enabling cross-format learning and templating

Frequently Asked Questions

What makes OfficeCLI's dump format AI-friendly?

The dump format uses flat, path-addressed objects with consistent tag, path, and attributes fields across Word, Excel, and PowerPoint. Unlike raw OOXML's deeply nested XML, this structure lets language models predict and generate valid operations without specialized Office knowledge. The schema is version-stable and deterministic—dumping the same document twice produces identical JSON, enabling reliable diff-based workflows.

How does batch replay handle errors?

By default, officecli batch operates atomically: it validates all operations, acquires necessary locks, applies changes to an in-memory representation, and commits only on full success. If any operation fails, the entire batch rolls back with no disk changes. Use --best-effort to apply valid operations and report failures individually—useful when processing AI-generated batches where some operations may reference non-existent paths.

Can I use dump-batch for document templating?

Yes. The round-trip pattern supports exemplar-based templating: dump a well-designed document, replace content-bearing attributes with placeholders (e.g., {{company_name}}), store the result as a template, then programmatically substitute values and batch-replay to generate instances. Combine with TemplateMerger.cs for simpler mail-merge scenarios or full dump-batch for structural variations.

Does resident mode improve dump-batch performance?

Resident mode eliminates serialization overhead for iterative workflows. Without it, each command loads the document from disk, modifies, and saves—typical latency 200-500ms. With officecli open, the document stays in memory; dump, batch, and view commands execute in 10-50ms. This 10x acceleration matters when AI agents perform hundreds of exploratory operations or when running watch with continuous updates.

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