# OfficeCLI Schema for AI Agent Documentation: A Complete Technical Reference

> Explore the OfficeCLI schema for AI agent documentation. Programmatically control Word, Excel, and PowerPoint without Microsoft Office using its deterministic JSON schema and three tier architecture.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: api-reference
- Published: 2026-07-10

---

**OfficeCLI exposes a deterministic JSON schema and three-tier architecture (Read, DOM, Raw XML) that enables AI agents to programmatically control Word, Excel, and PowerPoint documents without Microsoft Office, complete with MCP server integration and resident pipe communication.**

The iOfficeAI/OfficeCLI repository delivers a self-contained, cross-platform binary designed specifically for AI-native document automation. Its schema provides deterministic interfaces for reading, manipulating, and rendering Office documents through structured JSON outputs and stable path-based addressing. This architecture eliminates the need for GUI automation or Microsoft Office installation while offering AI agents precise control over document elements through programmatic commands.

## Three-Layer Architecture for Document Control

OfficeCLI organizes its functionality into three distinct abstraction layers, each optimized for different AI agent use cases.

### Layer 1: High-Level Read Operations

The **Read layer** provides human-friendly document views including outlines, annotated text, HTML previews, and PNG screenshots. Implemented in [`CommandBuilder.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.View.cs) and [`CommandBuilder.Watch.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Watch.cs), this layer utilizes [`HtmlPreviewHelper.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/HtmlPreviewHelper.cs) and [`HtmlScreenshot.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/HtmlScreenshot.cs) to render documents without opening Microsoft Office. These components generate high-fidelity HTML and screenshots via headless browser rendering, allowing AI agents to "see" document contents programmatically.

### Layer 2: DOM Manipulation

The **DOM layer** handles structured element operations through [`CommandBuilder.Set.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Set.cs), [`CommandBuilder.Add.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Add.cs), [`CommandBuilder.Query.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Query.cs), and related partial classes. These builders orchestrate format-specific handlers located in [`src/officecli/Handlers/Word/WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.cs), [`src/officecli/Handlers/Excel/ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Excel/ExcelHandler.cs), and [`src/officecli/Handlers/PowerPoint/PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/PowerPoint/PowerPointHandler.cs). Each handler manages element-specific parsing, validation, and rendering for native document operations like get, query, set, add, remove, move, and swap.

### Layer 3: Raw XML Access

For edge cases requiring direct document manipulation, the **Raw XML layer** exposes XPath-based operations through [`CommandBuilder.Raw.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Raw.cs) and `RawSet` commands. These utilize [`GenericXmlQuery.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/GenericXmlQuery.cs) and [`XmlTextValidator.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/XmlTextValidator.cs) for low-level XML manipulation, providing escape hatches when high-level DOM operations cannot achieve specific formatting requirements.

## Core Components for AI Integration

### CommandBuilder and Handler Architecture

The entry point at [`src/officecli/Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs) parses CLI arguments and dispatches commands to the **CommandBuilder** system—a fluent builder split into multiple partial classes for maintainability. Each sub-command (`create`, `view`, `add`, `set`, `batch`, `dump`, `merge`, `watch`, `mcp`) maps to concrete handlers that execute format-specific logic. The handler architecture ensures that Word, Excel, and PowerPoint documents receive specialized treatment while maintaining consistent command interfaces across formats.

### MCP Server Implementation

The [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs) file implements the **Model-Context-Protocol (MCP)** JSON-RPC interface, enabling direct integration with AI tools such as Claude Code, Cursor, and VS Code. This server exposes OfficeCLI commands as callable endpoints, allowing AI agents to invoke document operations through standardized JSON-RPC messages rather than shell execution.

### Resident Server and SDK Communication

