# How to Use OfficeCLI to Manage Office Documents: A Complete Guide to Command-Line Document Automation

> Master OfficeCLI command-line document automation. This guide shows you how to create, read, and modify Word, Excel, and PowerPoint files without Microsoft Office. Automate your documents today!

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

---

**OfficeCLI** is a single-binary, cross-platform command-line tool that enables AI agents and developers to create, read, modify, and render Word, Excel, and PowerPoint files without Microsoft Office installed, using a three-layer architecture of semantic views, DOM operations, and raw XML access.

OfficeCLI provides a programmatic interface for office document management through deterministic JSON outputs and headless rendering capabilities. The tool, maintained in the `iOfficeAI/OfficeCLI` repository, eliminates the need for heavy desktop suites by embedding its own .NET runtime and browser engine for screenshot generation. Whether you are building automated reporting pipelines or enabling AI agents to edit documents, OfficeCLI offers a comprehensive command set for handling `.docx`, `.xlsx`, and `.pptx` formats.

## Installation and Distribution Methods

OfficeCLI ships as a statically linked binary with no external dependencies, making it immediately runnable on macOS, Linux, and Windows.

### Direct Binary Installation

Install the latest version using the official installer script:

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

```

This downloads the platform-specific binary and places it in your system path.

### NPM Wrapper Distribution

For Node.js environments, install via the thin wrapper that handles binary fetching:

```bash
npm i -g @officecli/officecli

```

The wrapper logic resides in [`npm/officecli.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/officecli.js), which automatically retrieves the correct binary for your operating system.

### AI Agent Auto-Configuration

OfficeCLI automatically installs its skill definitions into detected AI coding agents including Claude Code, Cursor, and GitHub Copilot. The tool references [`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) to expose its command surface to agents, enabling immediate usage without manual configuration.

## Three-Layer Architecture for Document Operations

OfficeCLI organizes functionality into three distinct layers that progress from high-level semantic operations to low-level XML manipulation.

### L1 – Semantic Reading Layer

The **Read** layer provides high-level semantic views of documents including text extraction, outline generation, HTML conversion, and PNG screenshots. According to the source code in [`src/officecli/CommandBuilder.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.View.cs), this layer handles sub-commands such as `view html`, `view outline`, `view screenshot`, and `view issues`.

Use this layer when you need to consume document content without manipulating the underlying structure:

```bash

# Generate HTML preview of a presentation

officecli view deck.pptx html

# Export first slide as PNG image

officecli view deck.pptx screenshot --page 1 -o slide1.png

# Check document for structural issues

officecli view report.docx issues --json

```

### L2 – DOM Manipulation Layer

The **DOM** layer enables structured element operations using stable, 1-based **paths** such as `/slide[1]/shape[2]` or `/body/p[1]/r[1]`. As implemented in [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs), this layer supports the verbs `get`, `query`, `set`, `add`, `remove`, `move`, and `swap`.

Path-based addressing ensures that scripts remain stable across document edits that don't affect the targeted element's position:

```bash

# Query all Heading 1 paragraphs in a Word document

officecli query report.docx "paragraph[style=Heading1]" --json

# Update text of the first run in the first paragraph

officecli set report.docx /body/p[1]/r[1] --prop text="Executive Summary"

```

### L3 – Raw XML Layer

When DOM shortcuts prove insufficient, the **Raw XML** layer provides direct OOXML manipulation. The `raw`, `raw-set`, `add-part`, and `validate` commands allow precise modifications to the underlying Open XML structure.

Use this layer for advanced scenarios such as custom namespace handling or manipulation of esoteric document parts not exposed through the DOM abstraction.

## Creating and Initializing Documents

OfficeCLI generates blank documents through [`BlankDocCreator.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/BlankDocCreator.cs), supporting all three major Office formats.

Create a blank PowerPoint presentation:

```bash
officecli create deck.pptx

```

Add a titled slide immediately after creation:

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

```

Add a styled textbox shape with specific positioning:

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

```

## Reading and Querying Document Content

All read operations support deterministic JSON output via the `--json` flag, making them ideal for consumption by scripts and AI agents.

Extract structured content from Excel workbooks:

```bash
officecli get sheet.xlsx /workbook/sheet[1]/cell[2,3] --json

```

Retrieve semantic outlines for rapid content scanning:

```bash
officecli view document.docx outline --json

```

## Modifying Documents with Single and Batch Operations

### Property Mutation

The `set` command, implemented in [`src/officecli/CommandBuilder.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Set.cs), modifies element properties including text, fonts, colors, layout parameters, and chart data. Properties pass via the `--prop` flag:

