OfficeCLI Schema for AI Agent Documentation: A Complete Technical Reference

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 and CommandBuilder.Watch.cs, this layer utilizes HtmlPreviewHelper.cs and 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, CommandBuilder.Add.cs, CommandBuilder.Query.cs, and related partial classes. These builders orchestrate format-specific handlers located in src/officecli/Handlers/Word/WordHandler.cs, src/officecli/Handlers/Excel/ExcelHandler.cs, and 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 and RawSet commands. These utilize GenericXmlQuery.cs and 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 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 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 and 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:

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

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:

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, ExcelHandler.cs, 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) and resident pipe mode (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 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 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 for Word documents, src/officecli/Handlers/Excel/ExcelHandler.cs for Excel spreadsheets, and 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 and 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) 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 and 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.

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