To eliminate process-spawn overhead, [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) and [`ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentClient.cs) establish an in-process pipe server architecture. This **resident mode** supports the Python (`officecli-sdk`) and Node.js (`@officecli/sdk`) SDKs, which communicate with a long-running binary instance. The SDKs auto-provision the binary when missing and expose the same command set as the CLI through thin .NET wrappers.

## AI-Friendly Schema Design

### Deterministic JSON Output

Every OfficeCLI command supports the `--json` flag, producing stable schemas that enable reliable parsing by large language models (LLMs). Output includes structured error objects with `code` and `suggestion` fields, allowing agents to programmatically detect and respond to document validation issues.

### Path-Based Addressing

The schema implements **stable element paths** such as `/slide[1]/shape[2]` or `/sheet[1]/cell[A1]`, avoiding fragile XPath expressions. This deterministic addressing ensures AI agents can reliably target specific document elements across sessions without fragile coordinate-based or index-based references that might shift during document manipulation.

### Self-Healing Workflows

Built-in validation commands (`validate`, `view issues`) combined with structured error responses enable **self-healing document workflows**. When agents encounter shape overflow errors or formatting inconsistencies, they receive specific error codes and suggestions that drive automated correction loops without human intervention.

## Implementation Examples

### CLI Commands

Install and manipulate documents using the cross-platform binary:

```bash

# Install the binary (one-liner)

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

# Create a new PowerPoint deck

officecli create deck.pptx

# Add a slide with a title

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

# Add a textbox shape to the 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

# Render an interactive HTML preview (agent "sees" the result)

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

# Validate and auto-fix issues

officecli view deck.pptx issues --json | jq .
officecli set deck.pptx '/slide[1]/shape[1]' --prop fontSize=18

```

### Python SDK

Access the resident server through the Python SDK:

```python
from officecli import Doc

with Doc("report.xlsx") as d:
    # Add a new sheet

    d.add("/", type="sheet", name="Q2")
    # Write a formula that auto-calculates

    d.set("/Sheet2/A1", props={"formula": "=SUM(B1:B10)"})
    # Export as JSON for downstream processing

    print(d.get("/", depth=2, json=True))

```

### Node.js SDK

Use the asynchronous JavaScript SDK for document manipulation:

```javascript
import { Doc } from "@officecli/sdk";

await using d = await Doc.open("presentation.pptx");
await d.add("/", { type: "slide", title: "Launch Plan" });
await d.add("/slide[1]", { type: "shape", text: "Goals", x: "1cm", y: "2cm" });
console.log(await d.get("/slide[1]/shape[1]", { json: true }));

```

## Summary

- OfficeCLI implements a **three-layer architecture** (Read, DOM, Raw XML) that provides AI agents with both high-level abstractions and low-level document access.
- The **CommandBuilder** system and format-specific handlers ([`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs), [`PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.cs)) deliver consistent APIs across Microsoft Office formats.
- **Deterministic JSON output** and **path-based addressing** (`/slide[1]/shape[2]`) enable reliable LLM parsing and stable element targeting.
- **MCP server integration** ([`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs)) and **resident pipe mode** ([`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs)) optimize AI tool integration by eliminating process overhead and supporting direct JSON-RPC communication.
- The **SKILL.md** auto-installation mechanism ensures AI agents can immediately discover and utilize OfficeCLI capabilities without manual configuration.

## Frequently Asked Questions

### How does OfficeCLI provide schema documentation for AI agents?

OfficeCLI distributes a [`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SKILL.md) file that automatically installs into known AI tooling configuration directories. This file documents the deterministic JSON schemas, path-based addressing syntax, and available commands. The MCP server implementation in [`McpServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/McpServer.cs) further exposes these capabilities through the Model-Context-Protocol, allowing AI agents to discover and invoke commands via JSON-RPC.

### What file paths does OfficeCLI use to handle different document formats?

Format-specific logic resides in dedicated handler files: [`src/officecli/Handlers/Word/WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.cs) for Word documents, [`src/officecli/Handlers/Excel/ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Excel/ExcelHandler.cs) for Excel spreadsheets, and [`src/officecli/Handlers/PowerPoint/PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/PowerPoint/PowerPointHandler.cs) for PowerPoint presentations. Each handler works with `CommandBuilder` partial classes to implement document-specific operations while maintaining a unified command interface.

### Can AI agents render Office documents without Microsoft Office installed?

Yes. The [`HtmlPreviewHelper.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/HtmlPreviewHelper.cs) and [`HtmlScreenshot.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/HtmlScreenshot.cs) components provide headless rendering capabilities that generate high-fidelity HTML and PNG screenshots. The `view html` and `view screenshot` commands (implemented in [`CommandBuilder.View.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.View.cs)) allow AI agents to capture visual representations of documents without requiring a GUI or Microsoft Office installation.

### How does the resident server improve AI agent performance?

[`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) and [`ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentClient.cs) implement a pipe-based communication protocol that maintains a long-running OfficeCLI process. This eliminates the startup overhead of spawning new processes for each command, which is critical for AI agents performing bulk document operations. The Python and Node.js SDKs leverage this architecture to provide low-latency document manipulation while auto-provisioning the binary when needed.