OfficeCLI Environment Variables: How OFFICECLI_NO_AUTO_RESIDENT and OFFICECLI_RESIDENT_FLUSH Control Document Processing

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 (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 (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 (lines 7–8) and implemented in 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.
• <seconds> – 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 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:

# 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.

# 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.

# 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, McpServer.cs, ResidentServer.cs, and 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 (lines 586–588) and src/officecli/McpServer.cs (lines 41–42). OFFICECLI_RESIDENT_FLUSH is parsed in src/officecli/ResidentServer.cs (lines 123–132) with policy definitions in src/officecli/Core/ResidentFlushPolicy.cs (lines 7–8).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}