How to Use the OfficeCLI Merge Command Across Word, Excel, and PowerPoint

The merge command in OfficeCLI injects JSON data into Word, Excel, and PowerPoint templates by replacing {{key}} placeholders in the Open XML structure, producing a merged output file with a single unified syntax.

The OfficeCLI tool from the iOfficeAI/OfficeCLI repository provides a document generation engine that unifies templating across Microsoft's core Office formats. Unlike format-specific solutions, this command uses a consistent JSON-driven approach to populate documents, spreadsheets, and presentations without requiring the Office applications to be installed. Understanding how the merge pipeline handles Open XML internals allows you to build robust automation workflows for all three formats.

Command Syntax and Prerequisites

The merge command uses identical syntax regardless of whether the target is a Word document, Excel workbook, or PowerPoint deck:

officecli merge <template> <output> --data <json|jsonFile> [--force] [--json]

• <template>: Path to the source .docx, .xlsx, or .pptx file containing {{key}} placeholders.
• <output>: Destination path where the merged file is written.
• --data: Either an inline JSON string or a file path to a .json file containing key-value pairs.
• --force: Overwrites the output file if it already exists.
• --json: Outputs a machine-readable JSON summary instead of human-readable text.

How the Merge Command Works Internally

When you execute the command, the CLI orchestrates a five-stage pipeline defined in src/officecli/CommandBuilder.Import.cs and executed by the TemplateMerger class in src/officecli/Core/TemplateMerger.cs:

1. Template validation: The CLI verifies the file extension is one of the three supported Open XML formats.
2. Resident-client sync: If a resident process holds the template open, the CLI invokes ResidentClient.SendSave to flush in-memory edits before processing.
3. JSON parsing: The Core.TemplateMerger.ParseMergeData method parses the --data argument, accepting either inline JSON or a file path.
4. Placeholder substitution: Core.TemplateMerger.Merge traverses the document's XML tree, replaces every {{key}} occurrence with the corresponding JSON value, and tracks resolved versus unresolved keys.
5. Result reporting: By default, the CLI prints a summary showing the output path and replacement statistics. With --json, it emits a structured payload containing the output path, replacement count, and list of unresolved placeholders.

Format-Specific Behaviors

While the command signature remains constant, each Office format implements specialized handlers for its unique document structure.

Word Documents (.docx)

In src/officecli/Handlers/Word/WordHandler.cs, the merger walks the Word Open XML tree to replace placeholders inside paragraphs, tables, headers, footers, and content controls. The engine supports RTL (right-to-left) layout inference automatically based on content, though slide-specific properties (irrelevant to Word) remain unaffected.

Excel Workbooks (.xlsx)

The src/officecli/Handlers/Excel/ExcelHandler.cs file handles substitution within cell values and named ranges. Excel supports a special merge property in your JSON data that instructs the engine to merge cells after substitution:

{
  "title": "Q3 Forecast",
  "merge": "A1:C1"
}

This merges cells A1 through C1 after the placeholder replacement completes.

PowerPoint Presentations (.pptx)

Implemented in src/officecli/Handlers/Pptx/PowerPointHandler.cs, the PowerPoint merger replaces placeholders in slide notes, shapes, tables, and vector drawing properties. It specifically handles hmerge and vmerge flags for table cell merging and supports shape types such as FlowChartMerge.

Practical Examples

Merge a Word document using a JSON file:

officecli merge templates/report.docx merged/report.docx \
    --data data/report-data.json

Merge an Excel workbook with inline JSON and force overwrite:

officecli merge templates/budget.xlsx merged/budget.xlsx \
    --data '{ "Q1": 12000, "Q2": 15000 }' --force

Merge a PowerPoint deck with machine-readable output:

officecli merge templates/pitch.pptx merged/pitch.pptx \
    --data '{"company":"Acme Corp","date":"2026-09-01"}' --json

Merge an Excel file with cell range merging:

{
  "title": "Q3 Forecast",
  "merge": "A1:C1"
}

officecli merge templates/forecast.xlsx merged/forecast.xlsx \
    --data data/forecast.json

Summary

• The OfficeCLI merge command uses a single syntax to process .docx, .xlsx, and .pptx files by replacing {{key}} placeholders with JSON values.
• The merge pipeline in CommandBuilder.Import.cs and TemplateMerger.cs handles validation, resident-client synchronization, XML traversal, and reporting.
• Word supports paragraphs, tables, and content controls; Excel supports cell values and range merging via the merge property; PowerPoint supports slides, shapes, and table cell merging via hmerge/vmerge flags.
• Use --data for JSON input, --force to overwrite existing files, and --json to receive machine-readable output suitable for CI/CD pipelines.

Frequently Asked Questions

What file formats does the OfficeCLI merge command support?

The merge command supports the three core Office Open XML formats: Word (.docx), Excel (.xlsx), and PowerPoint (.pptx). The CLI validates file extensions before processing and rejects unsupported formats early in the pipeline.

How does the merge command handle JSON data input?

The command accepts JSON via the --data parameter, which Core.TemplateMerger.ParseMergeData processes. You can pass an inline JSON string enclosed in single quotes or provide a path to a .json file. The parser converts this into a dictionary that the XML traversal engine uses for placeholder substitution.

Can I merge cells in Excel using the merge command?

Yes. While the command replaces text placeholders in cell values, you can also trigger cell merging by including a merge key in your JSON data with a range value like "A1:C1". The ExcelHandler.cs implementation processes this property after substitution to merge the specified cell range.

What happens if a placeholder in my template doesn't exist in the JSON data?

The TemplateMerger tracks which placeholders remain unresolved during the XML traversal. If keys are missing from your JSON, the original {{key}} text remains in the document, and the final report (or JSON output when using --json) lists these unresolved placeholders so you can identify data gaps.

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