How to Run the OfficeCLI Tool Locally: Complete Installation Guide

You can run OfficeCLI locally by executing a one-line install script that downloads the appropriate native binary for your platform, after which the tool auto-configures itself on first execution and enables headless creation, editing, and viewing of Word, Excel, and PowerPoint documents.

OfficeCLI is a single-binary, cross-platform CLI tool from the iOfficeAI/OfficeCLI repository that requires no Microsoft Office installation. Because the binary embeds the .NET runtime, running the OfficeCLI tool locally only requires downloading the executable and allowing its bootstrap mechanism to handle the initial setup.

Install the OfficeCLI Binary Locally

One-Line Install for macOS and Linux

Open your terminal and execute the official install script:

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

This script downloads the platform-specific binary, writes it to ~/.local/bin/officecli, and sets the executable bit. The underlying logic mirrors the auto-install routine found in src/officecli/Program.cs (lines 21-24).

Windows PowerShell Install

For Windows environments, use the PowerShell one-liner:

irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex

Install via Package Managers

Alternatively, install through your preferred package manager:

• Homebrew (macOS/Linux): brew install officecli
• Scoop (Windows): scoop install officecli
• npm (cross-platform): npm install -g @officecli/officecli

The npm package automatically fetches the native binary for your operating system during installation.

Manual Binary Download

Download the exact binary for your architecture from the GitHub Releases page and place it on your $PATH:

Platform	Binary Name
macOS Apple Silicon	officecli-mac-arm64
macOS Intel	officecli-mac-x64
Linux x64	officecli-linux-x64
Linux ARM64	officecli-linux-arm64
Windows x64	officecli-win-x64.exe
Windows ARM64	officecli-win-arm64.exe

Verify the installation by checking the version:

officecli --version

First-Time Execution: The Bootstrap Process

When you run any officecli command for the first time, the bootstrap code in src/officecli/Program.cs performs three critical actions before executing your command:

1. Auto-installation check: The method OfficeCli.Core.Installer.MaybeAutoInstall(args) verifies whether the binary resides in the user's preferred bin directory (~/.local/bin on Unix or %USERPROFILE%\AppData\Local\officecli on Windows). If not, it copies the executable to that location and re-launches the command transparently.

2. Background update check: Unless you set the environment variable OFFICECLI_SKIP_UPDATE=1, the bootstrap invokes OfficeCli.Core.UpdateChecker.CheckInBackground() to check for newer versions asynchronously.

3. Command dispatch: After setup completes, control passes to the CommandBuilder classes under src/officecli/CommandBuilder.*.cs, which parse verbs like create, add, or view and route to the appropriate handler in WordHandler.cs, ExcelHandler.cs, or PptHandler.cs.

This architecture ensures a seamless "just run it" experience even if you initially executed the binary from a temporary download location.

Practical OfficeCLI Commands After Local Setup

Once installed locally, you can execute document automation workflows without any GUI. Below are common operations demonstrating the tool's capabilities.

Create New Documents

Generate an empty PowerPoint deck:

officecli create deck.pptx

The tool detects the file extension and invokes the appropriate handler in src/officecli/Handlers/PowerPoint/PptHandler.cs.

Add Content Programmatically

Add a slide with a title to the document root:

officecli add deck.pptx / --type slide --prop title="Quarterly Review"

Add a text shape to the first slide with specific positioning:

officecli add deck.pptx '/slide[1]' --type shape \
  --prop text="Revenue ↑ 25%" \
  --prop x=2cm --prop y=5cm \
  --prop font=Arial --prop size=24 --prop color=FFFFFF

Coordinates accept flexible units including cm, in, pt, px, or raw EMUs.

View Documents as HTML

Render high-fidelity HTML for browser viewing without Microsoft Office:

officecli view deck.pptx html -o /tmp/deck.html

The built-in rendering engine produces pure HTML with inlined assets, making it suitable for AI agents or CI environments without display servers.

Live Preview with Watch Mode

Start a local development server that refreshes automatically:

officecli watch deck.pptx

This launches an HTTP server (default http://localhost:26315) powered by the same rendering engine. The server updates after each mutating command (add, set, remove).

Batch Process Modifications

Apply multiple changes atomically using a JSON instruction file:

officecli batch sales.xlsx --input updates.json --json

Where updates.json contains:

[
  { "command": "set", "path": "/Sheet1!A1", "props": { "value": "42" } }
]

Batch mode is atomic by default; add --best-effort to preserve partial progress on failure.

Export Document Structure

Dump the complete document blueprint as JSON for templating or version control:

officecli dump report.docx -o blueprint.json

You can replay this JSON later using officecli batch to reproduce the original file exactly.

Configuration and Environment Variables

Control local OfficeCLI behavior through environment variables and the config file at ~/.officecli/config.json:

• OFFICECLI_SKIP_UPDATE=1: Disables the background update check in Program.cs for air-gapped environments.
• OFFICECLI_RESIDENT_FLUSH=each: Forces disk writes after every mutation when using resident mode, ensuring other processes can read the file immediately.
• officecli config <key> <value>: Modifies persistent settings like default render modes or auto-update preferences.

Summary

Running OfficeCLI locally provides a fully headless, cross-platform document automation environment:

• Installation options include one-line shell scripts, package managers (Homebrew, Scoop, npm), or manual binary downloads from GitHub Releases.
• Auto-installation logic in src/officecli/Program.cs handles PATH configuration automatically on first run via MaybeAutoInstall.
• Background updates run automatically unless disabled with OFFICECLI_SKIP_UPDATE=1.
• Core handlers in WordHandler.cs, ExcelHandler.cs, and PptHandler.cs implement verbs like create, add, view, and watch.
• Resident mode and batch processing support high-throughput automation scenarios.

Frequently Asked Questions

How do I verify that OfficeCLI is installed correctly?

Run officecli --version in your terminal. If the binary is not found in your $PATH, invoking officecli triggers the auto-install stub in Program.cs (lines 21-24), which copies the binary to a standard location and re-executes the command.

Can I run OfficeCLI without installing it to my PATH permanently?

Yes. You can execute the binary directly from any directory (e.g., ./officecli-mac-arm64 --version). On the first invocation, the bootstrap logic in src/officecli/Program.cs will offer to copy it to your user's bin directory, but you can decline and continue using the absolute path.

How do I disable automatic updates when running OfficeCLI locally?

Set the environment variable OFFICECLI_SKIP_UPDATE=1 before executing commands. This prevents OfficeCli.Core.UpdateChecker.CheckInBackground() from running during the bootstrap phase defined in Program.cs.

What happens if the watch command fails to bind to port 26315?

The resident server implemented in src/officecli/ResidentServer.cs defaults to port 26315. If this port is occupied, specify an alternative port using the --port flag: officecli watch document.pptx --port 8080. The server exposes the MCP JSON-RPC interface and HTTP preview endpoint on the specified port.

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