How to Disable Auto-Resident Behavior in OfficeCLI: A Complete Guide

Set the OFFICECLI_RESIDENT_FLUSH environment variable to off or use the --no-resident flag to prevent OfficeCLI from spawning background resident processes.

OfficeCLI uses an auto-resident architecture to keep documents open in memory between commands, eliminating startup overhead for successive operations. While this improves performance for interactive workflows, the resident behavior can interfere with CI/CD pipelines and external file monitoring tools that require immediate disk persistence. This guide explains how to disable auto-resident behavior in iOfficeAI/OfficeCLI using environment variables and command-line flags, based on the actual source implementation.

Understanding the Resident Process

The resident process is a background service that maintains open document handles in memory. When you run commands like create or open, OfficeCLI automatically starts this resident to enable near-zero latency on subsequent operations. The resident writes changes to disk based on a configurable flush policy defined in src/officecli/Core/ResidentFlushPolicy.cs.

According to the source code in src/officecli/ResidentServer.cs, the resident checks the OFFICECLI_RESIDENT_FLUSH environment variable during initialization (lines 123-132) to determine whether to start and how frequently to persist changes to disk.

Method 1: Set the OFFICECLI_RESIDENT_FLUSH Environment Variable

Setting OFFICECLI_RESIDENT_FLUSH to off completely disables the resident layer, forcing every command to run as a one-shot process that writes directly to disk and exits immediately.

Configure this in your shell before running OfficeCLI commands:

# Bash / Zsh

export OFFICECLI_RESIDENT_FLUSH=off
officecli create report.docx
officecli add report.docx / --type paragraph --prop text="Hello, world!"

# PowerShell

$env:OFFICECLI_RESIDENT_FLUSH = "off"
officecli create report.docx

In src/officecli/ResidentServer.cs (lines 123-132), the application reads this variable during resident initialization. When set to off, the CLI bypasses the resident server entirely, ensuring that external tools reading the file see the latest changes immediately after each command completes.

Method 2: Use the --no-resident Flag

For workflows that occasionally need direct disk access without disabling the resident globally, append the --no-resident flag to commands that would otherwise auto-start a resident (such as create).

officecli create new.pptx --no-resident
officecli add new.pptx / --type slide --prop title="Intro"

This flag instructs OfficeCLI to skip the resident layer for that specific operation while leaving the global flush policy unchanged. The --no-resident option is documented alongside the resident management commands in src/officecli/CommandBuilder.cs and is particularly useful when mixing resident-enabled workflows with one-off automation scripts.

How the Flush Policy Works

The resident behavior is governed by four flush modes implemented in src/officecli/Core/ResidentFlushPolicy.cs:

• each: Writes to disk after every command
• auto: Flushes based on internal heuristics
• <seconds>: Flushes on a timed interval
• off: Disables the resident completely

The help text for the close and save commands in src/officecli/CommandBuilder.cs (lines 71-73) and src/officecli/CommandBuilder.Save.cs (lines 28-30) documents this behavior, explaining that OFFICECLI_RESIDENT_FLUSH controls both the persistence strategy and whether the resident process starts at all.

When to Disable the Resident

Disable the auto-resident behavior in these scenarios:

• CI/CD Pipelines: Build agents should not keep background processes alive between steps, and jobs require immediate file consistency
• External Monitoring: File watchers and sync tools require documents to be closed and flushed to disk immediately
• Concurrent Access: When multiple processes must read the file while OfficeCLI writes to it, bypassing the resident prevents file locking conflicts
• Debugging: Eliminate the resident layer to rule out memory-related issues or stale state corruption

Summary

• Set OFFICECLI_RESIDENT_FLUSH=off to globally disable the resident process and force direct disk writes on every command
• Use --no-resident on individual commands to bypass the resident without changing global environment settings
• The resident logic is implemented in src/officecli/ResidentServer.cs and controlled via src/officecli/Core/ResidentFlushPolicy.cs
• Disabling the resident ensures immediate persistence but adds startup overhead to each command execution

Frequently Asked Questions

What is the default flush policy in OfficeCLI?

By default, OfficeCLI uses an automatic flush policy that keeps the resident alive and writes changes based on internal heuristics or timed intervals. This behavior is documented in src/officecli/CommandBuilder.cs (lines 71-73) and can be overridden by setting OFFICECLI_RESIDENT_FLUSH or using the --no-resident flag.

Can I re-enable the resident after disabling it with the environment variable?

Yes. Since OFFICECLI_RESIDENT_FLUSH is read at process startup, simply unset the variable or set it to auto, each, or a specific number of seconds before running OfficeCLI commands. The change takes effect immediately for the next process invocation.

Does using --no-resident affect performance?

Yes. Without the resident process, each command must initialize the full OfficeCLI runtime and open the document from disk, which increases latency compared to keeping the document resident in memory. Use this flag only when immediate disk persistence outweighs the performance benefits of the resident architecture.

Where is the resident flush policy implemented in the source code?

The flush policy logic resides in src/officecli/Core/ResidentFlushPolicy.cs, which defines the four modes (each, auto, <seconds>, off). The environment variable is parsed in src/officecli/ResidentServer.cs (lines 123-132), and the command-line descriptions referencing this behavior appear in src/officecli/CommandBuilder.cs (lines 71-73) and src/officecli/CommandBuilder.Save.cs (lines 28-30).

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