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

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 before executing commands like open() or create().

The Binary Resolution Chain

The core logic resides in the ensureCliBinary function within 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 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 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 at lines 76-88, with the underlying download helper located in 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 (Unix) or install.ps1 (Windows) scripts, exposed through 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 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:

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:

(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:

(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 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 or install.ps1 scripts from 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}