How to Use OfficeCLI for Automating Word Tasks: Complete Command Reference

OfficeCLI is a single-binary, headless command-line tool that enables AI agents and scripts to create, modify, and render Microsoft Word documents without installing Microsoft Office, using a three-layer architecture from semantic views down to raw XML editing.

OfficeCLI from the iOfficeAI/OfficeCLI repository provides a path-based API for automating Word document generation and modification. Unlike traditional COM automation that requires a full Office installation, this .NET-based CLI operates entirely headless, making it ideal for CI pipelines, Docker containers, and AI-driven workflows. The tool exposes Word functionality through stable document paths like /body/p[2]/r[1], allowing precise manipulation of paragraphs, tables, styles, and templates.

Understanding the Three-Layer Architecture

OfficeCLI organizes Word automation capabilities into three distinct abstraction layers, letting you choose the appropriate level of control for each task.

L1 Read: Semantic Document Views

The L1 Read layer provides high-level semantic views that return structured data without requiring OOXML parsing knowledge. According to the source design documented in README.md, this layer implements commands like view … outline|text|html|issues that return plain text, annotated outlines, or rendered HTML/PNG previews. These views give automation scripts "eyes" on the document content without handling raw XML.

L2 DOM: Element-Level Operations

The L2 DOM layer handles element-level interactions through stable document paths. As implemented in the command reference, operations include get, query, set, add, remove, move, and swap. Paths follow XPath-like syntax such as /body/p[3]/r[1] (paragraph 3, run 1) and remain stable across edits. The CLI automatically validates property names and provides suggestions for typos, making this the primary interface for Word automation scripts.

L3 Raw XML: Direct OpenXML Editing

The L3 Raw XML layer provides fallback access through XPath-based commands raw and raw-set. This handles edge cases where the DOM abstraction cannot express needed changes. Because OfficeCLI targets the OpenXML format directly, any raw XML modifications remain compatible with Microsoft Word.

Essential Word Automation Commands

OfficeCLI implements the full Word specification including RTL scripts, styles, tables, pictures, equations, headers/footers, bookmarks, TOC, and charts. All features are exposed through consistent CLI patterns.

Creating Documents

Use the create command to initialize blank Word documents:

officecli create report.docx

Adding Content with the Add Command

The add command inserts new elements at specified parent paths:

# Add a heading paragraph at root

officecli add report.docx / --type paragraph \
  --prop style=Heading1 \
  --prop text="Quarter 4 Financial Summary"

# Add a normal paragraph after the first paragraph

officecli add report.docx /body/p[1] --type paragraph \
  --prop text="The Q4 results exceed expectations..."

Modifying Properties with Set

The set command updates existing elements using precise paths:

# Change font properties of the second paragraph's first run

officecli set report.docx /body/p[2]/r[1] \
  --prop font=Arial \
  --prop size=12pt \
  --prop color="#333333"

Working with Tables

Insert and populate tables using the same path-based approach:

# Insert a 3×3 table after the second paragraph

officecli add report.docx /body/p[2] --type table \
  --prop rows=3 \
  --prop cols=3

# Populate the first cell with bold text

officecli set report.docx /body/p[3]/tbl[1]/tr[1]/tc[1]/p[1]/r[1] \
  --prop text="Revenue" \
  --prop bold=true

Template Merging

Merge data into Word templates containing placeholders:

officecli merge invoice-template.docx invoice-001.docx \
  --data '{"client":"Acme Corp","total":"$12,340"}'

Validation and Inspection

Validate document integrity and inspect formatting issues:

# Render as HTML for visual inspection

officecli view report.docx html -o report.html

# Validate against OpenXML schema

officecli validate report.docx

# List formatting issues (overflow, missing alt text)

officecli view report.docx issues --json

Practical Word Automation Examples

The following complete workflow demonstrates document creation, content insertion, styling, and rendering:

# Create document

officecli create report.docx

# Add styled heading

officecli add report.docx / --type paragraph \
  --prop style=Heading1 \
  --prop text="Quarter 4 Financial Summary"

# Add body paragraph