```bash
officecli set presentation.pptx /slide[1]/shape[1] \
  --prop fill="#FF0000" \
  --prop text="Updated Title"

```

### Batch Processing

Execute multiple mutations atomically using the `batch` command. Create a JSON file describing the operations:

```json
[
  {"op":"set","path":"/slide[1]/shape[1]","props":{"fill":"#FF0000"}},
  {"op":"add","path":"/slide[2]","type":"shape","props":{"text":"Conclusion"}}
]

```

Then apply them in a single pass:

```bash
officecli batch deck.pptx --input updates.json

```

## Template Merging and Data Injection

OfficeCLI implements a merge engine that replaces template placeholders with JSON data. Placeholders use the `{{key}}` syntax.

Merge data into a templated Excel workbook:

```bash
officecli merge template.xlsx filled.xlsx '{"quarter":"Q4","revenue":4200000}'

```

This operation processes the template, substitutes all matching keys, and writes the result to the output file without modifying the source template.

## AI Integration and Development Features

### MCP Server for JSON-RPC

OfficeCLI exposes all operations over JSON-RPC through the `mcp` command, enabling AI-native integration. The Model Context Protocol (MCP) server allows external agents to invoke OfficeCLI functionality programmatically without shell execution.

### Live Preview Server

The `watch` command starts a local HTTP server that auto-refreshes HTML previews on each document change, closing the edit-render-feedback loop entirely on the client side:

```bash
officecli watch document.docx --port 8080

```

### Deterministic JSON Output

Every command supports the `--json` flag for machine-readable output. This determinism ensures that AI agents can parse results reliably, whether checking for errors, reading content, or confirming successful mutations.

## Summary

- **OfficeCLI** is a statically-linked, cross-platform binary requiring no Microsoft Office installation for managing `.docx`, `.xlsx`, and `.pptx` files.
- The **three-layer architecture** (L1 Read, L2 DOM, L3 Raw XML) provides flexibility from semantic views to precise XML manipulation.
- **Path-based addressing** using 1-based indices (e.g., `/slide[1]/shape[2]`) ensures stable scripting across document modifications.
- **Batch operations** and **template merging** enable automated document generation pipelines.
- **JSON-RPC MCP server** and **deterministic JSON output** make the tool natively compatible with AI agents and automated workflows.
- Key source files include [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) (core dispatch), [`src/officecli/CommandBuilder.Add.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Add.cs) (element creation), and [`src/officecli/CommandBuilder.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Set.cs) (property mutation).

## Frequently Asked Questions

### Does OfficeCLI require Microsoft Office or Windows to run?

No. OfficeCLI is a self-contained binary that statically links the .NET runtime and embeds its own rendering engine for HTML-to-PNG conversion. It runs natively on macOS, Linux, and Windows without any Microsoft Office installation or external dependencies.

### How do I address specific elements within a document using OfficeCLI?

OfficeCLI uses **stable paths** with 1-based indexing to address document elements. For example, `/slide[1]/shape[2]` targets the second shape on the first slide of a PowerPoint file, while `/body/p[3]/r[1]` targets the first text run in the third paragraph of a Word document. These paths remain stable even when other parts of the document change.

### Can OfficeCLI handle complex operations like updating charts or handling formulas?

Yes. The **L2 DOM layer** supports modification of charts, tables, equations, and formulas through the `set` command with appropriate `--prop` flags. For complex scenarios not covered by DOM shortcuts, the **L3 Raw XML layer** allows direct OOXML manipulation using `raw-set` and `raw` commands to access any document part.

### What is the best way to integrate OfficeCLI into an automated CI/CD pipeline?

Use the `--json` flag for all operations to ensure deterministic, machine-readable output that pipelines can parse. For multiple changes, use the `batch` command with a JSON input file to apply atomic updates. Additionally, you can start the `mcp` server to expose OfficeCLI functionality via JSON-RPC, eliminating shell invocation overhead in containerized environments.