How to Control Flushing in OfficeCLI Resident Mode: A Complete Guide

Set the OFFICECLI_RESIDENT_FLUSH environment variable to each, auto, <N>, or off before starting the resident server, or use officecli save and officecli close commands to manually trigger writes.

The iOfficeAI/OfficeCLI repository provides a resident mode that keeps documents open in memory via a long-running server process (ResidentServer). When running in this mode, changes accumulate in memory until a flush operation writes them to disk. Understanding how to control flushing in OfficeCLI resident mode is essential for balancing data safety, performance, and visibility to external applications.

Understanding the Resident Flush Policy

The resident server reads the OFFICECLI_RESIDENT_FLUSH environment variable (or the legacy OFFICECLI_RESIDENT_IDLE_SAVE_SECONDS) at startup to determine persistence behavior. As implemented in src/officecli/ResidentServer.cs (lines 111-123), the selected policy is stored in ResidentServer.FlushMode and ResidentServer.FixedFlushInterval (lines 128-130).

The system supports four distinct flushing strategies:

• each – Flushes the in-memory DOM after every mutation command. This provides deterministic persistence and ensures external readers see changes immediately, though it increases disk I/O.
• auto (default) – Uses idle-debounced flushing after the document has been idle for an adaptive interval clamped between 2 seconds and 10 seconds (lines 116-120). The interval adjusts based on measured save cost, optimizing for interactive sessions.
• <N> – Flushes every N seconds using a fixed interval. The numeric value is parsed from the environment variable, providing predictable periodic writes regardless of save speed.
• off – Disables automatic flushes entirely. The document persists only when you issue an explicit save or close command.

Configuring the Flush Environment Variable

Control the flushing behavior by exporting the variable before invoking officecli:

export OFFICECLI_RESIDENT_FLUSH=each
officecli open document.docx

For a fixed 5-second flush interval:

export OFFICECLI_RESIDENT_FLUSH=5
officecli open document.docx

To disable automatic flushing for batch operations:

export OFFICECLI_RESIDENT_FLUSH=off
officecli open document.docx

Manual Flush Commands

Regardless of the automatic policy, you can force persistence at any time using manual commands.

Using officecli save

The officecli save <file> command writes in-memory changes to disk while keeping the resident process alive. According to src/officecli/CommandBuilder.Save.cs, this command triggers ExecuteSave() and is a no-op when no resident is active. Use this when you need external tools to see current state without terminating the session.

officecli save document.docx

Using officecli close

The officecli close <file> command flushes pending changes and immediately terminates the resident server, releasing the file lock. As shown in src/officecli/CommandBuilder.cs (lines 71-73), this performs a final save before shutdown.

officecli close document.docx

Automatic Flush Behavior and Timers

The resident server manages persistence through two independent timers defined in src/officecli/ResidentServer.cs.

The Autosave Timer

The _autosaveCts timer fires after CurrentAutosaveInterval (determined by FlushMode). When the document is dirty, it calls ExecuteSave() without shutting down the resident (lines 66-69). This ensures recent edits become visible to third-party tools while keeping the process warm for subsequent commands.

The Idle Shutdown Timer

The _idleCts timer monitors for configured idle timeouts. When elapsed, the resident performs a final flush and then closes the file (lines 55-60). This prevents resource leaks from abandoned resident processes.

Runtime Timeout Adjustments

You can modify the idle timeout dynamically without restarting the resident. The client API exposes a special RPC command __set-idle-timeout__ that invokes ResidentServer.TrySetIdleTimeout() (lines 70-77).

To change the timeout to 300 seconds (5 minutes) on a running resident:

officecli __set-idle-timeout__ 300

This adjustment takes effect immediately and persists until the resident closes.

Practical Configuration Examples

Match your configuration to your workflow requirements:

• Immediate visibility (scripting workflows) – Set OFFICECLI_RESIDENT_FLUSH=each to ensure Python python-docx or Java openpyxl scripts reading the file between commands see every change.
• Balanced performance – Use auto (default) or OFFICECLI_RESIDENT_FLUSH=5 for periodic visibility without excessive disk writes on large Excel workbooks.
• Batch processing – Set OFFICECLI_RESIDENT_FLUSH=off and run officecli save once at the end to minimize I/O during intensive mutation sequences.
• Safe external coordination – Use officecli save before launching external tools that read the file, then continue editing without closing the resident.

Summary

• Control automatic flushing via the OFFICECLI_RESIDENT_FLUSH environment variable with modes: each, auto, <N>, or off.
• Manual flushing is available through officecli save (persist without close) and officecli close (persist and terminate).
• The auto mode adapts flush intervals between 2-10 seconds based on save cost, balancing safety and performance.
• Adjust idle timeouts at runtime using the __set-idle-timeout__ RPC command.
• File paths referenced: ResidentServer.cs (lines 111-123, 55-77), CommandBuilder.Save.cs, and CommandBuilder.cs (lines 71-73).

Frequently Asked Questions

What is the default flush mode in OfficeCLI resident mode?

The default mode is auto, which enables idle-debounced flushing. The resident waits for the document to be idle for an adaptive interval between 2 and 10 seconds, adjusting based on the measured time required to save the file. This minimizes disk I/O while ensuring reasonable persistence for interactive use.

How do I force an immediate flush without closing the resident?

Run officecli save <file> while the resident is active. This command invokes ExecuteSave() in ResidentServer, writing the in-memory DOM to disk but keeping the resident process alive and the file open for subsequent edits. This is useful when external applications need to read the current state without terminating your editing session.

Can I change the flush interval while the resident is running?

You cannot change the flush mode (each/auto/off) dynamically, but you can adjust the idle timeout using the RPC command __set-idle-timeout__ <seconds>. This calls ResidentServer.TrySetIdleTimeout() (lines 70-77) and affects how long the resident waits before auto-closing. For flush interval changes, you must restart the resident with a new OFFICECLI_RESIDENT_FLUSH value.

What happens if the resident crashes before a flush occurs?

If the resident terminates unexpectedly before flushing, all mutations since the last successful flush (or since opening the file) are lost. To prevent data loss, use OFFICECLI_RESIDENT_FLUSH=each for critical workflows where every change must persist, or manually call officecli save after significant edits. The off mode carries the highest risk of data loss in crash scenarios.

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