OfficeCLI: The AI-Native Command-Line Tool for Microsoft Office Automation

OfficeCLI is an open-source, single-binary command-line tool that gives AI agents and developers full programmatic control over Microsoft Office documents without requiring a full Office installation.

OfficeCLI transforms the traditionally heavyweight Office stack into a lightweight, headless, scriptable service. Developed by iOfficeAI and hosted at iOfficeAI/OfficeCLI, this .NET-based utility enables programmatic creation, modification, and rendering of Word, Excel, and PowerPoint files through deterministic JSON interfaces and path-based addressing.

Core Architecture and Design Philosophy

AI-Native Document Manipulation

Unlike traditional Office automation libraries that require COM interop or full Microsoft Office installations, OfficeCLI operates as a self-contained binary with an embedded .NET runtime. In src/officecli/Program.cs, the entry point parses CLI arguments and dispatches operations to the CommandBuilder.cs core dispatcher, which orchestrates high-level operations across document formats.

The tool implements stable, path-based addressing (e.g., /slide[1]/shape[2]) allowing AI agents to navigate complex document structures without parsing raw OOXML. Every command supports the --json flag for deterministic, machine-readable output, eliminating the need for fragile screen-scraping or regex parsing.

Document Lifecycle Engine

OfficeCLI handles the complete document lifecycle through specialized handlers located in src/officecli/Handlers/. The WordHandler.cs implements Word-specific logic including paragraph manipulation, style application, table of contents generation, and PDF export. For Excel operations, src/officecli/Core/Formula/FormulaEvaluator.cs powers over 350 built-in functions with automatic recalculation on write operations, enabling complex spreadsheet automation without Excel installed.

Key Capabilities for Automation

Headless Office Operations

OfficeCLI creates, reads, modifies, validates, and renders .docx, .xlsx, and .pptx files through pure code execution. The CommandBuilder.cs constructs operation pipelines that execute atomically, ensuring document integrity during batch modifications. This headless architecture makes OfficeCLI ideal for CI/CD pipelines, serverless functions, and containerized environments where traditional Office applications cannot run.

High-Fidelity HTML Rendering and Visual Feedback

A critical feature for multimodal AI agents is the built-in rendering engine implemented in src/officecli/Core/HtmlPreviewHelper.cs. This component generates high-fidelity HTML representations and PNG screenshots of Office documents, enabling a render → look → fix automation loop. The officecli view command produces portable HTML outputs, while officecli watch launches a resident server (default port 26315) that auto-refreshes browser previews as documents change.

MCP Server and AI Integration

OfficeCLI exposes all document operations as JSON-RPC tools through the Model Context Protocol (MCP) server implemented in src/officecli/McpServer.cs. This allows AI coding assistants like Claude Code, Cursor, and VS Code extensions to invoke OfficeCLI directly as a tool. The protocol provides structured access to document introspection and modification, effectively turning Office files into queryable data sources for large language models.

Installation and Quick Start

OfficeCLI distributes as a single binary for Linux, macOS, and Windows. Install via curl, Homebrew, Scoop, or npm:

# macOS / Linux installation

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

# Create a new PowerPoint presentation

officecli create deck.pptx

# Add a slide with structured properties

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

# Insert a text shape using path-based addressing

officecli add deck.pptx '/slide[1]' --type shape \
  --prop text="Revenue ↑ 25%" --prop x=2cm --prop y=5cm --prop size=28

# Generate HTML preview for AI visual verification

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

# Start live preview server for iterative development

officecli watch deck.pptx

All commands return structured JSON when invoked with the --json flag, enabling reliable programmatic integration: officecli get deck.pptx /slide[1] --json.

Performance Optimization Architecture

For high-throughput automation scenarios, src/officecli/ResidentServer.cs implements a resident-mode process that keeps documents loaded in memory between operations. This eliminates file I/O overhead and parsing latency during batch edits, providing ultra-low-latency responses for iterative AI agent workflows. The resident server maintains document state until explicitly terminated, making it suitable for long-running automation sessions.

Summary

• OfficeCLI is a single-binary, cross-platform CLI tool for programmatic Office document manipulation without Microsoft Office dependencies.
• It supports Word, Excel, and PowerPoint formats with full create, read, update, and render capabilities.
• Path-based addressing (/slide[1]/shape[2]) and deterministic JSON output make it inherently compatible with AI agent workflows.
• The MCP server (McpServer.cs) enables direct integration with AI coding assistants via JSON-RPC.
• HTML/PNG rendering capabilities (HtmlPreviewHelper.cs) provide visual feedback loops for multimodal automation.
• Resident server mode (ResidentServer.cs) optimizes performance for high-frequency batch operations by keeping documents in memory.

Frequently Asked Questions

What file formats does OfficeCLI support?

OfficeCLI supports the modern Office Open XML formats: Word (.docx), Excel (.xlsx), and PowerPoint (.pptx). The tool handles these formats natively without requiring the Microsoft Office suite, using specialized handlers like WordHandler.cs for document-specific logic and FormulaEvaluator.cs for Excel calculation engines.

How does OfficeCLI differ from traditional Office automation libraries?

Traditional automation typically requires COM interop, full Office installations, or Windows-specific APIs. OfficeCLI operates as a headless, cross-platform binary with an embedded .NET runtime. It uses deterministic JSON interfaces and path-based selectors rather than object models, making it specifically designed for server environments and AI agent consumption where graphical interfaces and heavy dependencies are prohibitive.

What is the Model Context Protocol (MCP) server in OfficeCLI?

The MCP server, implemented in src/officecli/McpServer.cs, exposes OfficeCLI functionality as JSON-RPC tools following the Model Context Protocol specification. This allows AI agents such as Claude Code, Cursor, or custom VS Code extensions to discover and invoke Office document operations directly. Agents can query document structure, modify content, and render previews through standardized tool calls rather than executing shell commands manually.

How does the resident server mode improve performance?

The resident server, controlled via officecli watch and implemented in src/officecli/ResidentServer.cs, keeps Office documents loaded in memory between operations. This eliminates the parse-serialize overhead that typically occurs with CLI invocations, reducing latency from hundreds of milliseconds to near-instantaneous for subsequent commands targeting the same document. This mode is essential for iterative AI workflows requiring rapid feedback loops.

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