How to Start a Live Preview Server with Auto-Refresh Using OfficeCLI Watch

The OfficeCLI watch command launches a local HTTP server on port 26315 that serves a live HTML preview of your Office document, automatically refreshing the view via Server-Sent Events whenever you modify the file.

The iOfficeAI/OfficeCLI repository provides a real-time document editing experience through its watch functionality. This feature eliminates the need to manually reopen documents after every change by establishing a persistent connection between your file system and browser. By running officecli watch, developers can see instant visual feedback as they programmatically manipulate Word, Excel, or other Office formats.

How the Auto-Refresh Architecture Works

The live preview system in OfficeCLI operates through a sophisticated two-layer JavaScript architecture that streams document changes directly to your browser.

Layer 1: Server-Sent Events Core (watch-sse-core.js)

At the foundation lies src/officecli/Resources/watch-sse-core.js, which exports an EventSource instance assigned to window._watchEs. This core layer establishes a persistent SSE connection that streams document-rendering events from the server to the client. After each DOM mutation occurs, the script invokes window._watchReapplyHook() to trigger UI updates, ensuring decorations and overlays redraw without requiring a full page refresh.

Layer 2: UI Overlay (watch-overlay.js)

The presentation layer resides in src/officecli/Resources/watch-overlay.js, which consumes the EventSource through var es = window._watchEs. This file handles visual decorations, selection management, and click-to-navigate functionality. Critically, it registers the reapply hook via window._watchReapplyHook = reapplyDecorations, creating the callback mechanism that refreshes the interface whenever the underlying document structure changes.

Starting the Live Preview Server

To initiate the watch process, execute the watch command followed by your target document. The server defaults to port 26315, though you can specify alternatives.

# Start preview for a Word document (default port 26315)

officecli watch my-report.docx

# Start on a custom port

officecli watch my-report.docx --port 3000

Once running, navigate to http://localhost:26315 (or your custom port) to view the live HTML rendering.

Managing the Watch Process

OfficeCLI enforces a same-file single-watch constraint—only one active watch process may monitor a specific file at any given time. Control your preview session using these supplementary commands:

• officecli unwatch <file> - Terminates the active watch process and shuts down the HTTP server.
• officecli goto <file> <path> - Scrolls the preview to a specific element using a data-path selector (e.g., p[3] for the third paragraph).
• officecli set <file> [options] - Applies live modifications that instantly reflect in the browser, such as text replacement or color changes.

# Stop the preview server

officecli unwatch my-report.docx

# Jump to the third paragraph

officecli goto my-report.docx data-path="p[3]"

# Apply a live style change

officecli set my-report.docx --find "Revenue" --replace "Revenue (Q1)" --color "#ff6600"

Configuration Reference

According to the command reference documented in SKILL.md, the watch server binds to port 26315 by default. The system utilizes Server-Sent Events rather than WebSockets, providing lightweight one-way communication optimized for document preview scenarios. Remember that the auto-refresh mechanism depends on both watch-sse-core.js and watch-overlay.js executing correctly in the browser context, as implemented in the iOfficeAI/OfficeCLI source code.

Summary

• OfficeCLI watch launches an HTTP server (default port 26315) serving live HTML previews of Office documents.
• Auto-refresh works through Server-Sent Events streamed via window._watchEs in watch-sse-core.js.
• UI updates are triggered by window._watchReapplyHook() registered in watch-overlay.js.
• Single-process constraint: Only one watch instance may monitor a specific file simultaneously.
• Lifecycle commands: Use unwatch to stop, goto to navigate, and set/mark to apply live changes.

Frequently Asked Questions

What port does OfficeCLI watch use by default?

The default port is 26315. You can override this using the --port flag followed by your desired port number when starting the watch process.

How does the auto-refresh mechanism work without reloading the page?

OfficeCLI uses Server-Sent Events (SSE) via the EventSource API exposed in watch-sse-core.js. The server streams mutation events to the browser, which then invokes window._watchReapplyHook() to redraw only the modified DOM elements through the overlay layer defined in watch-overlay.js.

Can I run multiple watch processes for different files simultaneously?

Yes, you can watch different files in parallel, but you cannot run more than one watch process per specific file at a time. Attempting to start a second watch on an already-monitored file will fail due to the same-file single-watch enforcement.

How do I navigate to specific content within the live preview?

Use the goto command with a data-path selector. For example, officecli goto document.docx data-path="p[3]" scrolls the preview viewport to the third paragraph, enabling rapid inspection of specific document sections during editing.

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