# How to Run the OfficeCLI Tool Locally: Complete Installation Guide

> Easily run OfficeCLI locally with a simple install script. Get a native binary for your system and start creating editing and viewing Word Excel and PowerPoint documents instantly.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-07-26

---

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

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs) ([lines 21-24](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs#L21-L24)).

### Windows PowerShell Install

For Windows environments, use the PowerShell one-liner:

```powershell
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](https://github.com/iOfficeAI/OfficeCLI/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:

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs), or [`PptHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash
officecli create deck.pptx

```

The tool detects the file extension and invokes the appropriate handler in [`src/officecli/Handlers/PowerPoint/PptHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/PowerPoint/PptHandler.cs).

### Add Content Programmatically

Add a slide with a title to the document root:

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

```

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

```bash
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:

```bash
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:

```bash
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:

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

```

Where [`updates.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/updates.json) contains:

```json
[
  { "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:

```bash
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs), and [`PptHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Program.cs) ([lines 21-24](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs#L21-L24)), 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Program.cs).

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

The resident server implemented in [`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.