How to Use Batch Mode for Atomic Multi‑Command Execution in OfficeCLI

OfficeCLI's batch mode executes multiple document commands atomically, rolling back all changes if any single operation fails.

Batch mode in OfficeCLI provides a robust mechanism for applying complex, multi-step transformations to Word, PowerPoint, and Excel documents. This feature leverages transaction-style execution to ensure document integrity when running automated workflows or CI/CD pipelines. The implementation centers on the ApplyBatchItems and RunNonResidentBatch methods in src/officecli/CommandBuilder.Batch.cs, with data structures defined in src/officecli/BatchTypes.cs.

Understanding Batch Mode Architecture

Core Data Structures

The batch system operates on a JSON array of BatchItem objects. Each item specifies:

• Command: The operation verb (e.g., set, replace, delete)
• Path: The document location to modify
• Props or Args: Operation-specific parameters

In src/officecli/BatchTypes.cs, the BatchItem class defines the contract for deserialization. The engine distinguishes between read-only verbs and modifying operations through the ReadOnlyBatchVerbs collection. This distinction directly controls atomicity behavior.

Atomicity Logic

The batch engine determines atomic execution through this conditional check:

atomic = !bestEffort && containsNonReadOnlyCommand

When atomic mode is active (the default for modifying operations):

1. The engine prepares a transaction-style rollback checkpoint
2. Each command executes via ExecuteBatchItem
3. Successes append to a BatchResult list
4. Failures trigger exception capture through OfficeCli.Core.OutputFormatter.InferErrorCode
5. On any failure, the document state restores using the rollback mechanism

Command-Line Flags for Batch Control

OfficeCLI exposes precise control over batch behavior through these flags:

Flag	Effect
--json	Output results as structured JSON for programmatic parsing
--best-effort	Disable atomicity; continue execution and preserve partial changes
--stop-on-error	Halt immediately on first failure without rollback
--commands <json>	Supply batch JSON inline, bypassing stdin/file input
--input <file>	Read batch JSON from a file (commonly generated via officecli dump)

These options are documented in the README.md batch mode section.

Practical Batch Mode Examples

Creating Reproducible Batch Definitions

First, extract a document's structure as a replayable batch template:

officecli dump template.docx --output blueprint.json

This generates a JSON file suitable for modification and reuse across multiple documents.

Standard Atomic Execution

Run a batch with full rollback protection—the default behavior:

officecli batch target.docx --input blueprint.json --json

If any command in blueprint.json fails, the document reverts to its pre-batch state. The JSON output includes a rolledBack boolean flag indicating whether recovery occurred.

Best-Effort Non-Atomic Execution

Accept partial success when complete atomicity isn't required:

officecli batch target.docx --input updates.json --best-effort --json

This mode processes all items regardless of individual failures. Use this for reporting or diagnostic workflows where partial progress has value.

Debugging with Stop-on-Error

Isolate the first failing command without triggering rollback:

officecli batch target.docx --input updates.json --stop-on-error --json

This flag is particularly useful during batch development to identify specific command syntax or path errors.

Inline Batch Execution

Execute commands directly without intermediate files:

officecli batch target.pptx \
  --commands '[{"op":"set","path":"/slide[1]/shape[1]","props":{"text":"Hello"}}]' \
  --json

The --commands flag accepts a JSON array string, enabling dynamic batch construction in shell scripts or automation tools.

Key Implementation Files

File	Purpose
[src/officecli/CommandBuilder.Batch.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Batch.cs)	Core batch parsing, execution loop, atomicity logic, and result formatting
[src/officecli/BatchTypes.cs](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/BatchTypes.cs)	BatchItem definitions, JSON converters, and read-only verb classification
[README.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md)	User-facing documentation and workflow examples
[npm/README.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/README.md)	JavaScript wrapper installation and API notes

Summary

• Atomic multi-command execution is the default behavior in OfficeCLI batch mode, protecting document integrity through automatic rollback
• The atomicity decision depends on the presence of non-read-only commands and the absence of the --best-effort flag
• Batch items are deserialized from JSON into BatchItem objects and executed through ExecuteBatchItem with comprehensive result tracking
• Four execution modes address different operational needs: atomic (default), best-effort, stop-on-error, and inline commands
• The officecli dump command creates reproducible batch templates for version-controlled document automation

Frequently Asked Questions

How does OfficeCLI batch mode guarantee atomic execution?

According to the OfficeCLI source code, batch atomicity is enforced through a transaction-style checkpoint system in ApplyBatchItems. When atomic=true, the engine prepares rollback state before executing any command. If ExecuteBatchItem throws an exception for any BatchItem, the entire document restores to its pre-batch condition and the rolledBack flag appears in JSON output.

What happens when I use both --best-effort and --stop-on-error together?

These flags are mutually exclusive in practice. --best-effort explicitly disables atomicity and continues processing all items, while --stop-on-error halts immediately without rollback. If combined, --best-effort takes precedence for atomicity control, but execution will still stop at the first error due to the stop-on-error trigger. The source code in CommandBuilder.Batch.cs evaluates these flags independently in the execution loop.

Can I mix read-only and modifying commands in a single batch?

Yes. The batch engine inspects all Command values in src/officecli/BatchTypes.cs against ReadOnlyBatchVerbs. If any command is non-read-only and --best-effort is absent, the entire batch runs atomically. Read-only results simply don't trigger rollback preparation on failure.

Where should I store batch JSON for CI/CD pipelines?

Store batch definitions as version-controlled files and reference them via --input. This approach supports code review, change tracking, and environment-specific variants. For dynamically generated batches, use --commands with properly escaped JSON strings. The officecli dump command provides a reliable starting point for creating these definitions from existing documents.

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