OfficeCLI Template Merge with {{key}} Placeholders: A Complete Guide to Batch Document Generation

OfficeCLI's merge command replaces {{key}} placeholders in Word, Excel, or PowerPoint templates with JSON values, enabling deterministic batch document generation without regenerating the template file.

The iOfficeAI/OfficeCLI repository provides a command-line interface for automating Microsoft Office document workflows. Using OfficeCLI template merge with {{key}} placeholders, you can design a document once and populate it thousands of times with data-driven values. This approach eliminates repetitive formatting work while maintaining visual consistency across all generated outputs.

How Template Merge Works Under the Hood

The merge functionality is implemented through a pipeline of specialized handlers that parse Office documents as traversable models. In src/officecli/CommandBuilder.Import.cs at line 288, the merge sub-command is registered with the explicit purpose: “Merge template with JSON data, replacing {{key}} placeholders”.

When you execute a merge, the engine performs three critical operations:

1. Template Parsing: The appropriate handler (Word, Excel, or PowerPoint) loads the file and builds an in-memory model of document elements including runs, cells, shapes, and text nodes.

2. Placeholder Detection: The engine scans all text nodes for the regular expression \{\{.*?\}\}. This pattern matches any {{key}} token regardless of location—body text, table cells, slide shapes, chart titles, or headers/footers.

3. JSON-Driven Substitution: The JSON payload supplied via --data is parsed into a dictionary. For each detected placeholder, the string inside the braces (key) is looked up and the corresponding value is injected into the node while preserving original formatting properties.

The deep-merge logic that handles nested JSON structures is implemented in src/officecli/Help/SchemaHelpLoader.cs at lines 282-287. Because the template file is never modified during this process, the merge step is purely deterministic and computationally cheap, making it ideal for high-volume batch operations.

Creating Your First Template with Placeholders

Before merging data, you need a template containing literal {{key}} tokens. You can create this using OfficeCLI's set command or by manually editing an existing document.

# Initialize a fresh Word document

officecli new invoice-template.docx

# Add a heading with a client placeholder

officecli set invoice-template.docx '/body/p[1]' \
    --prop text="Invoice for {{client}}" \
    --prop style=Heading1

# Add a paragraph with a total amount placeholder

officecli set invoice-template.docx '/body/p[2]' \
    --prop text="Amount due: {{total}}"

These operations are handled by the generic Word handler, specifically src/officecli/Handlers/Word/WordHandler.Set.cs. The resulting invoice-template.docx now contains literal strings {{client}} and {{total}} that will trigger substitution during the merge phase.

Merging JSON Data into Templates

For single-document generation, pass a JSON object directly to the --data flag:

officecli merge invoice-template.docx \
    invoice-001.docx \
    --data '{"client":"Acme Corp","total":"$5,200"}'

The command walks the document model using the handlers defined in src/officecli/Handlers/WordHandler.cs (and equivalent files for Excel and PowerPoint), replacing every instance of {{client}} with "Acme Corp" and {{total}} with "$5,200". The output file invoice-001.docx contains the substituted text with all original formatting intact.

Batch Document Generation Workflows

The true power of OfficeCLI template merge emerges when processing multiple records. Because the template remains static on disk, you can invoke the merge command thousands of times without performance degradation.

Assume you have a data.json file containing an array of objects:

[
  {"client": "Acme Corp", "total": "$5,200"},
  {"client": "Beta Industries", "total": "$3,450"},
  {"client": "Gamma LLC", "total": "$8,900"}
]

Use the following bash script to generate numbered invoices:

#!/usr/bin/env bash
set -euo pipefail

TEMPLATE=invoice-template.docx
DATA=data.json

# Iterate over the array with jq

jq -c '.[]' "$DATA" | nl -w1 -s',' | while IFS=',' read -r idx payload; do
    OUT=invoice-$(printf "%03d" "$idx").docx
    officecli merge "$TEMPLATE" "$OUT" --data "$payload"
    echo "Created $OUT"
done

This pipeline uses jq -c '.[]' to emit each object as a compact JSON string, then calls officecli merge for every record. Since the template file is never regenerated, this pattern scales linearly and consumes no additional tokens per iteration.

Scaling to Massive Fleets with Dump and Batch

For generating thousands of documents in a single command, use the dump and batch pipeline:

# Extract the template structure to JSON

officecli dump invoice-template.docx --output template.json

# Batch-process the entire dataset

officecli batch template.json data.json --output-dir invoices/

As documented in the README at line 297, this approach pre-computes the document structure (including placeholder locations) and replays it against your entire dataset, optimizing I/O for massive fleet generation.

Summary

• Design once, generate infinitely: OfficeCLI template merge uses static template files and JSON data to produce unlimited document variations.
• Universal placeholder syntax: The {{key}} pattern works across Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) formats in any text-containing element.
• Deterministic performance: Merges are computationally cheap because the template file is never regenerated, making batch operations cost-effective.
• Data validation: The engine supports nested JSON objects through the deep-merge logic in src/officecli/Help/SchemaHelpLoader.cs.
• Quality assurance: Use the query command to scan for stray {{ tokens and ensure no placeholders leak into final outputs.

Frequently Asked Questions

What Office document formats support OfficeCLI template merge?

OfficeCLI supports {{key}} placeholder replacement in Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files. Each format uses a dedicated handler—WordHandler.cs, ExcelHandler, and PowerPointHandler respectively—to traverse document-specific structures like runs, cells, and shapes while preserving formatting.

Can I use nested JSON objects with template placeholders?

Yes. The deep-merge logic implemented in src/officecli/Help/SchemaHelpLoader.cs (lines 282-287) correctly handles nested JSON structures. You can reference nested values using appropriate key names in your placeholders, and the engine will traverse the JSON object to retrieve the corresponding values.

How do I verify that all placeholders were replaced correctly?

After merging, run the officecli query command to scan the output document for stray {{ tokens. As noted in the README at line 420, this validation step ensures no placeholder leaks into your final document, catching typos in your JSON keys or template tokens before distribution.

Is there a performance limit for batch document generation?

No practical limit exists for batch operations. Because the template file is never regenerated during the merge process, the operation remains deterministic and cheap regardless of volume. You can call officecli merge thousands of times in a loop or use the batch command for single-step massive fleet generation without additional token usage or memory overhead.

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