# OfficeCLI Watch Command: Live Preview Server on localhost:26315

> Explore the OfficeCLI watch command to instantly preview Office documents on localhost:26315. Get live HTML previews with automatic browser refreshes as you edit.

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

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-sse-core.js) and [`watch-overlay.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-overlay.js). These are lazily loaded via the `_sseScriptBlock` lazy initializer defined at lines 95-100 of [`WatchServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

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

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-sse-core.js) and [`watch-overlay.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/watch-overlay.js) script reapplies these decorations after each HTML update, preserving your context during live editing sessions.