officecli add report.docx /body/p[1] --type paragraph \
  --prop text="The Q4 results exceed expectations..." \
  --prop font=Arial \
  --prop size=12pt

# Insert table for data

officecli add report.docx /body/p[2] --type table \
  --prop rows=2 \
  --prop cols=2

# Validate final document

officecli validate report.docx

Integrating with Python and Node.js

OfficeCLI provides thin SDKs that open resident pipes to the binary, converting each operation into low-latency JSON RPC calls rather than spawning new processes.

Python SDK Example

Install via pip install officecli-sdk:

import officecli

with officecli.create("report.docx") as doc:
    doc.send({
        "command": "add",
        "parent": "/",
        "type": "paragraph",
        "props": {
            "style": "Heading1",
            "text": "Quarter 4 Financial Summary"
        }
    })
    doc.send({
        "command": "add",
        "parent": "/body/p[1]",
        "type": "paragraph",
        "props": {
            "text": "The Q4 results exceed expectations..."
        }
    })
    doc.send({
        "command": "set",
        "path": "/body/p[2]/r[1]",
        "props": {
            "font": "Arial",
            "size": "12pt",
            "color": "#333333"
        }
    })

Node.js SDK

Install via npm install @officecli/sdk. The wrapper file npm/officecli.js handles binary downloads and command forwarding.

Key Source Files for Word Automation

The following files from the iOfficeAI/OfficeCLI repository constitute the core Word automation implementation:

• src/officecli/officecli.csproj — The .NET project definition that builds the self-contained binary containing the Word automation engine.
• npm/officecli.js — Node.js wrapper that downloads the native binary and forwards commands to the CLI.
• examples/word/document-formatting.py — Python demonstration showing paragraph addition, table insertion, and style manipulation via the CLI.
• examples/word/textbox.py — Python demonstration for inserting and styling text boxes (shapes) in Word documents.
• README.md — Central documentation covering quick-start guides, the three-layer architecture, and complete command reference.

Detailed per-feature references are maintained in the project Wiki:

• Paragraphs: word-paragraph wiki page
• Tables: word-table wiki page
• Styles: word-style wiki page

Summary

• OfficeCLI provides headless Word automation without Microsoft Office installation, packaged as a single self-contained binary.
• The three-layer architecture (L1 Read, L2 DOM, L3 Raw XML) allows automation scripts to operate at the appropriate abstraction level, from semantic views down to direct XML manipulation.
• Path-based addressing (/body/p[2]/r[1]) provides stable references to document elements that persist across edits.
• Built-in rendering (view html, view screenshot, watch) enables visual verification in CI pipelines and headless environments.
• SDK support for Python (officecli-sdk) and Node.js (@officecli/sdk) allows low-latency integration via JSON RPC pipes.

Frequently Asked Questions

What is OfficeCLI and how does it differ from traditional Word automation?

OfficeCLI is a command-line interface for creating and modifying Word documents that operates independently of the Microsoft Office suite. Traditional automation relies on COM interop or VBA requiring installed Office applications, whereas OfficeCLI parses and generates OpenXML directly using its own rendering engine. This makes it suitable for server environments, Docker containers, and AI agent workflows where Office cannot be installed.

Can OfficeCLI run in CI/CD pipelines or containers?

Yes. Because the tool compiles to a self-contained binary defined in src/officecli/officecli.csproj with no external dependencies on Microsoft Office, it runs in any Linux, Windows, or macOS container. The headless rendering capabilities (view html, view screenshot) allow automated visual regression testing without GUI availability.

How does Word template merging work with OfficeCLI?

The merge command combines a Word template containing placeholder markers (like {{key}}) with JSON data to produce populated documents. For example, officecli merge template.docx output.docx --data '{"client":"Acme"}' replaces all instances of {{client}} with "Acme" while preserving formatting, styles, and document structure from the original template.

What programming languages can integrate with OfficeCLI?

Any language capable of executing shell commands can use OfficeCLI directly. Additionally, official SDKs provide optimized integration for Python (pip install officecli-sdk) and Node.js (npm install @officecli/sdk). These SDKs maintain persistent pipes to the binary, eliminating process spawn overhead and enabling high-throughput document generation workflows.

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