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

> Discover OfficeCLI core commands for AI-native document automation. Automate Word, Excel, and PowerPoint document creation, modification, and export with our unified CLI.

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

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.

```bash

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

```bash

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

```bash

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

```bash

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

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.

```bash

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

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/npm/officecli.js)**: The globally-installable Node wrapper that forwards to the native binary
- **[`sdk/node/index.js`](https://github.com/iOfficeAI/OfficeCLI/blob/main/sdk/node/index.js)**: Minimal Node SDK defining the `Doc` class and auto-installing the binary if missing
- **[`README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md)**: Central documentation containing the complete command reference table
- **[`SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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.