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

> Learn to use the OfficeCLI merge command to inject JSON data into Word, Excel, and PowerPoint templates. Streamline document generation with a unified syntax.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-08-07

---

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

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Import.cs) and executed by the `TemplateMerger` class in [`src/officecli/Core/TemplateMerger.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```json
{
  "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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:**

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

```

**Merge an Excel workbook with inline JSON and force overwrite:**

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

```

**Merge a PowerPoint deck with machine-readable output:**

```bash
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:**

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

```

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Import.cs) and [`TemplateMerger.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.