# How to Integrate with OfficeCLI Using Python and Node.js SDKs: Named Pipe Communication Guide > Integrate OfficeCLI with Python and Node.js SDKs using named pipe communication. Achieve sub-second document manipulation by sending JSON commands via UTF-8 messages. Learn how now. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: how-to-guide - Published: 2026-08-01 --- **OfficeCLI's Python and Node.js SDKs communicate with a resident background process through named pipes by encoding JSON commands as single-line UTF-8 messages, enabling sub-second document manipulation without spawning new processes.** The iOfficeAI/OfficeCLI repository provides lightweight SDK wrappers that abstract the complexity of inter-process communication (IPC). Both the Python ([`sdk/python/officecli.py`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/python/officecli.py)) and Node.js ([`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js)) implementations follow an identical RPC protocol over named pipes, allowing scripts to manipulate Office documents with minimal latency. ## Named Pipe Architecture and Naming Convention OfficeCLI maintains a persistent resident process that hosts the Office document in memory. To locate this process, the SDKs generate a deterministic pipe name derived from the document's canonical path. ### Pipe Name Generation The pipe name follows a strict hashing scheme to ensure both sides reference the same endpoint: ```text officecli-[:16] (uppercase) ``` The path undergoes platform-specific canonicalization before hashing. On Windows, `Path.GetFullPath` resolves symbolic links and relative components. On Unix systems, the Python SDK uses `os.path.abspath` followed by `os.path.realpath` to eliminate symlinks. This canonicalization prevents connection failures when the same file is accessed through different path representations. As implemented in [`officecli.py`](https://github.com/iOfficeAI/OfficeCLI/blob/main/officecli.py) lines 28-38 and mirrored in [`index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/index.js), the `pipe_paths` helper returns both the main command pipe and the auxiliary ping pipe (suffixed with `-ping`). ### Transport Layer Implementation The underlying transport differs by operating system but presents a unified interface: - **Unix**: Unix-domain sockets located at `$TMPDIR/CoreFxPipe_` (falling back to `/tmp` if `$TMPDIR` is unset) - **Windows**: Named pipes at `\\.\pipe\` The resident process creates two pipes upon initialization. The main pipe handles document commands, while the secondary ping pipe manages health checks and idle-timeout negotiations. Both use line-delimited JSON over UTF-8, with each request and response terminated by `\n`. ## Request Protocol and Communication Flow Understanding the wire format is essential for debugging or extending the SDKs beyond their built-in capabilities. ### JSON Request Structure Every command sent through the pipe conforms to a strict envelope format: ```json { "Command": "set|get|save|batch|...", "Args": { }, "Props": { }, "Json": null } ``` The `Command` field maps directly to OfficeCLI CLI operations. The SDKs do not transform the payload; they forward the dictionary exactly as received. This design allows the Python `send()` method and Node `send()` function to support any command available in the CLI `batch` mode without SDK updates. ### Ping Pipe Operations The `-ping` pipe serves dual purposes within the communication protocol: 1. **Health Verification**: Before sending document commands, `ResidentClient.TryConnect` (see [`ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentClient.cs) lines 24-39) transmits a `__ping__` request to verify the resident is alive and bound to the expected file path. 2. **Idle Timeout Upgrade**: When opening documents, the SDK calls `SendSetIdleTimeout` ([`ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentClient.cs) lines 26-44) to send a `__set-idle-timeout__` command. This upgrades residents spawned with a 60-second auto-shutdown timer (from `create` operations) to the standard 12-minute interactive timeout. ## Implementing the Busy-Connect Policy Both SDKs implement identical connection resilience logic defined in the CLI core. The resident process may temporarily refuse connections during initialization or heavy operations, requiring a backoff strategy. The connection policy uses two constants: - **`_BUSY_CONNECT_TIMEOUT`**: 30 seconds maximum wait time - **`_BUSY_MAX_RETRIES`**: 3 connection attempts As found in [`officecli.py`](https://github.com/iOfficeAI/OfficeCLI/blob/main/officecli.py) lines 59-61 and the C# `ResidentClient.TrySend` method (lines 59-84), retries only occur during the connect phase. Once a command transmits across the pipe, the SDK establishes **at-most-once** semantics—disconnecting after transmission does not trigger a retry, preventing duplicate mutations. ## Practical Integration Examples The following patterns demonstrate production-ready usage of both SDKs. ### Python SDK Implementation The Python wrapper provides context managers for automatic resident lifecycle management: ```python import officecli # Create forces a new resident (with 60s idle timeout) with officecli.create("report.xlsx", "--force") as doc: # Write data using the set command doc.send({ "Command": "set", "Path": "/Sheet1/A1", "Props": {"text": "Revenue"} }) # Batch multiple operations atomically doc.send({ "Command": "batch", "Args": { "commands": [ {"Command": "set", "Path": "/Sheet1/B1", "Props": {"number": 100000}}, {"Command": "set", "Path": "/Sheet1/C1", "Props": {"formula": "=B1*1.1"}} ] } }) # Retrieve computed value result = doc.send({ "Command": "get", "Path": "/Sheet1/C1" }) print(f"Calculated value: {result['Stdout']}") # Persist to disk doc.send({"Command": "save"}) # Resident terminates automatically on context exit ``` The `create` and `open` helpers internally call `pipe_paths` to resolve the pipe location, then use the `_rpc` helper (around line 52 in [`officecli.py`](https://github.com/iOfficeAI/OfficeCLI/blob/main/officecli.py)) to apply the busy-connect retry logic. ### Node.js SDK Implementation The JavaScript implementation follows an equivalent Promise-based API: ```javascript const officecli = require('officecli'); // Open reuses an existing resident or spawns a new one officecli.open('presentation.pptx') .then(doc => { // Chain multiple operations return doc.batch([ { Command: 'add', Path: '/Slide1', Props: { shape: 'title', text: 'Q3 Results' } }, { Command: 'set', Path: '/Slide1/Title1', Props: { font: 'Arial', size: 44 } } ]); }) .then(doc => doc.send({ Command: 'save' })) .then(() => console.log('Presentation updated successfully')) .catch(err => { // OfficeCliError raised if pipe unavailable console.error('Integration failed:', err); }); ``` The Node SDK ([`index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/index.js) lines 28-38) implements `pipePaths(filePath)` using the same SHA256 truncation logic as Python, ensuring cross-platform consistency. ## Error Handling and Failure Modes The SDKs distinguish between transport failures and application-level errors: - **Transport Errors**: If the named pipe cannot be opened after retries, the Python SDK raises `OfficeCliError`, while the Node SDK returns a rejected Promise. These indicate the resident is not running or the path hash mismatch. - **Command Failures**: Non-zero exit codes from Office operations (e.g., invalid cell references) return through the response envelope fields `Stdout`, `Stderr`, and `ExitCode`. The SDKs do not throw exceptions for business logic failures, requiring explicit checking of the `ExitCode` field. When integrating with long-running applications, implement heartbeat monitoring using the ping pipe to detect resident crashes before issuing expensive batch operations. ## Summary - **Pipe Naming**: SDKs generate pipe names using `officecli-` (uppercase) after platform-specific path canonicalization, found in [`officecli.py`](https://github.com/iOfficeAI/OfficeCLI/blob/main/officecli.py) and [`index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/index.js). - **Dual Pipe Design**: Main pipe handles document commands; `-ping` pipe manages health checks and idle-timeout upgrades via `__ping__` and `__set-idle-timeout__` commands. - **Protocol Format**: Single-line JSON over UTF-8 with `\n` termination, supporting any OfficeCLI command through unified `Command`/`Args`/`Props` envelopes. - **Resilience**: 30-second timeout with 3 retries during connection phase only, providing at-most-once delivery semantics as implemented in [`ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentClient.cs). - **Auto-Lifecycle**: Context managers (Python) and Promise chains (Node) handle resident startup and shutdown automatically. ## Frequently Asked Questions ### How do I debug connection failures between my script and the OfficeCLI resident? Verify the pipe name generation matches on both sides by checking the temporary directory for `CoreFxPipe_` (Unix) or using PipeList (Windows). The hash must derive from the identical canonical path. If paths differ due to symlinks, ensure both SDK and resident use `realpath` resolution before hashing, as implemented in [`officecli.py`](https://github.com/iOfficeAI/OfficeCLI/blob/main/officecli.py) lines 28-38. ### Can I use the named pipe protocol from languages other than Python or Node.js? Yes. Any language capable of opening named pipes (Windows) or Unix-domain sockets can implement the protocol. Follow the naming convention in `pipe_paths`, connect with a 30-second timeout, and send single-line JSON requests terminated by `\n`. The response format mirrors the request exactly—JSON terminated by newline. ### Why does the resident shut down after 60 seconds when I use `create` versus `open`? The `create` command spawns residents with a defensive 60-second idle timeout to prevent resource leaks from abandoned processes. When you subsequently call `open` or any SDK method that triggers `SendSetIdleTimeout`, it sends `__set-idle-timeout__` to the ping pipe, upgrading the resident to the standard 12-minute interactive timeout suitable for actual development work. ### What is the difference between `send()` and `batch()` in the SDKs? `send()` transmits a single command and waits for the JSON response, suitable for dependent operations where later steps require previous results. `batch()` sends multiple commands in one request, reducing IPC overhead for independent operations. Both use the same underlying `_rpc` (Python) or `_busyConnect` (Node) transport logic defined in the respective SDK files.