Office-stamper CLI

The Command Line Interface (CLI) for Office-stamper lets you stamp DOCX or PPTX templates from the terminal. It wraps the Engine module so you can generate documents without writing Java code.

Quick start

Build the CLI fat JAR:

mvn -q -pl :cli -am -DskipTests package

Run it:

java -jar cli/target/cli-<VERSION>-jar-with-dependencies.jar --help

Replace <VERSION> with the built version. Use --help to discover available commands and options.

New to Office‑stamper on Windows? See the dedicated Quickstart (Windows) for a 5‑minute walkthrough, including installer/portable options, --dry-run, JSON logs, and directory multi‑stamp.

Synopsis

officestamper \
  -t|--template <template.docx|template.pptx|diagnostic> \
  [-d|--data <file|dir|diagnostic>] \
  [-o|--output <output.docx|outputDir>] \
  [--dry-run] \
  [--report <report.json>] \
  [--log-format <human|json>]

The previous --stamper flag has been removed. Template type is auto‑detected by file extension.

Flags

  • -t, --template:: Template path. Supported: .docx, .pptx, or diagnostic (built‑in sample template).
  • -d, --data:: Data input. One of:
    • File: json, yaml, yml, properties, csv, xlsx, xml, html
    • Directory: special multi‑stamp behavior (see below)
    • Keyword: diagnostic (built‑in sample context)
  • -o, --output (default: output.docx):: Output target. Can be a file path or a directory.
  • --dry-run:: Validate template + data and variables without producing an output file. Fails on unresolved placeholders.
  • --report:: Optional JSON report file path. Contains run metadata and validation outcome.
  • --log-format (default: human):: Logging format: human for standard console logs, or json for structured logs printed to stdout.

Behavior

Template auto‑detection

  • .docx → Word stamper
  • .pptx → PowerPoint stamper
  • diagnostic → uses an internally packaged DOCX demo template and generated context

Directory data mode (multi‑stamp)

When --data points to a directory:

  • For each top‑level file in the directory (with a supported extension), the CLI creates an individual context and stamps one output document.
  • For each immediate subfolder, all supported files inside that subfolder (recursively) are merged into a bigger context object, and one output document is stamped for that subfolder.

Output naming rules when multiple documents are produced:

  • If -o|--output is an existing directory, outputs are written inside it as <itemName>.docx|.pptx.
  • If -o|--output is a single file path like report.docx, outputs are written next to it as report-<itemName>.docx|.pptx.
  • If -o|--output is a non‑existing path without an extension, it is treated as a directory and created as needed; outputs go inside it as <itemName>.ext.

Dry‑run validation

  • Uses a strict resolver that throws on unresolved placeholders.
  • No output file is written.
  • Exit codes follow POSIX conventions (0 on success; non‑zero on failure).

Structured JSON logging

When --log-format=json is set, the CLI prints structured lines to stdout with the minimal schema:

{ "ts": "2026-04-23T00:00:00Z", "level": "info", "msg": "Start", "fields": { "template": "invoice.docx", "dryRun": false } }

Other library logs are kept to a minimum and remain in human format.

Report file format

When --report <file.json> is provided, the CLI writes a JSON file similar to:

{
  "status": "ok|error",
  "template": "<template>",
  "data": "<data or <none>>",
  "output": "<output path>",
  "dryRun": true,
  "timestamp": "<RFC 3339>",
  "error": "<message if any>"
}

Windows builds

EXE installer (bundled runtime)

Build a native Windows EXE installer that bundles a Java runtime:

mvn -pl :cli -am -P windows-exe -DskipTests package

Artifact: cli/target/installer/officestamper-<VERSION>.exe

Portable single-file EXE (no installer)

Build a standalone EXE that self‑extracts to a temp directory and runs immediately:

Prerequisites:

  • JDK with jpackage (14+)
  • 7‑Zip installed and available on PATH (7z.exe)
mvn -pl :cli -am -P windows-portable -DskipTests package

Artifact: cli/target/portable/officestamper-portable-<VERSION>.exe

Experimental: the Windows portable single‑file EXE is provided for convenience and is considered experimental.

  • It is implemented as a 7‑Zip self‑extracting archive that unpacks to a temporary directory on launch.
  • First‑run startup can be slower and may trigger Antivirus/SmartScreen warnings.
  • The binary is not code‑signed; Windows may show an "Unknown publisher" prompt.
  • No PATH integration, file associations, or auto‑update.
  • Packaging details and behavior may change between releases.

For stable deployments, prefer the EXE installer profile. Please report issues you encounter.

Notes:

  • The portable EXE is built as a 7‑Zip SFX that launches officestamper.exe after extraction.
  • Temporary files are cleaned automatically when the process exits.

Windows packaging (EXE installer with bundled runtime)

Build a native Windows EXE installer that bundles a trimmed Java runtime. The installed app runs on machines without Java preinstalled and provides a console launcher officestamper.exe.

mvn -pl :cli -am -P windows-exe -DskipTests package

Artifact is generated at:

  • cli/target/installer/officestamper-<VERSION>.exe — Windows installer (self‑contained)

Notes:

  • Requires a JDK with jpackage (JDK 14+; tested with JDK 25). WiX is NOT required for the EXE type.
  • The embedded application version is normalized (e.g., 3.4.0) for jpackage compatibility.
  • Re-running the build cleans the previous output automatically.

When --data is a directory, the report aggregates results and includes an items array:

{
  "status": "ok|error",
  "template": "<template>",
  "data": "<data dir>",
  "dryRun": false,
  "timestamp": "<RFC 3339>",
  "items": [
    { "name": "a", "status": "ok", "output": "out/a.docx" },
    { "name": "sales-q1", "status": "error", "error": "<message>" }
  ]
}

YAML support

YAML input requires the jackson-dataformat-yaml dependency on the classpath. If missing, the CLI clearly reports the requirement.

Examples

Stamp a DOCX template with JSON data:

java -jar cli/target/cli-<VERSION>-jar-with-dependencies.jar \
  -t invoice.docx \
  -d data.json \
  -o invoice-out.docx

Validate without writing output and emit structured logs:

java -jar cli/target/cli-<VERSION>-jar-with-dependencies.jar \
  --template invoice.docx \
  --data data.json \
  --dry-run \
  --log-format json

Stamp once per file and per subfolder when data is a directory:

java -jar cli/target/cli-<VERSION>-jar-with-dependencies.jar \
  -t report.docx \
  -d ./data-dir \
  -o ./out

Use the built‑in diagnostic template and context:

java -jar cli/target/cli-<VERSION>-jar-with-dependencies.jar \
  -t diagnostic \
  -d diagnostic \
  -o diag.docx

Native packaging (Windows)

You can build a native Windows app-image that includes a console launcher officestamper.exe and an embedded Java runtime.

Build command (from project root):

mvn -pl :cli -am -P windows-exe -DskipTests package

Artifacts:

  • cli/target/installer/officestamper/ — application image directory
  • cli/target/installer/officestamper/officestamper.exe — native Windows launcher

Notes:

  • Requires a JDK with jpackage available (Java 14+; tested with JDK 25).
  • No WiX is required since we build an app-image (not an MSI installer).
  • The image version is normalized to numeric form for jpackage compatibility.

Links