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

> Get started with OfficeCLI, a cross-platform tool for manipulating Office files without installation. Learn its architecture and run your first commands easily.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: getting-started
- Published: 2026-07-15

---

**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](https://github.com/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):**

```bash
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)](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)](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:

```bash

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

```bash

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

```bash
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)](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Resources/watch-sse-core.js) to provide real-time updates:

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

```bash
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)](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)](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)](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)](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)](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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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/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)](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)](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.