OfficeCLI Save Command Flush Modes: Off, Auto, Each, and Fixed Explained

The OfficeCLI save command supports four resident flush modes—Off, Auto, Each, and Fixed—that control when in-memory document changes are persisted to disk, configurable via the OFFICECLI_RESIDENT_FLUSH environment variable.

The iOfficeAI/OfficeCLI repository implements a resident architecture that keeps documents in memory during editing sessions to optimize performance. When you execute the save command, the timing of disk persistence depends on the ResidentFlushMode configured for the session, which is defined in the ResidentFlushPolicy.cs source file. These modes determine whether changes flush automatically, on fixed intervals, only on explicit commands, or before every mutation returns.

Understanding the ResidentFlushMode Enum

In src/officecli/Core/ResidentFlushPolicy.cs, the ResidentFlushMode enum (declared at line 16) defines four distinct behaviors for persisting in-memory document state. The resident server selects the active mode during initialization by parsing the OFFICECLI_RESIDENT_FLUSH environment variable, as implemented in src/officecli/ResidentServer.cs between lines 128 and 142.

The Four OfficeCLI Save Command Flush Modes

Off Mode (ResidentFlushMode.Off)

Off disables automatic flushing entirely. The document remains in memory until you issue an explicit save or close command. This mode minimizes disk I/O but risks data loss if the resident process terminates unexpectedly before a manual save.

Auto Mode (ResidentFlushMode.Auto)

Auto serves as the default behavior. The resident flushes changes automatically during idle-autosave intervals and whenever you explicitly run the save or close commands. This balances performance with data safety by persisting changes during periods of inactivity without blocking every operation.

Each Mode (ResidentFlushMode.Each)

Each ensures maximum durability by flushing the document to disk before every mutation command returns. While this guarantees that each operation is immediately persisted, it introduces higher disk I/O overhead compared to other modes.

Fixed Mode (ResidentFlushMode.Fixed)

Fixed triggers flushes on a configurable time interval specified by the OFFICECLI_RESIDENT_FLUSH_FIXED_INTERVAL environment variable (in seconds). Like Auto, it also flushes on explicit save or close commands, making it suitable for long-running sessions where periodic checkpoints are desired without the overhead of Each mode.

How the Save Command Interacts with Flush Modes

Regardless of the active flush mode, the save command forces an immediate flush of the in-memory document to disk. According to the implementation in src/officecli/ResidentServer.cs at line 792, this ensures that the file on disk reflects the latest state even when running in Off or Fixed modes with pending changes.

Configuring Flush Modes in Practice

You control the flush behavior by setting environment variables before launching OfficeCLI. The primary variable OFFICECLI_RESIDENT_FLUSH accepts lowercase values corresponding to the enum members.

• Set OFFICECLI_RESIDENT_FLUSH to off, auto, each, or fixed
• For Fixed mode, additionally set OFFICECLI_RESIDENT_FLUSH_FIXED_INTERVAL to the desired interval in seconds

Practical Code Examples

Default Auto Mode

# Auto mode flushes on idle intervals and explicit save

officecli open mydoc.docx
officecli add text "Important content"
officecli save mydoc.docx

Each Mode for Immediate Persistence

# Each mode flushes before every mutation returns

OFFICECLI_RESIDENT_FLUSH=each officecli open mydoc.docx
officecli add text "Hello"          # Flushed immediately

officecli replace text "World"      # Flushed immediately

officecli save mydoc.docx           # Final flush

Off Mode with Explicit Control

# Off mode accumulates changes in memory only

OFFICECLI_RESIDENT_FLUSH=off officecli open mydoc.docx
officecli add text "Draft"          # Not yet persisted

officecli replace text "Final"      # Still in memory only

officecli save mydoc.docx           # Now flushed to disk

Fixed Interval Mode

# Fixed mode auto-flushes every 30 seconds

OFFICECLI_RESIDENT_FLUSH=fixed \
OFFICECLI_RESIDENT_FLUSH_FIXED_INTERVAL=30 \
officecli open mydoc.docx

# Changes accumulate; auto-flush occurs every 30s

officecli save mydoc.docx           # Ensures final state is persisted

Summary

• Off mode requires explicit save or close commands to persist changes, minimizing disk I/O but risking data loss on unexpected termination.
• Auto mode combines idle-autosave intervals with explicit commands as the default behavior for balanced performance.
• Each mode flushes before every mutation returns, ensuring immediate persistence at the cost of higher I/O overhead.
• Fixed mode uses the OFFICECLI_RESIDENT_FLUSH_FIXED_INTERVAL environment variable to schedule periodic flushes alongside explicit commands.
• The save command forces a flush regardless of the current mode, as implemented in ResidentServer.cs at line 792.

Frequently Asked Questions

What is the default flush mode for OfficeCLI?

The default flush mode is Auto (ResidentFlushMode.Auto). In this mode, the resident process automatically persists changes during idle intervals and whenever you explicitly execute the save or close commands, providing a balance between safety and performance.

How do I configure Fixed interval flushing?

Set the environment variable OFFICECLI_RESIDENT_FLUSH to fixed and define OFFICECLI_RESIDENT_FLUSH_FIXED_INTERVAL with the desired number of seconds. For example, OFFICECLI_RESIDENT_FLUSH_FIXED_INTERVAL=30 configures the resident to flush the document every 30 seconds in addition to explicit save operations.

Does the save command behave differently in Each mode versus Off mode?

No. The save command triggers an immediate flush to disk regardless of the active mode. In Each mode, changes are already persisted before the command returns, so the save operation confirms the final state. In Off mode, the save operation is the primary mechanism (aside from close) that writes accumulated in-memory changes to disk.

Where are the flush modes defined in the source code?

The flush modes are defined in the ResidentFlushMode enum located in src/officecli/Core/ResidentFlushPolicy.cs at line 16. The logic that maps environment variables to these modes and implements the flushing behavior resides in src/officecli/ResidentServer.cs, specifically around lines 128-142 for initialization and line 792 for the save command implementation.

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