OfficeCLI Resident Mode vs Batch Mode: When to Use Each

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 (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 (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:

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

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 (line 326), omitting --best-effort ensures that any failure triggers the rollback mechanism in 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, 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 (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 (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 (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.

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