# OfficeCLI Environment Variables: How OFFICECLI_NO_AUTO_RESIDENT and OFFICECLI_RESIDENT_FLUSH Control Document Processing > Discover how OFFICECLI_NO_AUTO_RESIDENT and OFFICECLI_RESIDENT_FLUSH environment variables control OfficeCLI's persistent process and document flushing for efficient document processing. Learn to manage your OfficeCLI workflow. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: deep-dive - Published: 2026-08-08 --- **OfficeCLI uses two environment variables—`OFFICECLI_NO_AUTO_RESIDENT` and `OFFICECLI_RESIDENT_FLUSH`—to control whether a persistent background resident process automatically starts and when in-memory document changes are written to disk.** The iOfficeAI/OfficeCLI repository implements a **resident process** architecture that keeps documents open in memory for rapid successive edits. Configuring these **OfficeCLI environment variables** allows you to optimize performance for automated scripts or guarantee data consistency when integrating with external tools. ## Understanding the Resident Process Architecture OfficeCLI maintains a resident process that keeps a document open in memory between commands. This design eliminates the overhead of reloading files for each operation, enabling faster batch processing. By default, the resident starts automatically when you run commands like `open` or `import`, and it flushes changes to disk using an adaptive idle timer. Two specific environment variables govern this behavior: one controls the **lifecycle** of the resident process, while the other manages the **persistence timing** of your modifications. ## OFFICECLI_NO_AUTO_RESIDENT: Disabling Automatic Resident Startup The `OFFICECLI_NO_AUTO_RESIDENT` variable determines whether OfficeCLI spawns a background resident process automatically. ### How the Code Checks This Variable According to the source code in `iOfficeAI/OfficeCLI`, the application checks for this variable in two critical locations: - In [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) (lines 586–588), the code calls `Environment.GetEnvironmentVariable("OFFICECLI_NO_AUTO_RESIDENT")` to determine whether to initialize a resident session. - In [`src/officecli/McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/McpServer.cs) (lines 41–42), the variable sets the default behavior when no explicit flag is provided. When this variable is set to `1`, OfficeCLI runs in **non-resident mode**, meaning every command executes independently and exits immediately without leaving a background process. ### When to Disable Auto-Resident Set `OFFICECLI_NO_AUTO_RESIDENT=1` when running scripts that require a clean state for each operation or when you want to avoid the resource overhead of a persistent background process. This ensures deterministic, stateless execution at the cost of slower repeated operations on the same file. ## OFFICECLI_RESIDENT_FLUSH: Configuring Disk Flush Behavior The `OFFICECLI_RESIDENT_FLUSH` variable controls when the resident process writes in-memory changes to the physical file on disk. ### Available Flush Policy Values The resident process supports four distinct flushing modes, as defined in [`src/officecli/Core/ResidentFlushPolicy.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/ResidentFlushPolicy.cs) (lines 7–8) and implemented in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) (lines 123–132): - **`each`** – Flushes changes to disk immediately after every mutating command. Use this when external programs need to read the file between OfficeCLI operations. - **`auto`** – The default adaptive mode that flushes a few seconds after the resident goes idle. This balances performance with data safety. - **``** – A custom numeric value specifying the exact number of seconds to wait after the last change before flushing. - **`off`** – Disables automatic flushing entirely. Changes remain in memory until you explicitly call `save` or `close`. ### Implementation Details The [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) file parses this variable during initialization to instantiate the appropriate `ResidentFlushPolicy`. The policy evaluation occurs at line 123, where the server configures its background flush timer based on the parsed value. ## Practical Configuration Examples Configure these variables in your shell environment before executing OfficeCLI commands: ```bash # Disable automatic resident startup for one-off commands export OFFICECLI_NO_AUTO_RESIDENT=1 officecli open my.docx get text # The command executes and exits without leaving a background process. ``` ```bash # Ensure every mutation is immediately persisted for external tool compatibility export OFFICECLI_RESIDENT_FLUSH=each officecli open my.docx set text "Hello" officecli open my.docx set style bold # After each command, changes are written to disk, allowing subsequent # Python scripts or other tools to read the updated content. ``` ```bash # Batch multiple edits without intermediate disk writes export OFFICECLI_RESIDENT_FLUSH=off officecli open my.docx set text "Batch edit..." officecli open my.docx set property title "Updated" # No disk writes occur until you explicitly trigger persistence: officecli save # Flushes to disk while keeping the resident active # Or: officecli close # Flushes and terminates the resident process ``` ## Summary - **OFFICECLI_NO_AUTO_RESIDENT** controls whether a persistent background process starts automatically; set to `1` to force stateless, single-command execution. - **OFFICECLI_RESIDENT_FLUSH** determines when in-memory changes are written to disk, with options ranging from immediate (`each`) to manual (`off`). - The source code implements these checks in [`CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.cs), [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs), [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), and [`ResidentFlushPolicy.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentFlushPolicy.cs). - Use `OFFICECLI_RESIDENT_FLUSH=each` when piping OfficeCLI output to other applications that read the same file. ## Frequently Asked Questions ### What happens if I set OFFICECLI_NO_AUTO_RESIDENT=1? OfficeCLI will not start a background resident process automatically. Every command runs in isolation, opening and closing the document file independently. This increases execution time for batch operations but ensures no persistent processes remain after each command completes. ### What is the default value of OFFICECLI_RESIDENT_FLUSH? The default value is `auto`, which enables an adaptive idle-flush mechanism. The resident waits a few seconds after the last modification before writing changes to disk, optimizing for both performance and data durability. ### How do I ensure external tools see my changes immediately? Set `OFFICECLI_RESIDENT_FLUSH=each` before running your commands. This forces the resident to flush changes to disk after every mutating operation, ensuring that subsequent reads by external programs like Python's `python-docx` or other CLI tools access the most recent data without requiring an explicit `save` command. ### Where are these environment variables checked in the OfficeCLI source code? `OFFICECLI_NO_AUTO_RESIDENT` is checked in [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) (lines 586–588) and [`src/officecli/McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/McpServer.cs) (lines 41–42). `OFFICECLI_RESIDENT_FLUSH` is parsed in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs) (lines 123–132) with policy definitions in [`src/officecli/Core/ResidentFlushPolicy.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/ResidentFlushPolicy.cs) (lines 7–8).