# How the OfficeCLI Auto-Update Mechanism and Configuration Work

> Learn how the OfficeCLI auto-update mechanism ensures an up-to-date binary. Discover how it resolves packages, validates installations, and downloads the latest release, all configured via runtime options.

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

---

**The OfficeCLI SDK automatically maintains an up-to-date `officecli` binary by resolving bundled packages, validating existing installations through version probing, and downloading the latest signed release from official mirrors when necessary, with behavior controlled via runtime configuration options.**

The iOfficeAI/OfficeCLI repository provides a Node.js SDK that eliminates manual binary management through an intelligent auto-update mechanism. When you invoke methods like `open()` or `create()`, the SDK executes a deterministic resolution chain defined in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) to locate, validate, or install the required binary. This process ensures developers always interact with the latest stable version without requiring static configuration files.

## How the OfficeCLI Auto-Update Mechanism Resolves Binaries

At the heart of the auto-update system lies the **`ensureCliBinary`** function in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js). This orchestrator manages the entire lifecycle of binary discovery, validation, and acquisition through a strict priority chain.

### Bundled Binary Detection via `bundledBinary()`

The resolution process begins with the `bundledBinary()` helper, which attempts to `require('@officecli/officecli')` and invoke `cli.binaryPath()` [▶ source](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js#L309-L321). If the bundled installer package exists and returns a valid filesystem path, the SDK checks for file existence before proceeding to validation.

### Version Validation with `probeVersion()`

Before accepting any binary, the SDK executes **`probeVersion()`** to run `<binary> --version` [▶ source](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js#L334-L342). Only binaries that exit with code 0 are retained; corrupted, outdated, or incompatible binaries trigger the auto-install fallback, ensuring the SDK never attempts to use a broken executable.

## Automatic Download and Installation Flow

When no functional binary exists and the `autoInstall` option remains enabled (the default), the SDK initiates a resilient, multi-tiered download strategy.

### Primary Download via the Bundled Package

The SDK first invokes `cli.ensureBinary()` on the bundled package, which contacts the official mirror at `https://d.officecli.ai/` and writes the signed binary to platform-specific user directories: `~/.local/bin` on Unix systems or `%LOCALAPPDATA%\OfficeCLI` on Windows [▶ source](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js#L76-L88). This download occurs automatically on the first call to `open()` or `create()` if no valid binary is detected.

### Official Installer Script Fallback

If the bundled package is absent or its download fails, the SDK falls back to executing platform-specific installer scripts—[`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) for Unix or `install.ps1` for Windows [▶ source](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js#L126-L138). These scripts perform the same mirror-based acquisition, ensuring the binary becomes available even when the npm package `@officecli/officecli` is corrupted or missing.

## Configuring the OfficeCLI Auto-Update Behavior

Unlike tools that rely on static configuration files, OfficeCLI accepts runtime options that control binary resolution behavior. This design keeps configuration explicit and context-dependent.

### Disabling Automatic Installation

Set `autoInstall: false` to prevent all automatic downloads and restrict operation to pre-installed binaries:

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

// Throws OfficeCliError if binary is missing or non-functional
const doc = await oc.open('existing.xlsx', { autoInstall: false });
console.log(await doc.send({ command: 'get', path: '/Sheet1/A1' }));

```

### Specifying Custom Binary Paths

Bypass the entire auto-update mechanism—including version probing and bundled package checks—by providing an explicit `binary` path:

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

```

### Default Auto-Installation Behavior

Allow the SDK to manage binaries automatically (default behavior):

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

// Automatically downloads latest binary if not present
const doc = await oc.create('report.xlsx');
await doc.send({ command: 'set', path: '/Sheet1/A1', props: { text: 'Hello' } });
await doc.close();

```

## Core Implementation Files

The auto-update mechanism spans several critical files within the iOfficeAI/OfficeCLI repository:

- **[`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js)**: Contains the `ensureCliBinary`, `bundledBinary`, and `probeVersion` functions that orchestrate the resolution and validation logic.
- **[`npm/install.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/install.js)**: Exposes the `install()` function used by the SDK during fallback scenarios when the bundled package cannot complete the download.
- **[`npm/lib/install-binary.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/lib/install-binary.js)**: Handles low-level binary downloads for the bundled installer package (`@officecli/officecli`).
- **[`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) / `install.ps1`**: Shell scripts fetched and executed when the primary bundled package acquisition fails.

## Summary

- **The OfficeCLI auto-update mechanism** resolves binaries through a deterministic chain: bundled package detection → version probing → automatic download → installer fallback.
- **Binary validation** occurs via `probeVersion()` execution in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js), ensuring only functional binaries are utilized.
- **Downloads target** platform-specific local directories from the official mirror `https://d.officecli.ai/`, requiring no system-wide permissions.
- **Configuration is runtime-based**, using the `autoInstall` and `binary` options passed to `open()` or `create()` rather than static configuration files.
- **Resilience** is built through a two-tier download strategy: bundled package first, installer scripts second.

## Frequently Asked Questions

### How do I disable the OfficeCLI auto-update mechanism?

Pass `{ autoInstall: false }` to any SDK method such as `open()` or `create()`. This prevents automatic downloads and restricts operation to existing, pre-installed binaries, throwing `OfficeCliError` if none are found or if the existing binary fails the version probe.

### Where does OfficeCLI store the downloaded binary?

On Unix systems, binaries are installed to `~/.local/bin`; on Windows, to `%LOCALAPPDATA%\OfficeCLI`. These paths ensure user-level installation without requiring administrative privileges or system-wide configuration changes.

### What happens if the bundled package fails to download the binary?

The SDK falls back to executing official installer scripts ([`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) or `install.ps1`) that perform the same mirror-based download from `https://d.officecli.ai/`. This fallback mechanism ensures binary availability even when the npm package `@officecli/officecli` is missing or corrupted.

### Can I use a specific binary version instead of the auto-updated one?

Yes. Provide the absolute path to your preferred binary using the `binary` option: `{ binary: '/path/to/officecli' }`. This bypasses all auto-update logic, version checking, and bundled package resolution, using your specified executable directly without validation against the official mirror.