command save

save

Flush pending in-memory changes to disk without stopping the resident process.

Synopsis

officecli save <file>

Description

While a resident process is active, mutations (set, add, remove, batch) are applied to the in-memory document and reported as success, but the file on disk is not rewritten on every command — it is flushed on save, close, the idle auto-save (adaptive 2–10s), or idle shutdown. This deferral avoids re-serializing the whole document on each command, which is the whole point of resident mode.

save writes the current in-memory state to disk and leaves the resident running, so subsequent commands stay fast. Use it whenever another program needs to read the file mid-session:

• a third-party reader that opens the file directly — python-docx, PizZip, openpyxl, pandas, Microsoft Word, a fresh process;
• an external renderer or screenshot tool;
• anything that is not an OfficeCLI command (OfficeCLI commands route through the resident and already see the latest in-memory state).

If no resident is active, save is a no-op success.

A live resident also flushes on its own when it goes idle, so save is the immediate version of the idle auto-save. The four flush triggers:

Trigger	Flushes to disk	Keeps resident running	When
save (explicit)	✅	✅ stays fast	immediately
close (explicit)	✅	❌ releases file	immediately
idle auto-save	✅	✅ stays fast	shortly after going idle — adaptive 2–10s by default (policy via OFFICECLI_RESIDENT_FLUSH: each/auto/<seconds>/off)
idle shutdown	✅	❌ releases file	60s auto-start / 12 min after open

save = flush + keep, close = flush + stop. Run save when an external tool needs the file right now instead of waiting for the idle auto-save — or set OFFICECLI_RESIDENT_FLUSH=each so every mutation is flushed before it returns. See open / close → When the file on disk is refreshed.

Arguments

Name	Type	Required	Default	Description
file	FileInfo	Yes	-	Office document path (.docx, .xlsx, .pptx)

Options

Name	Type	Required	Default	Description
--json	bool	No	false	Output result as JSON envelope

Examples

# Edit, then flush so an external tool can read the result — but keep editing fast
officecli set report.docx /body/p[1] --prop bold=true
officecli save report.docx            # disk now reflects the edit; resident still running
python my_reader.py report.docx       # third-party reader sees the change
officecli set report.docx /body/p[2] --prop italic=true   # still fast (resident alive)
officecli close report.docx           # final flush + stop resident when done

# Batch then flush for an external renderer / screenshot
officecli batch deck.pptx --input updates.json
officecli save deck.pptx
python tools/officeshot.py deck.pptx -d /tmp/shots/

When to use save vs close vs auto-save vs OFFICECLI_NO_AUTO_RESIDENT

• save — mid-session flush now; an external program must read the file but you have more edits coming. Fastest for long workflows.
• close — you are done with this file; flush and release it (also lets create overwrite it).
• idle auto-save — you do nothing; the resident flushes shortly after the last command (adaptive 2–10s) and stays running. Good enough when the external read is not time-critical; use save when it cannot wait.
• OFFICECLI_RESIDENT_FLUSH=each — every mutation is on disk before its command returns, and the resident stays warm. The deterministic choice for pipelines where another program reads after every command; much faster than OFFICECLI_NO_AUTO_RESIDENT=1 on large documents because the parse cache survives.
• OFFICECLI_NO_AUTO_RESIDENT=1 — skip the resident entirely; every command opens-once / saves-once so the disk file is always current. Simplest when an external program reads after every command, at the cost of per-command file I/O.

See Also

• open / close — resident process lifecycle and the deferred-flush model
• batch — multi-command execution
• Troubleshooting — "Edit reports success but a third-party tool reads the old file"