# OfficeCLI Resident Mode vs Batch Mode: When to Use Each

> Choose OfficeCLI resident mode for continuous editing or batch mode for automated CI/CD tasks. Learn when to use each mode for optimal efficiency and workflow.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: best-practices
- Published: 2026-07-31

---

**Use OfficeCLI resident mode for long-running editing sessions with multiple operations on the same file to eliminate repeated open/save overhead, and batch mode for atomic, one-shot command sequences ideal for CI/CD pipelines.**

OfficeCLI, the open-source document automation tool from iOfficeAI, provides two distinct execution strategies for manipulating Word, Excel, and PowerPoint files. Understanding when to use **OfficeCLI resident mode versus batch mode** is critical for optimizing performance, ensuring data integrity, and building robust document processing pipelines.

## Understanding OfficeCLI Resident Mode

Resident mode launches a long-lived background process that keeps your document open in memory, accepting multiple commands via a persistent pipe. According to the source code in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) (lines 55-73), the resident server maintains a document handle and implements an idle timeout mechanism that automatically flushes changes after 2-10 seconds of inactivity or upon explicit `save` and `close` commands.

### Key Benefits of Resident Mode

- **Performance**: Eliminates the cost of repeatedly opening and saving files, making it ideal for scenarios requiring three or more operations on the same document.
- **Statefulness**: The document remains editable in RAM, allowing subsequent commands to build upon previous modifications without disk I/O bottlenecks.
- **Auto-flush**: Changes persist automatically after a brief idle period, though explicit `save` commands ensure durability before handing files to external programs.

### When to Use Resident Mode

Choose resident mode when:

- You need to run **many mutations on the same file** (typically five or more operations).
- You require the fastest possible round-trip times because the document stays resident in memory.
- You are building an interactive pipeline where later steps read the file from disk (flush the resident with `save` or `close` before external access).

## Understanding OfficeCLI Batch Mode

Batch mode processes a JSON array of commands atomically in a single invocation. As implemented in [`src/officecli/CommandBuilder.Batch.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Batch.cs) (line 76), batch commands can run in a non-resident process or automatically route through an existing resident if one is detected. The implementation uses `DeferSave` to avoid N serializations and includes rollback logic (lines 1310-1350) that can restore the original file if any operation fails.

### Key Benefits of Batch Mode

- **Atomicity**: Execute multiple operations as a single transaction; if one command fails, the entire batch can roll back (unless `--best-effort` is specified).
- **Simplicity**: Ideal for one-off invocations where managing a resident lifecycle is unnecessary.
- **CI/CD Friendly**: Perfect for automated pipelines where you need a single command exit code and deterministic file states.

### When to Use Batch Mode

Opt for batch mode when:

- You have a **self-contained list of operations** that can be described upfront, such as a JSON script generated by another program.
- You need **transactional guarantees** where the entire operation set must succeed or leave the file untouched.
- You prefer single-command invocations from shell scripts or CI/CD configurations rather than managing process lifecycles.

## Comparing OfficeCLI Resident Mode vs Batch Mode

| Feature | Resident Mode | Batch Mode |
|---------|--------------|------------|
| **Process Lifecycle** | Long-lived server (`open` to `close`) | Single execution, immediate exit |
| **Memory Model** | Document held in RAM | Document loaded per batch (unless routing through resident) |
| **Performance** | Fastest for sequential edits | Overhead of process spawn per invocation |
| **Atomicity** | Manual (commands are independent) | Built-in rollback support (`--best-effort` toggle) |
| **Best For** | Interactive sessions, many edits | CI/CD, one-shot operations, guaranteed consistency |

## Practical Implementation Examples

### Long-Running Document Generation (Resident Mode)

For generating complex Word reports with dozens of populated fields, start a resident session to avoid repeated disk I/O:

```bash
officecli open report.docx
officecli set report.docx /body/p[1] --prop bold=true
officecli add report.docx /body/p[2] --type paragraph --prop text="Executive Summary"
officecli set report.docx /body/tbl[1]/tr[2]/td[1] --prop text="Q4 Results"
officecli save report.docx  # Flush to disk while keeping resident warm

officecli close report.docx  # Final flush and shutdown

```

The [`ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentClient.cs) file (lines 119-176) provides the underlying `AskFlush` and `AskClose` helpers that manage this communication through the resident pipe.

### Atomic CI/CD Updates (Batch Mode)

For automated template updates where failure must not corrupt the original file, use batch mode with JSON:

```bash
cat <<EOF > operations.json
[
  {"command":"set","path":"template.docx","args":["/body/p[1]","--prop","bold=true"]},
  {"command":"add","path":"template.docx","args":["/body/p[2]","--type","paragraph","--prop","text=Generated Report"]},
  {"command":"save","path":"template.docx"}
]
EOF
officecli batch --json operations.json

```

According to [`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) (line 326), omitting `--best-effort` ensures that any failure triggers the rollback mechanism in [`CommandBuilder.Batch.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Batch.cs), leaving the original file pristine.

### Hybrid Workflows

If a resident process is already running when you invoke a batch command, OfficeCLI automatically detects it and routes the batch through the existing pipe (as noted in [`CommandBuilder.Batch.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Batch.cs), line 76). This hybrid approach gives you the **speed of resident mode with the atomic semantics of batch mode**, though the resident retains control of the document state after completion.

## Summary

- **Resident mode** eliminates file open/save overhead by keeping documents in memory, making it ideal for interactive sessions with multiple sequential operations.
- **Batch mode** provides atomic, one-shot execution with built-in rollback capabilities, perfect for CI/CD pipelines and guaranteed consistency.
- Both modes can interoperate: batch commands automatically route through active residents when available, combining performance with transactional safety.
- Use explicit `save` or `close` commands in resident mode before external programs access the file, as detailed in the README (lines 308-337).

## Frequently Asked Questions

### Can I use batch mode if a resident process is already running?

Yes. According to [`src/officecli/CommandBuilder.Batch.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Batch.cs) (line 76), OfficeCLI detects running residents and routes batch commands through the existing pipe rather than spawning a new process. This gives you the atomic guarantees of batch mode while maintaining the in-memory performance benefits of the resident server.

### What happens if a batch operation fails halfway through?

By default, OfficeCLI attempts to roll back the entire operation. The atomic rollback logic in [`CommandBuilder.Batch.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Batch.cs) (lines 1310-1350) restores the original file state if any command in the JSON array fails. You can disable this behavior with the `--best-effort` flag, which commits successful commands up to the failure point while skipping the failed operation.

### How long does a resident process stay alive?

The resident server implements an idle timeout of 2-10 seconds, as documented in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) (lines 55-73). If no commands arrive within this window, the process automatically flushes pending changes to disk and shuts down. You can also manually trigger a flush with `officecli save` or terminate the resident with `officecli close`.

### Is resident mode faster than batch mode for single operations?

No. For single, isolated operations, batch mode is typically faster because it avoids the overhead of establishing a resident server and managing persistent pipes. Resident mode provides measurable performance benefits only when executing three or more sequential operations on the same document, where the cost of repeated file opening and serialization is amortized across the session.