How to Install OfficeCLI Using npm: Complete Setup Guide

Install OfficeCLI globally by running npm install -g @officecli/officecli, which automatically downloads the appropriate native binary for your platform during the postinstall phase.

OfficeCLI is a command-line interface distributed by the iOfficeAI/OfficeCLI repository as the npm package @officecli/officecli. The installation process handles platform detection and binary management automatically, making it available as the officecli command in your terminal.

Quick Installation via npm

You can install OfficeCLI using npm in two ways: globally for permanent access or temporarily via npx.

Global Installation

The recommended approach installs the CLI permanently and adds it to your system PATH:

npm install -g @officecli/officecli

Running Without Installation

To execute OfficeCLI without installing it globally, use npx:

npx @officecli/officecli --help

How the npm Installation Works

The @officecli/officecli package is not pure JavaScript; it contains a thin wrapper that downloads the native binary for your operating system during installation. According to the iOfficeAI/OfficeCLI source code, this process is orchestrated through several key files in the npm/ directory.

When you run npm install, the postinstall hook defined in npm/package.json executes npm/install.js. This script invokes npm/lib/install-binary.js, which performs the following steps:

1. Detects your current platform and CPU architecture (macOS, Linux glibc/musl, or Windows).
2. Downloads the appropriate binary from the official mirror at https://d.officecli.ai, with fallback to GitHub releases if needed.
3. Verifies the download integrity against the published SHA256SUMS file.

The npm/officecli.js file serves as the executable shim that forwards CLI arguments to the downloaded native binary.

Typical output after installation shows the automatic binary fetching:

> npm install -g @officecli/officecli
...
Downloading OfficeCLI binary for linux x64...
Verifying SHA256 checksum… OK
Installation complete. Use the `officecli` command.

Skipping the Binary Download During Installation

If you prefer to defer the binary download, set the OFFICECLI_SKIP_BINARY_DOWNLOAD environment variable before installing:

export OFFICECLI_SKIP_BINARY_DOWNLOAD=1
npm install -g @officecli/officecli

With this setting, the binary will be fetched lazily the first time you invoke the officecli command:

officecli --help
Downloading OfficeCLI binary for linux x64...

Verifying Your Installation

After installation, confirm that OfficeCLI is available and the binary was downloaded correctly:

officecli --version

You should see version information without any "binary not found" errors, indicating that the npm/lib/install-binary.js script successfully placed the executable in the package directory.

Summary

• Install globally with npm install -g @officecli/officecli to add the officecli command to your PATH.
• The installation triggers a postinstall script in npm/package.json that runs npm/install.js and npm/lib/install-binary.js to download platform-specific binaries.
• Downloads are automatically verified against SHA256SUMS and sourced from https://d.officecli.ai with GitHub fallback.
• Set OFFICECLI_SKIP_BINARY_DOWNLOAD=1 to defer binary downloads until first runtime.
• Use npx @officecli/officecli for temporary execution without global installation.

Frequently Asked Questions

What npm package name should I use to install OfficeCLI?

The official package is @officecli/officecli. Install it using npm install -g @officecli/officecli to get the command-line interface with automatic binary management.

Why does npm install OfficeCLI trigger a binary download?

OfficeCLI is distributed as a platform-specific binary rather than pure JavaScript. The postinstall hook in npm/package.json runs npm/install.js, which downloads the correct binary for your operating system (macOS, Linux, or Windows) and verifies its integrity using SHA256 checksums.

Can I install OfficeCLI without downloading the binary immediately?

Yes. Set the environment variable OFFICECLI_SKIP_BINARY_DOWNLOAD=1 before running npm install. The binary will then be downloaded on-demand the first time you execute the officecli command, handled by the logic in npm/lib/install-binary.js.

How do I verify that OfficeCLI installed correctly?

Run officecli --version in your terminal. If the binary downloaded successfully during installation (or on first run if you skipped the initial download), you will see the version number. If you encounter errors, check that the postinstall script in npm/package.json executed without network issues.

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