# How the OfficeCLI Auto-Update Mechanism Checks for and Applies Updates

> Discover how the OfficeCLI auto-update mechanism ensures your `officecli` binary is always current. Learn about its deterministic resolution chain, binary probing, and fallback to installer scripts.

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

---

**The OfficeCLI SDK automatically keeps the `officecli` binary up-to-date through a deterministic resolution chain in `ensureCliBinary()` that probes bundled binaries, downloads the latest signed release when needed, and falls back to installer scripts only as a last resort.**

The OfficeCLI auto-update mechanism ensures developers always have a working, current binary without manual intervention. According to the iOfficeAI/OfficeCLI source code, this process triggers whenever SDK methods like `open()` or `create()` are called without an explicit binary path. The system prioritizes reliability over silent updates—it only replaces binaries that are missing or broken, never overwriting a functioning version.

## The Five-Stage Resolution Chain

The core logic lives in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js), where `ensureCliBinary()` orchestrates the auto-update flow through five deterministic stages.

### 1. Bundled Binary Detection

The SDK first attempts to load the binary from the bundled installer package `@officecli/officecli`.

- `bundledBinary()` calls `require('@officecli/officecli')` and invokes `cli.binaryPath()` [source](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js#L309-L321)
- If the returned path exists on disk, the SDK proceeds to validation

This stage avoids network calls entirely when the bundled package is present and intact.

### 2. Binary Probing with Version Check

Before any binary is accepted, `probeVersion()` executes a sanity check:

```bash
<binary> --version

```

The implementation in lines 334-342 of [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) verifies that:
- The process exits with code 0
- Output can be parsed as a valid version string

Binaries that fail this probe—whether corrupted, incompatible, or outdated—are discarded immediately.

### 3. Auto-Install via Bundled Package

When no usable binary exists and `autoInstall` remains `true` (the default), the SDK triggers the download workflow:

```javascript
// sdk/node/index.js lines 76-88
await cli.ensureBinary();

```

The bundled package contacts the official mirror at `https://d.officecli.ai/...` and:
- Downloads the latest signed binary for the current platform
- Writes to `~/.local/bin` on Unix systems
- Writes to `%LOCALAPPDATA%\OfficeCLI` on Windows

This is the primary auto-update path in modern SDK deployments.

### 4. Official Installer Fallback

If the bundled package is missing or `ensureBinary()` fails, the SDK falls back to classic installer scripts [source](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js#L126-L138):

- [`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) for Unix-like systems
- `install.ps1` for Windows

These scripts fetch from the same mirror infrastructure, ensuring consistency across installation methods.

### 5. Binary Resolution and Command Dispatch

After successful download, subsequent calls resolve the freshly-installed binary. The original `open()` or `create()` command proceeds with guaranteed compatibility against the latest `officecli` release.

## Controlling Auto-Update Behavior

Developers can customize the mechanism through SDK configuration options.

### Default Auto-Install Behavior

Allow the SDK to manage binaries automatically:

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

// First call downloads 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();
})();

```

### Disable Auto-Install for Air-Gapped Environments

Force the SDK to use only pre-installed binaries:

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

```

### Bypass Auto-Update with Custom Binary Path

Specify an exact binary location to skip all resolution logic:

```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' } }
  ]);
})();

```

## Key Source Files in the Auto-Update System

| File | Role |
|------|------|
| [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) | Core implementation containing `ensureCliBinary()`, `bundledBinary()`, `probeVersion()`, and fallback installer logic |
| [`npm/install.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/install.js) | Exposes `install()` function for SDK fallback scenarios |
| [`npm/lib/install-binary.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/lib/install-binary.js) | Helper for bundled package binary downloads |
| [`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) / `install.ps1` | Official installer scripts for fallback execution |

## Summary

The OfficeCLI auto-update mechanism operates through a carefully ordered resolution chain:

- **Bundled detection first** — avoids network overhead when possible
- **Probe validation** — guarantees binary functionality before use
- **Signed download** — pulls latest release from `d.officecli.ai` mirrors
- **Installer fallback** — preserves functionality when bundled package fails
- **Explicit-only updates** — never silently replaces working binaries

This design balances automation with stability: the SDK stays current without surprising developers with unannounced changes to their toolchain.

## Frequently Asked Questions

### How does OfficeCLI decide whether to auto-update?

The SDK checks for a usable binary on every `open()` or `create()` call without an explicit `binary` option. If `probeVersion()` fails or no binary is found, and `autoInstall` is not disabled, the auto-update triggers. This explicit condition—missing or broken binary only—prevents unexpected replacements.

### Where does OfficeCLI download binaries from?

Downloads originate from `https://d.officecli.ai/...`, the official mirror infrastructure. Both the bundled package's `ensureBinary()` method and the fallback installer scripts fetch from this source, ensuring cryptographic signature verification and version consistency across platforms.

### Can I permanently disable the OfficeCLI auto-update mechanism?

Set `autoInstall: false` in SDK options to reject automatic downloads. For permanent disablement across a project, enforce this option in wrapper code or environment-specific configuration. Note that this requires pre-installing and maintaining the `officecli` binary manually.

### What happens if the bundled package and installer both fail?

The SDK throws `OfficeCliError` with diagnostic details about each attempted resolution stage. The error includes paths probed, mirror URLs contacted, and exit codes from failed installer executions—enabling systematic troubleshooting of network, permission, or compatibility issues.