# How the OfficeCLI Auto-Update Mechanism Works: A Deep Dive into the SDK's Binary Resolution Chain

> Discover how the OfficeCLI auto-update mechanism resolves binaries, from bundled packages to official mirrors, ensuring you always have the latest SDK version.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: deep-dive
- Published: 2026-08-03

---

**The OfficeCLI SDK automatically downloads and updates the `officecli` binary through a deterministic resolution chain in `ensureCliBinary`, falling back from bundled packages to official mirrors when needed.**

The OfficeCLI auto-update mechanism ensures developers always have the latest `officecli` binary without manual intervention. This article examines how the **Node.js SDK** resolves, validates, and installs binaries on-demand, based on the `iOfficeAI/OfficeCLI` source code.

## The Binary Resolution Pipeline

Every command that requires the CLI—such as `open()` or `create()`—triggers `ensureCliBinary` in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js). This function implements a strict, ordered resolution chain:

1. Attempt to locate the bundled binary
2. Probe its version to verify functionality
3. Trigger auto-install if missing or broken
4. Fall back to official installer scripts if necessary

### Step 1: Bundled Binary Detection

The `bundledBinary()` function tries to `require('@officecli/officecli')` and calls `cli.binaryPath()` to obtain a path [source](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js#L309-L321).

```javascript
// Simplified logic from sdk/node/index.js lines 309-321
function bundledBinary() {
  try {
    const cli = require('@officecli/officecli');
    const binaryPath = cli.binaryPath();
    if (fs.existsSync(binaryPath)) {
      return binaryPath;
    }
  } catch (e) {
    // Bundled package not available
  }
  return null;
}

```

If the file exists, the SDK proceeds to validation. If not, resolution continues to the next stage.

### Step 2: Binary Probing with `probeVersion`

Before accepting any binary, `probeVersion()` executes `<binary> --version` and verifies exit code 0 [source](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js#L334-L342). This validation step rejects corrupted or incompatible binaries.

```javascript
// From sdk/node/index.js lines 334-342
async function probeVersion(binaryPath) {
  return new Promise((resolve) => {
    const child = spawn(binaryPath, ['--version']);
    child.on('close', (code) => {
      resolve(code === 0); // Only accept clean exits
    });
    child.on('error', () => resolve(false));
  });
}

```

A binary that fails this probe is treated as absent, triggering the auto-install path.

### Step 3: Auto-Install via Bundled Package

When `autoInstall` is enabled (the default) and no valid binary exists, the SDK invokes `cli.ensureBinary()` on the bundled package [source](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js#L76-L88). This method contacts `https://d.officecli.ai/...` and downloads the latest **signed binary** to platform-specific locations:

- **Unix**: `~/.local/bin`
- **Windows**: `%LOCALAPPDATA%\OfficeCLI`

```javascript
// Default usage triggers auto-install automatically
const oc = require('@officecli/sdk');

(async () => {
  // First call 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();
})();

```

### Step 4: Official Installer Fallback

If the bundled package is unavailable or its download fails, the SDK falls back to classic installer scripts [source](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js#L126-L138). These scripts—[`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) for Unix and `install.ps1` for Windows—fetch from the same official mirrors.

This two-tier fallback ensures the SDK can recover even in restricted environments where the npm package structure is modified or corrupted.

## Controlling Auto-Update Behavior

The SDK exposes options to disable or bypass the auto-update mechanism entirely.

### Disable Auto-Install

Pass `autoInstall: false` to require a pre-existing binary. This throws `OfficeCliError` if resolution fails.

```javascript
(async () => {
  const doc = await oc.open('existing.xlsx', { autoInstall: false });
  console.log(await doc.send({ command: 'get', path: '/Sheet1/A1' }));
})();

```

### Use a Custom Binary Path

Provide an explicit `binary` option to skip all resolution logic and use your own managed binary.

```javascript
(async () => {
  const customPath = '/opt/officecli/officecli';
  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 Implementation Files

| File | Role |
|------|------|
| [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) | Core SDK—contains `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 installer |
| [`npm/lib/install-binary.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/lib/install-binary.js) | Helper for downloading binaries in bundled package |
| [`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) / `install.ps1` | Official installer scripts for fallback resolution |

## Summary

- **Default behavior**: Auto-installs missing or broken binaries automatically
- **Resolution order**: Bundled package → version probe → `ensureBinary()` download → official installer scripts
- **Explicit updates**: Only triggers when binary is missing or non-functional; never silently replaces working binaries
- **Override options**: `autoInstall: false` and `binary: 'custom/path'` disable automatic behavior

## Frequently Asked Questions

### Does OfficeCLI auto-update silently in the background?

No. The auto-update mechanism only runs when you call SDK methods like `open()` or `create()`, and only if no valid binary exists. It never replaces a working binary automatically. According to the source code in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js), the `probeVersion()` check ensures existing functional binaries are preserved.

### Where does OfficeCLI download binaries to?

Platform-specific user directories: `~/.local/bin` on Unix systems and `%LOCALAPPDATA%\OfficeCLI` on Windows. These locations avoid permission issues and keep the binary isolated per user, as implemented in the bundled package's `ensureBinary()` method.

### Can I use OfficeCLI without internet access?

Yes, if you pre-install the binary or use the `binary` option to point to a local path. Set `autoInstall: false` to prevent network attempts. The SDK will then only use your specified binary or fail with `OfficeCliError` if unavailable.

### What happens if the bundled npm package is missing?

The SDK falls back to executing [`install.sh`](https://github.com/iOfficeAI/OfficeCLI/blob/main/install.sh) or `install.ps1` directly from the official mirrors. This fallback path in [`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) lines 126-138 ensures the auto-update mechanism remains functional even when npm package structures are corrupted or manually altered.