# How to Control Flushing in OfficeCLI Resident Mode: A Complete Guide > Effortlessly control flushing in OfficeCLI resident mode. Learn to use environment variables or manual commands for data persistence. Read the complete guide now. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: how-to-guide - Published: 2026-07-09 --- **Set the `OFFICECLI_RESIDENT_FLUSH` environment variable to `each`, `auto`, ``, 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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. - **``** – 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`: ```bash export OFFICECLI_RESIDENT_FLUSH=each officecli open document.docx ``` For a fixed 5-second flush interval: ```bash export OFFICECLI_RESIDENT_FLUSH=5 officecli open document.docx ``` To disable automatic flushing for batch operations: ```bash 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 `** command writes in-memory changes to disk while keeping the resident process alive. According to [`src/officecli/CommandBuilder.Save.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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. ```bash officecli save document.docx ``` ### Using officecli close The **`officecli close `** command flushes pending changes and immediately terminates the resident server, releasing the file lock. As shown in [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) (lines 71-73), this performs a final save before shutdown. ```bash officecli close document.docx ``` ## Automatic Flush Behavior and Timers The resident server manages persistence through two independent timers defined in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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: ```bash 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`, ``, 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) (lines 111-123, 55-77), [`CommandBuilder.Save.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Save.cs), and [`CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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 `** 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__ `**. 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.