How the OfficeCLI Auto-Update Mechanism and Configuration Work

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 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. 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. 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. 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. 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 for Unix or install.ps1 for Windows ▶ source. 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:

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:

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

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: Contains the ensureCliBinary, bundledBinary, and probeVersion functions that orchestrate the resolution and validation logic.
• 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: Handles low-level binary downloads for the bundled installer package (@officecli/officecli).
• 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, 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 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.

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