# How the OfficeCLI Auto-Update Mechanism Works in the Node.js SDK

> Discover how the OfficeCLI auto-update mechanism in the Node.js SDK automatically checks, validates, and downloads the latest signed binary ensuring your tool is always current.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: internals
- Published: 2026-07-13

---

**The OfficeCLI SDK automatically keeps the `officecli` binary up-to-date by checking for a bundled version, validating it with `probeVersion()`, and downloading the latest signed binary from official mirrors if no working binary exists.**

The OfficeCLI auto-update mechanism ensures that developers always execute the latest version of the `officecli` binary without manual intervention. Implemented in the `iOfficeAI/OfficeCLI` repository, this system resolves the correct binary through a deterministic chain of checks defined in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) before executing commands like `open()` or `create()`.

## The Binary Resolution Chain

The core logic resides in the `ensureCliBinary` function within [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js). This orchestrates a four-stage resolution process that guarantees a working binary is available before any Office document operation begins.

### Bundled Binary Detection

First, the SDK attempts to locate a bundled binary via the `bundledBinary()` helper. This function tries to `require('@officecli/officecli')` and calls `cli.binaryPath()` to retrieve the path. If the file exists at the returned path, the SDK considers it a candidate for validation.

This logic is implemented in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) at lines 309-321.

### Version Probing and Validation

Before accepting any binary, `probeVersion()` executes `<binary> --version` to verify functionality. Only binaries that exit with code 0 are accepted; broken or corrupted installations are rejected and ignored.

This verification occurs in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) at lines 334-342.

### Auto-Install from Bundled Package

When no usable binary exists and `autoInstall` is **true** (the default), the SDK triggers the bundled installer package. It calls `cli.ensureBinary()` which contacts the official mirror at `https://d.officecli.ai/` to download the latest signed binary. The binary is written to the user's local install directory: `~/.local/bin` on Unix systems or `%LOCALAPPDATA%\OfficeCLI` on Windows.

This download logic is handled in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) at lines 76-88, with the underlying download helper located in [`npm/lib/install-binary.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/lib/install-binary.js).

### Official Installer Fallback

If the bundled package is missing or its download fails, the SDK falls back to classic installer scripts. These [`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) (Unix) or `install.ps1` (Windows) scripts, exposed through [`npm/install.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/install.js), fetch the newest binary from the same official mirrors, ensuring the SDK can recover even when the npm package is unavailable.

This fallback mechanism is defined in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) at lines 126-138.

## Controlling Auto-Update Behavior

Developers can configure how the SDK handles binary resolution through options passed to `open()` or `create()`.

### Default Auto-Install (Recommended)

Allow the SDK to automatically download and update the binary:

```javascript
const oc = require('@officecli/sdk');

// First call will download the latest binary if not present
(async () => {
  const doc = await oc.create('report.xlsx');   // auto-installs binary if needed
  await doc.send({ command: 'set', path: '/Sheet1/A1', props: { text: 'Hello' } });
  await doc.close();                             // shuts down resident
})();

```

### Disable Auto-Install

Prevent automatic downloads and use only pre-installed binaries:

```javascript
(async () => {
  // Throws OfficeCliError if the binary cannot be found / is not functional
  const doc = await oc.open('existing.xlsx', { autoInstall: false });
  console.log(await doc.send({ command: 'get', path: '/Sheet1/A1' }));
})();

```

### Custom Binary Path

Bypass the entire auto-update mechanism by specifying a custom binary:

```javascript
(async () => {
  const customPath = '/opt/officecli/officecli'; // your own managed binary
  const doc = await oc.open('file.docx', { binary: customPath });
  await doc.batch([
    { command: 'set', path: '/Sheet1/B2', props: { text: 'Row 2' } },
    { command: 'set', path: '/Sheet1/C3', props: { text: 'Row 3' } }
  ]);
})();

```

## Summary

- The **OfficeCLI auto-update mechanism** operates through a deterministic resolution chain in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) that prioritizes bundled binaries before attempting downloads.
- **Validation is mandatory**: Every binary must pass `probeVersion()` (exit code 0) to be accepted, preventing the use of corrupted installations.
- **Automatic downloads** occur via `cli.ensureBinary()` from official mirrors only when `autoInstall` is enabled (default) and no working binary exists.
- **Fallback resilience**: If the bundled npm package (`@officecli/officecli`) fails, the SDK executes [`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) or `install.ps1` scripts from [`npm/install.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/install.js) to guarantee binary availability.
- **Explicit updates**: The mechanism only replaces missing or broken binaries, never silently overwriting working versions.

## Frequently Asked Questions

### Where does OfficeCLI store the downloaded binary?

The SDK writes the `officecli` binary to platform-specific local directories: `~/.local/bin` on Unix-based systems and `%LOCALAPPDATA%\OfficeCLI` on Windows. These paths are standard user-local installation directories that do not require system-wide permissions.

### Can I prevent OfficeCLI from automatically downloading binaries?

Yes. Pass `{ autoInstall: false }` when calling `open()` or `create()`. This disables the auto-update mechanism and forces the SDK to use only existing binaries. If no valid binary is found, the SDK throws an `OfficeCliError` rather than downloading anything.

### How does OfficeCLI verify that a binary is valid before using it?

The SDK runs `probeVersion()` which executes `<binary> --version` and checks for exit code 0. This verification happens in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) and ensures that only functional binaries are used; corrupted or incompatible binaries are rejected and replaced.

### What happens if the bundled @officecli/officecli package is not installed?

If the bundled package is missing or `cli.ensureBinary()` fails, the SDK falls back to executing official installer scripts ([`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) on Unix or `install.ps1` on Windows). These scripts download the latest binary directly from the official mirrors, providing a secondary installation path independent of the npm package.