# How `OFFICECLI_RESIDENT_FLUSH` Controls Document Persistence in OfficeCLI

> Learn how the OFFICECLI_RESIDENT_FLUSH environment variable controls document persistence in OfficeCLI. Explore four modes balancing durability and performance.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: internals
- Published: 2026-07-08

---

**The `OFFICECLI_RESIDENT_FLUSH` environment variable determines when OfficeCLI writes the in-memory document back to disk, offering four modes that trade durability against performance.**

The `OFFICECLI_RESIDENT_FLUSH` environment variable is the primary control mechanism for the resident server's persistence behavior in iOfficeAI/OfficeCLI. When running commands against `.docx`, `.xlsx`, or `.pptx` files, OfficeCLI maintains a live in-memory copy (the "resident") to enable rapid successive modifications. This variable dictates exactly when that memory buffer synchronizes to the filesystem, ranging from immediate per-command flushes to adaptive background saves or manual-only persistence.

## Understanding the Resident Flush Mechanism

The resident server keeps documents hot in memory to eliminate redundant disk I/O between commands. However, external programs—such as Python-docx, OpenPyXL, or Microsoft Word—only see changes once the resident **flushes** its DOM to disk. The `OFFICECLI_RESIDENT_FLUSH` variable configures this synchronization timing by selecting one of four distinct policies defined in [`src/officecli/Core/ResidentFlushPolicy.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/ResidentFlushPolicy.cs) (lines 5–15).

## The Four `OFFICECLI_RESIDENT_FLUSH` Modes

During static initialization of `ResidentServer` (lines 123–127 in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs)), the variable is parsed and stored in the static fields `FlushMode` and `FixedFlushInterval` (lines 128–142). The supported values are:

### `each` – Deterministic Durability

Setting `OFFICECLI_RESIDENT_FLUSH=each` forces a flush **before every mutation command returns**. This guarantees that the file on disk always reflects the latest change, ensuring external tools see immediate updates. The trade-off is an extra `O(n)` serialization cost per command.

### `auto` – Adaptive Background Save (Default)

When unset or set to `auto`, the system uses an adaptive interval calculated as `clamp(4 × EMA(save-time), 2s, 10s)`. This exponential moving average (updated via `RecordSaveDuration` at lines 57–68 in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs)) ensures background saves never consume more than approximately 25% of wall-clock time while keeping idle latency between 2 and 10 seconds.

### `<N>` – Fixed Idle Interval

Specify a positive integer (e.g., `OFFICECLI_RESIDENT_FLUSH=5`) to flush after exactly `N` seconds of resident idle time. This reproduces pre-adaptive behavior and offers predictable timing without the variability of the EMA calculation.

### `off` or `0` – Manual Control

Setting `OFFICECLI_RESIDENT_FLUSH=off` disables automatic flushing entirely. Changes persist only in memory until you explicitly invoke `officecli save`, `officecli close`, or terminate the process.

## Legacy Compatibility and Variable Parsing

If `OFFICECLI_RESIDENT_FLUSH` is undefined, OfficeCLI checks the legacy alias `OFFICECLI_RESIDENT_IDLE_SAVE_SECONDS` for backward compatibility (same initialization block, lines 123–127). The `ResidentFlushPolicy.TryParse` method handles the string-to-enum conversion, validating inputs against the four modes while supporting numeric strings for fixed intervals.

## Configuration Examples

Configure the environment variable before starting your OfficeCLI session:

```bash

# Adaptive auto-flush (default behavior)

export OFFICECLI_RESIDENT_FLUSH=auto
officecli open document.docx
officecli set document.docx '/p[1]' --text "Immediate"

# Persists to disk 2-10 seconds after command completion

```

```bash

# Flush every mutation synchronously

export OFFICECLI_RESIDENT_FLUSH=each
officecli add report.docx '/body' --text "Data"

# File updated on disk before CLI returns

```

```bash

# Fixed 5-second idle delay

export OFFICECLI_RESIDENT_FLUSH=5
officecli set spreadsheet.xlsx '/sheet1/cell[A1]' --value "100"

# Auto-saves exactly 5 seconds after last activity

```

```bash

# Disable auto-flush for manual control

export OFFICECLI_RESIDENT_FLUSH=off
officecli set presentation.pptx '/slide[1]/title' --text "Draft"
officecli save presentation.pptx  # Explicit persistence required

```

## Summary

- **`OFFICECLI_RESIDENT_FLUSH`** controls when the resident server serializes in-memory documents to disk.
- Valid modes are **`each`** (every command), **`auto`** (adaptive 2–10s), **`<N>`** (fixed seconds), and **`off`** (manual only).
- The variable is parsed during static initialization of `ResidentServer` and stored in `FlushMode`/`FixedFlushInterval`.
- Legacy fallback to `OFFICECLI_RESIDENT_IDLE_SAVE_SECONDS` maintains backward compatibility.
- Choose `each` for pipeline reliability where external tools read after every command, or `auto` for optimal background performance.

## Frequently Asked Questions

### What happens if I don't set `OFFICECLI_RESIDENT_FLUSH`?

OfficeCLI defaults to `auto` mode, which uses an adaptive algorithm to flush the resident 2–10 seconds after activity ceases. This balances immediate availability with I/O efficiency by calculating the delay based on the exponential moving average of previous save durations.

### Can I use `OFFICECLI_RESIDENT_FLUSH` in CI/CD pipelines?

Yes. For CI/CD pipelines where subsequent steps depend on file modifications being visible on disk, set `OFFICECLI_RESIDENT_FLUSH=each` to ensure every mutation is persisted before the command returns, eliminating race conditions between OfficeCLI and downstream tools.

### Does `OFFICECLI_RESIDENT_FLUSH` affect the resident server's memory usage?

Indirectly. In `off` mode, the resident accumulates changes only in memory until explicit closure, potentially increasing memory footprint for large documents. The `each` and `auto` modes periodically serialize and release buffers, maintaining predictable memory consumption according to the save schedule.

### Where is the flush logic implemented in the source code?

The parsing logic resides in [`src/officecli/Core/ResidentFlushPolicy.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/ResidentFlushPolicy.cs) (lines 5–15), while the runtime state and adaptive EMA calculation are implemented in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) (lines 57–68 and 123–142).