# How OfficeCLI Resident Mode Works: Open, Save, and Close Commands Explained > Master OfficeCLI's resident mode. Learn how open, save, and close commands manage in memory documents and optimize file operations for efficiency. Understand when to use each command. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: how-to-guide - Published: 2026-08-08 --- **OfficeCLI's resident mode maintains a background server process that keeps documents open in memory, allowing you to execute multiple commands against the same file without the overhead of repeated disk I/O, while explicit `save` and `close` commands control persistence and file locking.** OfficeCLI is an open-source command-line interface for automating Microsoft Office document manipulation. Understanding how to leverage **OfficeCLI resident mode** is essential for building high-performance document processing pipelines that require multiple sequential operations on the same file. ## What is OfficeCLI Resident Mode? OfficeCLI resident mode creates a long-lived background process called `ResidentServer` that maintains an open document handle between commands. Instead of opening and closing the file for every operation, the resident server holds the document in memory and listens for commands via named pipes, significantly reducing latency when executing multiple mutations sequentially. ## How the Resident Server Architecture Works ### Document Handler Creation and File Locking When a resident server starts, it immediately creates an `IDocumentHandler` instance and acquires an exclusive lock on the target file. In [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs), the constructor initializes the handler at lines 29-30, ensuring that no other process can modify the document while the resident holds it. ### Named Pipe Communication The resident server establishes two named pipes for communication: - A primary command pipe (`officecli-`) for document operations - A secondary "ping" pipe for health checks and control commands This dual-pipe architecture, implemented at lines 31-34 and 49-52 of [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), allows lightweight status checks without interrupting active document processing. ### Idle Timeout and Autosave Mechanics The resident implements automatic resource management through configurable timeouts. The default idle timeout is **12 minutes**, stored in the volatile field `_idleTimeoutTicks` and initialized in the constructor (lines 55-60). If no commands arrive within this window, the server automatically shuts down, flushing pending changes and releasing the file lock. A background watchdog thread handles automatic persistence. The autosave interval adapts based on recent save durations or follows a fixed schedule, depending on the flush policy configuration (lines 63-70). ### Flush Policies and Write-Back Behavior Resident mode supports four flush policies controlled by the `OFFICECLI_RESIDENT_FLUSH` environment variable: - `each`: Save after every command - `auto`: Adaptive interval based on operation timing - Fixed interval: Specific millisecond duration - `off`: Disable autosave, rely on explicit saves Policy parsing occurs in the static constructor at lines 28-42 of [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs), storing the result in the static `FlushMode` property. ### Promote-to-Editable Optimization To minimize unnecessary write operations, residents start in read-only mode (`_editable = false` at line 22). The first mutating command (such as `set` or `add`) triggers promotion to editable mode, ensuring write-back only occurs when the document actually changes. ## Open vs Save vs Close: When to Use Each Command Understanding the distinction between these three commands is critical for correct file locking and data persistence. ### Starting a Session with `open` The `open ` command attaches to an existing resident or spawns a new `ResidentServer` process. It performs a ping check to detect running residents; if none exist, it launches a new server with the 12-minute idle timeout. For residents started by the `create` command (which uses a short 60-second timeout), `open` upgrades the timeout via the `__set-idle-timeout__` ping command. Use `open` when beginning a sequence of operations or when switching from non-resident to resident mode. ```bash # Start a resident session for document.docx officecli open document.docx # Subsequent commands reuse the same resident officecli set document.docx title "New Title" officecli add document.docx paragraph "Additional content" ``` ### Explicit Persistence with `save` The `save ` command triggers an immediate flush of the in-memory DOM to disk without terminating the resident. This is essential when external tools (like Python-docx or file watchers) need to access the current document state before the next autosave cycle. In [`src/officecli/ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentClient.cs), the `AskSave` method (lines 152-156) sends a `__save__` request to the resident, which calls `_handler.Save()` and clears the dirty flag while keeping the process alive. ```bash # Force immediate write to disk while keeping resident active officecli save document.docx # External process can now safely read the file python process_document.py document.docx ``` ### Terminating with `close` The `close ` command initiates graceful shutdown. It sends `__close__` over the ping pipe, triggering the resident's ordered teardown sequence. The server disposes the handler (flushing any pending edits) before acknowledging the client, guaranteeing file release when the command returns. After `close`, subsequent commands operate in standard non-resident mode, opening and closing the file for each operation. ```bash # Finalize changes and release the file lock officecli close document.docx ``` ## Resident Mode Lifecycle and Configuration ### Graceful Shutdown Sequence When receiving a close command or idle timeout expiration, the resident executes an ordered teardown defined in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs): 1. Stop accepting new commands 2. Flush pending changes via `_handler.Save()` 3. Dispose the document handler 4. Release named pipes 5. Terminate the process This sequence ensures no data loss occurs even if the client disconnects unexpectedly. ### Configuring Autosave Behavior Control automatic persistence through environment variables: ```bash # Set flush policy to 'each' for immediate persistence export OFFICECLI_RESIDENT_FLUSH=each # Or use adaptive autosave (default behavior) export OFFICECLI_RESIDENT_FLUSH=auto officecli open document.docx officecli set document.docx author "System" # Automatically saved based on policy ``` The `RunAutosaveWatchdogAsync` method (lines 36-60) monitors document state and triggers saves according to these settings. ## Summary - **OfficeCLI resident mode** maintains a background `ResidentServer` process that holds documents open in memory, eliminating the overhead of repeated file I/O for batch operations. - Use **`open`** to initiate or attach to a resident session, establishing the named pipe communication channels and file locks. - Use **`save`** when you need deterministic, immediate disk persistence while keeping the resident active for subsequent commands. - Use **`close`** to terminate the resident, guarantee final write-back, and release the exclusive file lock. - The resident automatically manages resources through a **12-minute idle timeout** and configurable **autosave intervals**, protecting against data loss without manual intervention. ## Frequently Asked Questions ### What happens if I forget to call `close` on a resident document? The resident server automatically shuts down after the **12-minute idle timeout** expires without receiving commands. Before terminating, the server executes its shutdown sequence to flush pending changes and release the file lock, ensuring data persistence even without explicit closure. ### Can multiple OfficeCLI processes access the same file in resident mode? No. The resident acquires an **exclusive file lock** when creating the `IDocumentHandler` in its constructor (lines 29-30 of [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs)). Only one resident can hold a specific document at a time. Subsequent `open` commands from other processes will either attach to the existing resident (if using the same pipe) or fail until the lock is released via `close` or timeout. ### How does resident mode improve performance compared to standard commands? Resident mode eliminates the overhead of parsing and loading large Office documents into memory for every operation. By reusing the in-process `IDocumentHandler` across multiple commands, subsequent mutations execute in milliseconds rather than seconds. This is particularly beneficial when processing large `.docx` or `.xlsx` files with hundreds of operations, as the document remains in memory between commands. ### When should I use `save` instead of relying on autosave? Use explicit **`save`** commands when integrating with external tools that require the file to be in a consistent state on disk at a specific point in time. While the autosave watchdog (default interval ≤10 seconds) handles routine persistence, it runs asynchronously. The `save` command provides synchronous, deterministic write-back that returns a success envelope only after the file is fully persisted, making it ideal for scripting workflows that trigger external processes immediately after document modification.