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

> Understand OfficeCLI save command flush modes: Off, Auto, Each, and Fixed. Learn how they control document persistence and optimize your workflow with the OFFICECLI_RESIDENT_FLUSH environment variable.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: deep-dive
- Published: 2026-07-29

---

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

```bash

# 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

```bash

# 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

```bash

# 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

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs), specifically around lines 128-142 for initialization and line 792 for the save command implementation.