OfficeCLI Watch Command: Live Preview Server on localhost:26315

The officecli watch command starts a lightweight Server-Sent Events (SSE) server on localhost that delivers instant HTML previews of Office documents, refreshing your browser automatically whenever any officecli sub-command modifies the file.

The iOfficeAI/OfficeCLI repository provides a hot-reload development workflow through its watch functionality, enabling real-time visualization of Word, Excel, and PowerPoint document changes directly at localhost:26315. Unlike static file servers, this implementation uses named pipes and SSE relays to push updates without browser refreshes. Understanding the OfficeCLI watch command's architecture reveals how it maintains secure localhost binding while synchronizing complex document state across multiple browser tabs.

How the OfficeCLI Watch Command Works

Command Registration and Server Initialization

The watch sub-command is defined in src/officecli/CommandBuilder.Watch.cs, where the command description at lines 18-20 declares its purpose: “Start a live preview server that refreshes when officecli modifies the document…”【/src/officecli/CommandBuilder.Watch.cs†L18-L20】. When invoked, the command instantiates the WatchServer class and binds to a local TCP port—commonly 26315—printing the accessible URL to the console.

SSE Relay Architecture

At the core of the live preview system lies WatchServer.cs in src/officecli/Core/Watch/, which functions as a pure SSE relay server. The server never reads or writes the actual document file; its sole responsibility is forwarding pre-rendered HTML received via a named pipe to connected clients【/src/officecli/Core/Watch/WatchServer.cs†L16-L20】. The class maintains a list of open client streams in _sseClients and stores the current HTML payload in _currentHtml, broadcasting updates immediately upon receipt【/src/officecli/Core/Watch/WatchServer.cs†L33-L38】.

Named Pipe Communication and HTML Rendering

When you execute mutating commands such as officecli set or officecli insert, the command handler renders the document to HTML using format-specific RenderHtml methods. The ResidentServer.cs file triggers a notification to the watch session after completing a batch of mutations, as seen at lines 1367-1370【/src/officecli/ResidentServer.cs†L1367-L1370】. The WatchNotifier.cs helper then transmits this HTML through the named pipe to the running server, which instantly pushes the content to all connected browsers via SSE.

Client-Side Live Preview Mechanics

Embedded Script Resources

The watch server injects two embedded JavaScript resources into the preview page: watch-sse-core.js and watch-overlay.js. These are lazily loaded via the _sseScriptBlock lazy initializer defined at lines 95-100 of WatchServer.cs【/src/officecli/Core/Watch/WatchServer.cs†L95-L100】. The core script establishes the EventSource connection to /watch/events, while the overlay script handles DOM patching, temporary selection marks, and scroll synchronization across tabs.

State Synchronization

The server maintains in-memory state for user interactions through _currentMarks and _currentSelection structures defined at lines 68-78 of WatchServer.cs. When you create temporary marks or change the current selection in the preview, these updates synchronize across all connected browser tabs via the same named pipe mechanism used for HTML delivery.

Security and Localhost Binding

By default, the OfficeCLI watch command restricts connections to localhost or 127.0.0.1 only. The HTTP handler enforces this restriction at lines 2111-2113, rejecting external connections unless you explicitly configure the OFFICECLI_WATCH_ALLOWED_HOSTS environment variable【/src/officecli/Core/Watch/WatchServer.cs†L2111-L2113】. This ensures that sensitive document previews remain inaccessible from the local network unless deliberately exposed.

Lifecycle Management and Graceful Shutdown

The WatchServer coordinates shutdown through a shared cancellation token (_cts) described at lines 41-50, ensuring clean termination of the TCP listener and named pipe when the user presses Ctrl-C or when the idle watchdog terminates the process【/src/officecli/Core/Watch/WatchServer.cs†L41-L50】【/src/officecli/Core/Watch/WatchServer.cs†L437-L442】. This prevents orphaned processes and ensures file handles release properly after the preview session ends.

Practical Usage Example

Start the live preview server by specifying your target document:

officecli watch mydoc.docx

The terminal outputs the local URL (e.g., http://localhost:26315). Opening this address displays a placeholder page until the first mutation occurs.

In a separate terminal, modify the document to trigger an instant preview update:

officecli set text "Hello, world!" --range A1

The browser refreshes immediately, showing the rendered HTML without manual reload.

Summary

• Architecture: The officecli watch command launches an SSE relay server via WatchServer.cs that listens on localhost (default port 26315) and forwards HTML updates through named pipes.
• Communication: Mutating commands render HTML and push it to the server using WatchNotifier.cs, which broadcasts to all connected browsers via Server-Sent Events.
• Security: Connections default to localhost only; remote access requires setting the OFFICECLI_WATCH_ALLOWED_HOSTS environment variable.
• Client Experience: Embedded scripts watch-sse-core.js and watch-overlay.js handle DOM updates, selection marks, and scroll synchronization across tabs.
• Lifecycle: A shared cancellation token ensures graceful shutdown of network resources and named pipes when the process terminates.

Frequently Asked Questions

What port does the OfficeCLI watch command use by default?

The command binds to a local TCP port on localhost—commonly 26315 or dynamically assigned—and prints the exact URL (e.g., http://localhost:26315) to the console upon startup. You can open this address in any modern browser to access the live preview interface.

How does the watch server detect document changes?

When you execute commands like officecli set or officecli insert, the command handler renders the document to HTML and transmits it through a named pipe to the running WatchServer instance. The server stores this in _currentHtml and immediately broadcasts it to all connected clients via SSE, causing the browser to update without a full page reload.

Can I view the live preview from another device on my network?

By default, the server rejects non-local connections for security reasons. To enable remote access, set the OFFICECLI_WATCH_ALLOWED_HOSTS environment variable to specify permitted IP addresses or hostnames before launching the watch command.

What happens to my selection and marks when the document updates?

The server maintains your temporary marks and current selection in memory (_currentMarks and _currentSelection) and synchronizes these across all browser tabs. The watch-overlay.js script reapplies these decorations after each HTML update, preserving your context during live editing sessions.

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