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

> Master OfficeCLI Resident Mode: Learn when to use save vs close to flush files effectively. Persist changes or finalize your session efficiently with expert tips.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-08-05

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.

```bash

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

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) line 46 documents "open → save → (optional) close"
- **Excel**: [`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) line 120 documents identical workflow
- **PowerPoint**: [`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.

```bash
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

```bash

# 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](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md#L32)

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