OfficeCLI Resident Mode: How to Flush Files and When to Use Save vs Close

Use officecli save to persist changes to disk while keeping the resident process alive for further edits, and officecli close when you need to finalize the session and release the file lock.

OfficeCLI's resident mode maintains documents in a long-running native process, applying edits to an in-memory model rather than writing to disk immediately. This design enables fast, sequential edits but requires explicit file flushing when external tools need access to your changes. Understanding the distinction between save and close commands—and when to apply each—is essential for integrating OfficeCLI into automated workflows and multi-tool pipelines.

How Resident Mode Handles File Flushing

When you open a document in resident mode, OfficeCLI loads it into memory and holds a lock on the file. All subsequent set, add, remove, and other mutation commands operate against this in-memory representation. The binary defers disk writes until one of four flush triggers occurs, as documented in README.md (line 32) and implemented across the SDK.

Four Ways to Trigger a Flush

Trigger	Behavior	Best For
officecli save <file>	Writes in-memory state to disk without terminating the resident	Continuing the editing session after external hand-off
officecli close <file>	Writes to disk and terminates the resident process	Finishing the session and releasing the lock
Idle auto-flush	Automatic save after 2–10 seconds of inactivity	Guaranteed persistence without explicit commands
OFFICECLI_RESIDENT_FLUSH=each	Immediate save after every mutation	Pipelines requiring real-time external visibility

The idle auto-flush interval adapts to document save cost, as noted in the official documentation. Larger documents with longer save times receive longer idle windows to avoid performance penalties.

Save vs Close: Key Differences

Both save and close persist your in-memory changes to disk, but their lifecycle implications differ significantly.

save: Keep the Resident Warm

The save command is idempotent and safe for repeated calls. It pushes current state to disk without side effects on session state.

# Flush before external tool reads the file

officecli save report.docx
python my_processor.py report.docx  # External tool sees latest changes

# Continue editing—the resident remains active

officecli set report.docx /body/p[2]/r[1] --prop text="Additional content"

As implemented in the resident architecture, save never discards work or errors on repeated invocation. Use it when you need intermittent disk visibility while maintaining the performance benefits of a warm resident.

close: Finalize and Release

The close command combines a final write with resident termination, completely releasing the file lock.

# End the session—no further edits possible without reopening

officecli close report.docx

After close, you must execute a fresh officecli open to modify the file again. The Node.js SDK type definitions in sdk/node/index.d.ts (line 56) explicitly document this behavior: stopping the resident triggers the final flush to disk.

When to Use Each Command

Situation	Command	Rationale
Hand off to external tool, then resume editing	save	Maintains resident state; avoids reopening overhead
Session complete or lock must release	close	Clean termination; frees resources
Real-time pipeline requiring immediate visibility	OFFICECLI_RESIDENT_FLUSH=each	Every mutation persisted before command returns
Tolerable 2–10 second delay before persistence	(none)	Rely on idle auto-flush

The format-specific skill files reinforce this lifecycle pattern consistently:

• Word: SKILL.md line 46 documents "open → save → (optional) close"
• Excel: SKILL.md line 120 documents identical workflow
• PowerPoint: SKILL.md line 203 confirms same pattern

Environment Variable: OFFICECLI_RESIDENT_FLUSH

Set OFFICECLI_RESIDENT_FLUSH=each to override the default deferred-write behavior. This forces immediate persistence after every mutation command while keeping the resident active.

export OFFICECLI_RESIDENT_FLUSH=each

officecli open data.xlsx
officecli set data.xlsx /Sheet1/A1 --prop value=42   # Written before next prompt

# Concurrent process can read immediately

Use this setting in CI pipelines or multi-process workflows where external visibility must lag zero commands behind mutations.

Complete Workflow Example

# 1. Initialize resident session

officecli open contract.docx

# 2. Batch edits (no disk writes yet)

officecli set contract.docx /body/p[1]/r[1] --prop bold=true
officecli add contract.docx /body --type paragraph --prop style=Heading2
officecli set contract.docx /body/p[2]/r[1] --prop text="Scope of Work"

# 3. Flush for PDF rendering while continuing session

officecli save contract.docx
weasyprint contract.docx preview.pdf  # Sees all edits above

# 4. Additional edits based on preview feedback

officecli set contract.docx /body/p[2]/r[1] --prop text="Revised Scope of Work"

# 5. Final persistence and cleanup

officecli close contract.docx

Critical Distinction for External Tool Integration

OfficeCLI's own read commands (get, query, view, dump) always observe latest in-memory edits regardless of flush state. You only need explicit save or close when a non-OfficeCLI program will read the file:

"officecli's own reads … always see your latest edits, so within officecli you never need to save mid‑workflow. But a live resident defers the disk write, so before a non‑officecli program reads the file — python‑docx/openpyxl, Microsoft Word, a renderer, delivery/upload — flush it." — README.md § Flushing

Summary

• Resident mode defers disk writes for performance, keeping documents in memory
• save persists to disk while preserving the resident session for further edits
• close persists and terminates, requiring open to resume modifications
• Idle auto-flush (2–10s) provides safety net for forgotten saves
• OFFICECLI_RESIDENT_FLUSH=each enables real-time persistence for demanding pipelines
• Flush only when external tools need file access—OfficeCLI reads are always current

Frequently Asked Questions

What happens if I forget to save in resident mode?

Your changes remain safe in memory. The resident's idle auto-flush automatically persists to disk after 2–10 seconds of inactivity, with the interval adapting to your document's measured save cost. However, external tools cannot see changes until this auto-flush or an explicit save occurs.

Can I call save multiple times on the same resident session?

Yes. The save command is designed for safe repeated invocation. Each call writes the current in-memory state to disk without error or data loss, and the resident stays active for continued editing.

Why would I use close instead of just killing the process?

officecli close ensures clean, atomic persistence and proper lock release. Killing the process risks file corruption or lock artifacts, and may leave temporary resident files. Always use close for production workflows.

Does OFFICECLI_RESIDENT_FLUSH=each slow down batch operations?

Potentially. Immediate per-mutation saves add I/O overhead. For high-volume edit batches, prefer the default deferred mode with periodic save calls, or bracket critical external hand-offs with explicit saves rather than global each mode.

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