Core Commands in OfficeCLI: A Complete Reference for AI-Native Document Automation

OfficeCLI exposes over 20 core commands organized into a three-layer architecture that enables programmatic creation, modification, and export of Word, Excel, and PowerPoint documents via a unified command-line interface.

The iOfficeAI/OfficeCLI repository provides an AI-native automation toolkit for Office documents. Understanding the core commands in OfficeCLI is essential for developers building agentic workflows that manipulate .docx, .xlsx, and .pptx files without Microsoft Office installed. Each command follows the pattern officecli <file> <command> and is documented in the repository's README.md and dedicated Wiki pages.

Document Creation and Validation

The create command generates blank documents based on file extension detection. Use --type to force a specific format or --locale for language-specific defaults.

The validate command checks documents against the OpenXML schema, reporting structural issues before processing. Both commands accept --json for machine-readable output.

# Create a new PowerPoint deck

officecli create deck.pptx

# Validate document structure

officecli validate report.docx --json

Document Inspection: The L1 Read Layer

The view command provides high-level document representations across multiple modes: outline, text, annotated, stats, html, svg, screenshot, pdf, and forms. Control output granularity with --page, --cols, and --max-lines options.

# Export presentation as HTML for inspection

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

# Get text outline of a Word document

officecli view contract.docx outline --max-lines 100

DOM Manipulation: The L2 DOM Layer

This layer provides granular document manipulation through CSS-like selectors and path-based addressing.

get retrieves single elements or subtrees using path-style selectors (e.g., /slide[1]/shape[2]) with --depth limiting recursion.

query executes CSS-like selectors across the entire document, supporting pattern matching with --find and replacement with --replace.

set modifies properties of targeted elements including text content, styling, colors, dimensions, and formulas using --prop key=value syntax.

add inserts new elements (slides, shapes, paragraphs, sheets, rows) or clones existing ones via --from. Specify types with --type and properties with --prop.

remove deletes elements at the specified path.

move relocates elements to new parents using --to, with optional positioning via --index, --after, or --before.

swap exchanges two elements in place.

# Add a slide with title

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

# Insert a textbox with specific formatting

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

# Query shapes containing specific text

officecli query deck.pptx "shape[text~='Revenue']" --json

# Update fill color of first shape on first slide

officecli set deck.pptx '/slide[1]/shape[1]' --prop fill="#FF4444"

# Move shape to after another element

officecli move deck.pptx '/slide[1]/shape[1]' --to '/slide[2]' --after '/slide[2]/shape[1]'

Raw XML Operations: The L3 Raw Layer

For low-level OpenXML access, OfficeCLI provides direct XML manipulation.

raw displays the raw XML of specific document parts using path selectors.

raw-set edits XML via XPath actions (append, replace, delete) using --xpath, --action, and --xml parameters.

# View raw XML of document part

officecli raw document.docx '/word/document.xml'

# Edit XML via XPath

officecli raw-set document.docx --xpath "//w:t" --action replace --xml "<w:t>New Text</w:t>"

Batch Processing and Automation

batch executes command sequences in a single pass via stdin, --input file, or inline --commands. Use --stop-on-error to halt on failures.

dump serializes documents or subtrees to replayable JSON batch files using -o <file>.

merge performs template substitution, replacing {{key}} placeholders with supplied JSON data.

# Dump document to JSON for version control

officecli dump deck.pptx -o deck.json

# Replay batch on fresh file

officecli create fresh.pptx
officecli batch fresh.pptx --input deck.json

# Merge template with data

officecli merge template.docx data.json -o output.docx

Live Preview and AI Integration

watch starts a local HTTP server (default port 26315) that renders documents as HTML or PNG screenshots, auto-refreshing on every mutation. Configure with --port and --theme.

mcp launches a Model-Context-Protocol server enabling AI tools (Claude Code, Cursor, VS Code, LM Studio) to invoke OfficeCLI as JSON-RPC tools. Target specific editors with claude, cursor, vscode, or lmstudio arguments.

According to the SKILL.md file in the repository root, the install command registers these capabilities with AI agents, automatically installing the native binary and configuring the MCP server.

# Start live preview server

officecli watch deck.pptx --port 8080

# Launch MCP server for Claude

officecli mcp claude

Session Management and Configuration

open initiates resident mode, keeping files in memory for ultra-low-latency edits—critical for AI agents performing multiple rapid operations.

close flushes changes to disk and releases the resident session.

install handles binary installation and AI agent registration, with options including all, claude, cursor, or specific IDE targets.

config manages persistent settings such as auto-update behavior and flush modes using key=value syntax.

# Start resident session

officecli open document.pptx --json

# Multiple rapid edits... then close

officecli close document.pptx

Integration Architecture

The command structure is implemented across several key files:

• npm/officecli.js: The globally-installable Node wrapper that forwards to the native binary
• sdk/node/index.js: Minimal Node SDK defining the Doc class and auto-installing the binary if missing
• README.md: Central documentation containing the complete command reference table
• SKILL.md: Machine-readable skill file consumed by AI agents for auto-configuration

All commands support --json output, making OfficeCLI deterministic and parseable for automated workflows.

Summary

• Three-layer architecture: L1 Read (view), L2 DOM (get, query, set, add, remove, move, swap), and L3 Raw XML (raw, raw-set)
• Document lifecycle: create, validate, merge, dump, and batch handle file creation, verification, template processing, and replayable automation
• AI integration: mcp and watch commands enable direct AI tool integration and live preview capabilities
• Performance optimization: open and close manage resident sessions for high-frequency operations
• Universal JSON support: All commands accept --json for machine-readable output, as implemented in the core binary and documented in README.md

Frequently Asked Questions

What file formats does OfficeCLI support?

OfficeCLI natively handles Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files, automatically detecting the format from file extensions. The create command uses extension-based detection, though you can force specific formats using the --type flag.

How does OfficeCLI integrate with AI agents?

According to the SKILL.md file in the repository root, OfficeCLI provides the mcp command to launch a Model-Context-Protocol server, enabling AI tools like Claude Code, Cursor, and VS Code to invoke OfficeCLI as JSON-RPC tools. The install command registers these capabilities, while the --json flag ensures deterministic output for automated parsing.

What is the difference between get and query commands?

The get command retrieves a single element or its subtree using a specific path-style selector (e.g., /slide[1]/shape[2]), while query executes CSS-like selectors across the entire document to find matching elements. Use get for direct addressing when you know the path, and query for searching content or pattern matching.

How do I optimize performance for multiple operations?

Use the open command to start resident mode, which keeps the document in memory and eliminates disk I/O overhead between operations. This is essential for AI agents performing batch modifications. Execute your command sequence, then use close to flush changes to disk and release the session.

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