How to Get Started with OfficeCLI: Installation, Architecture, and First Commands

OfficeCLI is a self-contained, cross-platform command-line tool that enables AI agents and developers to create, read, and modify Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files without any Microsoft Office installation, using a three-layer architecture that ranges from high-level semantic views to direct OOXML manipulation.

Getting started with OfficeCLI requires understanding its dual nature as both a standalone binary for humans and an MCP (Model Context Protocol) server for AI agents. The tool embeds a .NET runtime and custom rendering engine, allowing all document processing to happen locally. According to the iOfficeAI/OfficeCLI repository, the binary parses OOXML packages, performs mutations, and optionally generates HTML or PNG previews within a single process.

Installation Methods

OfficeCLI supports multiple installation paths depending on your environment.

One-line installer (Linux/macOS):

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

Package managers:

• npm: npm install -g officecli (wraps the binary via [npm/officecli.js](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/officecli.js))
• Homebrew: brew install officecli (if available in your tap)
• Scoop: scoop install officecli (Windows)

AI Agent Setup:

For AI agents (Claude Code, Cursor, Copilot), the tool provides a skill file that auto-installs the binary and registers the MCP server. Agents can execute the skill installation directly from the repository's [SKILL.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md), which handles binary detection and configuration in one step.

Understanding the Three-Layer Architecture

OfficeCLI organizes functionality into three distinct layers, each exposed through specific commands.

L1 – Read Layer: High-level semantic views including outlines, text extractions, HTML rendering, and screenshots. Use commands like view ... html, view ... outline, and watch to access this layer.

L2 – DOM Layer: Structured element operations for adding, setting, removing, and moving document components. Commands include add, set, remove, and query, manipulating elements like slides, shapes, paragraphs, and cells.

L3 – Raw XML Layer: Direct OOXML manipulation when the DOM layer is insufficient. Access via raw, raw-set, and add-part commands for precise XML node editing.

Core Commands for Document Manipulation

Creating Documents

Initialize new Office documents using the create command:

# Create a blank PowerPoint presentation

officecli create deck.pptx

# Create a Word document

officecli create report.docx

Adding Content with DOM Operations

Use the add command with property flags to insert structured elements. This operates at the L2 DOM layer:

# Add a slide with a title

officecli add deck.pptx / --type slide --prop title="Q4 Report"

# Add a textbox shape to the first slide

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

Viewing and Watching Documents

Static viewing generates high-fidelity HTML representations:

officecli view deck.pptx html

Live preview leverages the SSE (Server-Sent Events) engine implemented in [src/officecli/Resources/watch-sse-core.js](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Resources/watch-sse-core.js) to provide real-time updates:

officecli watch deck.pptx

This launches a local HTTP server (default http://localhost:26315) that auto-refreshes whenever you run add, set, or remove commands in another terminal.

Structured Data Access

Retrieve specific elements as JSON for programmatic processing:

officecli get deck.pptx '/slide[1]/shape[1]' --json

Adding --json to any command returns deterministic JSON structures, making error handling and result parsing straightforward for automation scripts.

AI Integration and MCP Server

OfficeCLI exposes every command over JSON-RPC via an integrated MCP server, allowing AI-powered IDEs to invoke the CLI as native tools. The [SKILL.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) file defines the server's capabilities and installation hooks.

When running in resident mode, officecli open <file> keeps documents in memory for ultra-low-latency edits, while close flushes changes to disk. This mode is particularly effective for AI agents performing multiple rapid operations.

Key Source Files and Implementation Details

Understanding the codebase helps when extending or debugging OfficeCLI:

• [src/officecli/Resources/watch-sse-core.js](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Resources/watch-sse-core.js): Implements the Server-Sent Events engine that powers the watch command's live preview functionality.

• [sdk/node/index.js](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js): Official Node.js SDK that spawns the binary and exposes a thin pipe-based API for JavaScript/TypeScript integrations.

• [npm/officecli.js](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/officecli.js): Entry point for the global npm package, handling binary path resolution and platform detection.

• [README.md](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md): Contains the complete command reference, installation instructions, and architecture documentation.

Summary

• OfficeCLI requires no Microsoft Office installation and embeds its own .NET runtime for local processing.
• The three-layer architecture (Read, DOM, Raw XML) allows progressive complexity from simple viewing to precise XML manipulation.
• Installation works via curl, npm, Homebrew, or Scoop, with AI agents using the SKILL.md file for auto-configuration.
• Key commands include create for initialization, add/set for DOM manipulation, and watch for live previews on port 26315.
• AI integration happens through the MCP server defined in SKILL.md, enabling JSON-RPC access from modern IDEs.

Frequently Asked Questions

Do I need Microsoft Office installed to use OfficeCLI?

No. OfficeCLI is completely self-contained and embeds a .NET runtime along with a custom rendering engine. All document parsing, modification, and HTML/PNG generation happen locally without any dependency on Microsoft Office or LibreOffice installations.

How does the live preview feature work?

The watch command launches a local HTTP server (defaulting to port 26315) that uses Server-Sent Events (SSE) to push updates to your browser. The implementation in [watch-sse-core.js](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Resources/watch-sse-core.js) monitors document state changes caused by concurrent add, set, or remove commands and automatically refreshes the preview without requiring manual reloads.

Can I use OfficeCLI programmatically from Node.js?

Yes. The [sdk/node/index.js](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js) file provides an official Node.js SDK that spawns the OfficeCLI binary and exposes a pipe-based API. You can also install the officecli npm package, which wraps the binary via [npm/officecli.js](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/officecli.js), allowing you to import and call commands from within JavaScript or TypeScript applications.

What is the difference between the DOM layer and Raw XML layer?

The DOM layer (Layer 2) provides high-level abstractions for common operations like adding slides, shapes, or paragraphs using semantic commands such as add and set. The Raw XML layer (Layer 3) grants direct access to the OOXML package internals through commands like raw and raw-set, necessary when you need to manipulate document elements that the DOM layer does not yet expose or when performing precise XML attribute modifications.

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