How to Install OfficeCLI on macOS: Complete Setup Guide

OfficeCLI installs on macOS as a self-contained binary via a one-line curl command, Homebrew, or manual download, requiring no external runtime or Office installation.

The iOfficeAI/OfficeCLI repository distributes a native macOS binary that runs on both Apple Silicon and Intel architectures. Whether you prefer automated scripts or package managers, you can have the CLI running in seconds. This guide covers all installation methods, the underlying mechanics of the installer, and how to verify your setup.

Supported macOS Architectures

OfficeCLI provides separate native binaries for each Mac architecture:

• Apple Silicon (M1/M2/M3): officecli-mac-arm64
• Intel (x86_64): officecli-mac-x64

The official installer automatically detects your architecture using uname -m and selects the correct asset, eliminating manual guesswork.

Installation Methods

One-Line Curl Install (Recommended)

The fastest method uses the official installer script hosted in the repository root. This script handles platform detection, download, checksum verification, and installation to $HOME/.local/bin.

curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash

After execution, verify the installation:

officecli --version

Homebrew Installation

For users who prefer Homebrew, the formula is available in the official tap:

brew install officecli

This method handles dependencies and updates through the Homebrew ecosystem.

Manual Binary Installation

If you operate behind a corporate proxy or need to audit the binary before installation, download the asset directly from GitHub releases:

# Replace vX.Y.Z with the latest release tag

curl -LO https://github.com/iOfficeAI/OfficeCLI/releases/download/vX.Y.Z/officecli-mac-arm64
chmod +x officecli-mac-arm64
mv officecli-mac-arm64 $HOME/.local/bin/officecli

NPM Installation (Cross-Platform Wrapper)

The repository includes an npm/package.json wrapper that fetches the native binary. This is useful if you already manage Node.js tools:

npm install -g @officecli/officecli

The NPM wrapper detects macOS and downloads the appropriate officecli-mac-arm64 or officecli-mac-x64 binary behind the scenes.

How the Install Script Works

The install.sh script in the repository root implements a robust five-stage installation process:

1. Platform Detection: Reads uname -s (returns darwin for macOS) and uname -m (returns arm64 or x86_64) to determine the correct asset name.

2. Version Resolution: The resolve_version function follows GitHub API redirects to identify the latest release tag, constructing a version-pinned URL like .../releases/download/v1.2.3/officecli-mac-arm64.

3. Download with Fallback: The fetch_with_fallback function first attempts to download from the fast CDN mirror (https://d.officecli.ai). If the mirror is unreachable, it automatically falls back to the GitHub releases URL.

4. Integrity Verification: If a SHA256SUMS file exists in the release, the script extracts the expected hash for the specific asset and compares it against the computed SHA-256 of the downloaded binary.

5. Atomic Installation: The script copies the verified binary atomically to $HOME/.local/bin/officecli (creating the directory if necessary), sets executable permissions, and replaces any existing installation safely.

Verification and AI Integration

Once installed, the binary automatically enables the SKILL.md file located in the repository root. This file allows AI agents to discover and invoke OfficeCLI commands once the binary is present in your PATH.

Confirm the CLI is properly exposed by running:

which officecli

# Output: /Users/yourname/.local/bin/officecli

Summary

• Self-contained binary: OfficeCLI requires no Microsoft Office installation or runtime dependencies on macOS.
• Automatic architecture detection: The install.sh script selects officecli-mac-arm64 or officecli-mac-x64 based on uname -m.
• Multiple install paths: Use the curl one-liner for speed, Homebrew for package management, or manual download for air-gapped environments.
• Integrity guaranteed: The installer verifies SHA-256 checksums from SHA256SUMS before copying to $HOME/.local/bin.
• CDN resilient: Downloads use https://d.officecli.ai with automatic GitHub fallback via fetch_with_fallback.

Frequently Asked Questions

Does OfficeCLI require Microsoft Office to be installed?

No. OfficeCLI is a self-contained binary that operates independently of any local Microsoft Office installation, as implemented in the iOfficeAI/OfficeCLI source code. It handles document processing through its own internal engines.

Can I install OfficeCLI on Apple Silicon Macs?

Yes. The install.sh script detects Apple Silicon via uname -m and automatically downloads the officecli-mac-arm64 binary. The same script works identically on Intel Macs, selecting officecli-mac-x64 instead.

How do I update OfficeCLI to the latest version?

Re-run the installation command. The resolve_version function in install.sh always fetches the latest release tag from GitHub, and the script atomically replaces the existing binary in $HOME/.local/bin. Homebrew users can simply run brew upgrade officecli.

What if the CDN mirror is unavailable during installation?

The fetch_with_fallback function in install.sh first attempts to download from https://d.officecli.ai. If that fails, it automatically retries using the direct GitHub releases URL. Manual installation via direct download from the releases page is also available as a fallback.

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