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

> Master OfficeCLI batch mode for atomic multi-command execution. Roll back all changes if any operation fails, ensuring data integrity with iOfficeAI OfficeCLI.

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

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Batch.cs), with data structures defined in [`src/officecli/BatchTypes.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```csharp
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](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md#batch-mode---multi-command-execution-atomic-by-default-any-failed-item-rolls-back-the-whole-batch) batch mode section.

## Practical Batch Mode Examples

### Creating Reproducible Batch Definitions

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

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

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

```

If any command in [`blueprint.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

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

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

```bash
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)](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)](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)](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)](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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.