OfficeCLI

OfficeCLI is the world's first and the best Office suite designed for AI agents.

Give any AI agent full control over Word, Excel, and PowerPoint — in one line of code.

Open-source. Single binary. No Office installation. No dependencies. Works everywhere.

OfficeCLI's built-in HTML rendering engine reproduces documents with high fidelity — and that's what gives AI eyes. It renders .docx / .xlsx / .pptx to HTML or PNG, closing the render → look → fix loop.

![GitHub Release](https://github.com/iOfficeAI/OfficeCLI/releases)
![License](LICENSE)

English | 中文 | 日本語 | 한국어

🌐 Website: <a href="https://officecli.ai" target="_blank">officecli.ai</a>  |  💬 Community: <a href="https://discord.gg/2QAwJn7Egx" target="_blank">Discord</a>

PPT creation process using OfficeCLI on <a href="https://github.com/iOfficeAI/AionUi">AionUi</a>

PowerPoint Presentations

—
Word Documents

—
Excel Spreadsheets

All documents above were created entirely by AI agents using OfficeCLI — no templates, no manual editing.

For AI Agents — Get Started in One Line

Paste this into your AI agent's chat — it will read the skill file and install everything automatically:

text

curl -fsSL https://officecli.ai/SKILL.md

That's it. The skill file teaches the agent how to install the binary and use all commands.

For Humans

Option A — GUI: Install AionUi — a desktop app that lets you create and edit Office documents through natural language, powered by OfficeCLI under the hood. Just describe what you want, and AionUi handles the rest.

Option B — CLI: Download the binary for your platform from GitHub Releases, then run:

bash

officecli install

This copies the binary to your PATH and installs the officecli skill into every AI coding agent it detects — Claude Code, Cursor, Windsurf, GitHub Copilot, and more. Your agent can immediately create, read, and edit Office documents on your behalf, no extra configuration needed.

For Developers — See It Live in 30 Seconds

bash

1. Install (macOS / Linux) — or: brew install officecli / npm install -g @officecli/officecli

curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
Windows (PowerShell): irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
2. Create a blank PowerPoint

officecli create deck.pptx
3. Start live preview — opens http://localhost:26315 in your browser

officecli watch deck.pptx
4. Open another terminal, add a slide — watch the browser update instantly

officecli add deck.pptx / --type slide --prop title="Hello, World!"

That's it. Every add, set, or remove command you run will refresh the preview in real time. Keep experimenting — the browser is your live feedback loop.

Quick Start

bash

Create a presentation and add content

officecli create deck.pptx
officecli add deck.pptx / --type slide --prop title="Q4 Report" --prop background=1A1A2E
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
View as outline

officecli view deck.pptx outline
→ Slide 1: Q4 Report

→   Shape 1 [TextBox]: Revenue grew 25%
View as HTML — opens a rendered preview in your browser, no server needed

officecli view deck.pptx html
Get structured JSON for any element

officecli get deck.pptx '/slide[1]/shape[1]' --json
Save and close — flushes the resident session to disk

officecli close deck.pptx

json

{
  "tag": "shape",
  "path": "/slide[1]/shape[1]",
  "attributes": {
    "name": "TextBox 1",
    "text": "Revenue grew 25%",
    "x": "720000",
    "y": "1800000"
  }
}

Why OfficeCLI?

What used to take 50 lines of Python and 3 separate libraries:

python

from pptx import Presentation
from pptx.util import Inches, Pt
prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[0])
title = slide.shapes.title
title.text = "Q4 Report"
... 45 more lines ...

prs.save('deck.pptx')

Now takes one command:

bash

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

What OfficeCLI can do:

- Create documents from scratch -- blank or with content
- Read text, structure, styles, formulas -- in plain text or structured JSON
- Analyze formatting issues, style inconsistencies, and structural problems
- Modify any element -- text, fonts, colors, layout, formulas, charts, images
- Reorganize content -- add, remove, move, copy elements across documents

| Format | Read | Modify | Create |
|--------|------|--------|--------|
| Word (.docx) | ✅ | ✅ | ✅ |
| Excel (.xlsx) | ✅ | ✅ | ✅ |
| PowerPoint (.pptx) | ✅ | ✅ | ✅ |

Word — full i18n & RTL support (per-script font slots, per-script BCP-47 lang tags lang.latin/ea/cs, complex-script bold/italic/size, direction=rtl cascading through paragraph/run/section/table/style/header/footer/docDefaults, rtlGutter + pgBorders shorthand, locale-aware page numbering for Hindi/Arabic/Thai/CJK; create --locale ar-SA auto-enables RTL), paragraphs (framePr, tabs shorthand, char-based indents), runs (underline.color, position half-pts), tables (virtual column ops add/remove/move/copyfrom, hMerge), styles, textbox / shape (textbox: rotation, textDirection eaVert/vert270, gradient, shadow, opacity), headers/footers, images (PNG/JPG/GIF/SVG), equations (LaTeX input), diagrams (mermaid → native editable shapes, or any mermaid type as a full-fidelity PNG), comments, footnotes, watermarks, bookmarks, TOC, charts, hyperlinks, sections, form fields, content controls (SDT), fields (22 zero-param types + MERGEFIELD / REF / PAGEREF / SEQ / STYLEREF / DOCPROPERTY / IF), OLE objects, revisions / tracked changes (revision.type=ins\|del\|format\|moveFrom\|moveTo + revision.action=accept\|reject, per-target /revision[@author=Alice] selector, tracked Find&Replace), page background color, document properties

Excel — cells (phonetic guide / furigana on add, Excel-UI --shift left\|up on remove / shift=right\|down on add), formulas (350+ built-in functions with auto-evaluation, spilling dynamic arrays with _xlfn. auto-prefix, financial / bond and statistical families, OFFSET/INDIRECT, defined-name formula bodies inlined at parse, formula-ref rewrite on row/col insert), sheets (visible/hidden/veryHidden, print margins, printTitleRows/Cols, RTL sheetView, cascade-aware sheet rename, empty-cell bloat filter on open), boolean and/or selectors (row[Salary>5000 and Region=EMEA]), tables, sort (sheet / range, multi-key, sidecar-aware), conditional formatting, charts (including box-whisker, pareto with auto-sort + cumulative-%, log axis), pivot tables (multi-field, date grouping, showDataAs, sort, grandTotals, subtotals, compact/outline/tabular layout, repeat item labels, blank rows, calculated fields, persistent labelFilter / topN filters, cache CoW + cross-pivot sharing), slicers, named ranges, data validation, images (PNG/JPG/GIF/SVG with dual-representation fallback), sparklines, comments (RTL), autofilter, shapes, OLE objects, CSV/TSV import, $Sheet:A1 cell addressing

PowerPoint — slides (header/footer/date/slidenum toggles, hidden), shapes (pattern fill, blur effect, hyperlink tooltip + slide-jump links, highlight color on runs, slideMaster/slideLayout typed add/set/remove, arrow alias, effective.X + effective.X.src), images (PNG/JPG/GIF/SVG, fill modes: stretch/contain/cover/tile, brightness/contrast/glow/shadow, rotation, link + tooltip), tables (built-in PowerPoint style catalogue, virtual /col[C] get + swap/copyFrom, row/col Move/CopyFrom, fill/background alias), charts (pieOfPie, barOfPie, per-attr axisLine/gridline setters, series add/remove with theme palette, anchor=x,y,w,h shorthand), animations (15 emphasis + 16 exit template-backed presets, multi-effect chains, motion-path presets, repeat/restart/autoReverse, chart animations + chartBuild), transitions (morph + p14 + 12 p15 PowerPoint 2013+ presets), 3D models (.glb) (combined rotation=ax,ay,az), slide zoom, equations (LaTeX input), diagrams (mermaid flowchart / sequence → native editable shapes, or any mermaid type as a full-fidelity PNG), themes, connectors (from/to accept a full /slide[N]/shape[@name=Foo] path), video/audio (loop, autoStart), groups (link + tooltip; Get/Query/Add/Remove all descend into groups), notes (RTL, lang), comments (RTL, legacy + modern p188 threaded round-trip), SmartArt (round-trip via add-part + raw-set), OLE objects, placeholders (add/set by phType)

Use Cases

For Developers:
- Automate report generation from databases or APIs
- Batch-process documents (bulk find/replace, style updates)
- Build document pipelines in CI/CD environments (generate docs from test results)
- Headless Office automation in Docker/containerized environments

For AI Agents:
- Generate presentations from user prompts (see examples above)
- Extract structured data from documents to JSON
- Validate and check document quality before delivery

For Teams:
- Clone document templates and populate with data
- Automated document validation in CI/CD pipelines

Installation

Ships as a single self-contained binary. The .NET runtime is embedded -- nothing to install, no runtime to manage.

One-line install:

bash

macOS / Linux

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

irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex

Or via a package manager:

bash

Homebrew (macOS / Linux)

brew install officecli
Scoop (Windows)

scoop install officecli
npm (all platforms — fetches the native binary for your platform)

npm install -g @officecli/officecli

Or download manually from GitHub Releases:

| Platform | Binary |
|----------|--------|
| macOS Apple Silicon | officecli-mac-arm64 |
| macOS Intel | officecli-mac-x64 |
| Linux x64 | officecli-linux-x64 |
| Linux ARM64 | officecli-linux-arm64 |
| Windows x64 | officecli-win-x64.exe |
| Windows ARM64 | officecli-win-arm64.exe |

Verify installation: officecli --version

Or self-install from a downloaded binary (or run bare officecli to auto-install):

bash

officecli install    # explicit
officecli            # bare invocation also triggers install

Updates are checked automatically in the background. Disable with officecli config autoUpdate false or skip per-invocation with OFFICECLI_SKIP_UPDATE=1. Configuration lives under ~/.officecli/config.json.

Key Features

Built-in Engines & Generation Primitives

OfficeCLI is self-contained. The capabilities below ship inside the binary — no Office required.

#### Rendering engine — high-fidelity, built-in

OfficeCLI's keystone: a from-scratch, high-fidelity HTML rendering engine that lets an AI agent see the rendered document instead of guessing from the DOM. It covers shapes, charts (trendlines, error bars, waterfall, candlestick, sparklines), equations (OMML → LaTeX, rendered with KaTeX), 3D .glb models via Three.js, morph transitions, slide zoom, and shape effects. Per-page PNG screenshots are produced by piping the rendered HTML through a headless browser. Three modes:

- view html — standalone HTML file, assets inlined. Open in any browser.
- view screenshot — per-page PNG, ready for multimodal agents to read.
- watch — local HTTP server with auto-refreshing preview; every add / set / remove updates the browser instantly. Excel watch supports inline cell editing and drag-to-reposition charts.

bash

officecli view deck.pptx html -o /tmp/deck.html
officecli view deck.pptx screenshot -o /tmp/deck.png # add --page 1-N for more slides
officecli watch deck.pptx                            # http://localhost:26315

Without visualization, an agent generating slides is flying blind — it can read the DOM but can't tell if the title overflows or two shapes overlap. Because rendering is built into the binary, the render → look → fix loop works in CI, in Docker, on a server with no display — anywhere the binary runs.

#### Formula & pivot engine

350+ built-in Excel functions evaluated automatically on write — write =SUM(A1:A2), get the cell, the value is already there. No round-trip through Office to recalc. Covers spilling dynamic arrays (FILTER / SORT / UNIQUE / SEQUENCE / LET / LAMBDA / MAP), VLOOKUP / XLOOKUP / INDEX / MATCH, financial & bond math (XIRR / PRICE / YIELD / DURATION / COUPNUM), statistical distributions, tests & regression (NORM.DIST / T.TEST / LINEST), and date & text functions.

Plus native OOXML pivot tables from a source range with one command — multi-field rows/cols/filters, 10 aggregations, showDataAs modes, date grouping, calculated fields, top-N, layouts. Pivot cache + definition are written to OOXML, so Excel opens the file with the aggregation already populated:

bash

officecli add sales.xlsx '/Sheet1' --type pivottable \
  --prop source='Data!A1:E10000' --prop rows='Region,Category' \
  --prop cols=Quarter --prop values='Revenue:sum,Units:avg' \
  --prop showDataAs=percentOfTotal

#### Template merge — generate once, fill many

merge replaces {{key}} placeholders in any .docx / .xlsx / .pptx with JSON data — across paragraphs, table cells, shapes, headers, footers, and chart titles. Agent designs the layout once (expensive); production code fills it N times (cheap, deterministic, zero token cost). Avoids the failure mode where an agent regenerates each report from scratch and produces N inconsistent layouts.

bash

officecli merge invoice-template.docx out-001.docx --data '{"client":"Acme","total":"$5,200"}'
officecli merge q4-template.pptx q4-acme.pptx --data data.json

#### Round-trip dump — learn from existing docs

dump serializes any .docx, .pptx, or .xlsx — whole document or any subtree (a single paragraph, table, slide, worksheet, the styles part, numbering, theme, or settings) — into a replayable batch JSON; batch replays it. Given a sample the user wants to imitate, an agent reads the structured spec instead of raw OOXML XML, mutates, and replays. Bridges "I have an existing template" and "generate me 100 variations."

bash

officecli dump existing.docx -o blueprint.json                  # whole document
officecli dump existing.docx /body/tbl[1] -o table.json         # any subtree
officecli dump existing.xlsx /Sheet1 -o sheet.json              # a single worksheet
officecli batch new.docx --input blueprint.json

Resident Mode & Batch

For multi-step workflows, resident mode keeps the document in memory. Batch mode applies multiple operations in a single pass.

bash

Resident mode — near-zero latency via named pipes

officecli open report.docx
officecli set report.docx /body/p[1]/r[1] --prop bold=true
officecli set report.docx /body/p[2]/r[1] --prop color=FF0000
officecli close report.docx
Batch mode — multi-command execution (atomic by default: any failed item rolls back the whole batch)

echo '[{"command":"set","path":"/slide[1]/shape[1]","props":{"text":"Hello"}},
      {"command":"set","path":"/slide[1]/shape[2]","props":{"fill":"FF0000"}}]' \
  | officecli batch deck.pptx --json
Inline batch with --commands (no stdin needed)

officecli batch deck.pptx --commands '[{"op":"set","path":"/slide[1]/shape[1]","props":{"text":"Hi"}}]'
Keep whatever succeeds even if some items fail (pre-1.0.137 behavior)

officecli batch deck.pptx --input updates.json --best-effort --json
Stop at the first failing command instead of running the rest (still rolls back everything unless combined with --best-effort)

officecli batch deck.pptx --input updates.json --stop-on-error --json

Reading the file with another tool? Flush to disk first.

officecli's own reads (get/query/view) always see your latest edits, so within officecli you never need to save. But a live resident defers the disk write, so before a non‑officecli program reads the file — python‑docx/openpyxl, Microsoft Word, a renderer, delivery/upload — flush it:

``bash


officecli set report.docx /body/p[1] --prop bold=true

officecli save report.docx # flush, keep the resident warm (or close to flush + release)


python my_reader.py report.docx      # now sees the edit

`

A live resident also auto‑flushes shortly after going idle (adaptive 2–10s, scaled to the document's measured save cost). For a pipeline where another program reads after every command, set OFFICECLI_RESIDENT_FLUSH=each — every mutation is on disk before the command returns, while the resident stays warm. Full flush model (each/auto/fixed/off, save / close, env tuning): wiki → open / close.

`Three-Layer Architecture`

Start simple, go deep only when needed.

| Layer | Purpose | Commands | |-------|---------|----------| | L1: Read | Semantic views of content |view(text, annotated, outline, stats, issues, html, svg, screenshot) | | L2: DOM | Structured element operations |get, query, set, add, remove, move, swap| | L3: Raw XML | Direct XPath access — universal fallback |raw, raw-set, add-part, validate |

bash

L1 — high-level views

officecli view report.docx annotated
officecli view budget.xlsx text --cols A,B,C --max-lines 50
L2 — element-level operations

officecli query report.docx "run:contains(TODO)"
officecli add budget.xlsx / --type sheet --prop name="Q2 Report"
officecli move report.docx /body/p[5] --to /body --index 1
L3 — raw XML when L2 isn't enough

officecli raw deck.pptx '/slide[1]'
officecli raw-set report.docx document \
  --xpath "//w:p[1]" --action append \
  --xml '<w:r><w:t>Injected text</w:t></w:r>'

`AI Integration`

`MCP Server`

Built-in MCP server — register with one command:

bash

officecli mcp claude       # Claude Code
officecli mcp cursor       # Cursor
officecli mcp vscode       # VS Code / Copilot
officecli mcp lmstudio     # LM Studio
officecli mcp list         # Check registration status

Exposes all document operations as tools over JSON-RPC — no shell access needed.

`Direct CLI Integration`

Get OfficeCLI working with your AI agent in two steps:

1. Install the binary -- one command (see Installation) 2. Done. OfficeCLI automatically detects your AI tools (Claude Code, GitHub Copilot, Codex) by checking known config directories and installs its skill file. Your agent can immediately create, read, and modify any Office document.

<details> <summary>Manual setup (optional)</summary>

If auto-install doesn't cover your setup, you can install the skill file manually:

Feed SKILL.md to your agent directly:

bash

curl -fsSL https://officecli.ai/SKILL.md

Install as a local skill for Claude Code:

bash

curl -fsSL https://officecli.ai/SKILL.md -o ~/.claude/skills/officecli.md

Other agents: Include the contents of SKILL.md in your agent's system prompt or tool description.

</details>

`Why your agent will thrive on OfficeCLI`

- Deterministic JSON output — every command supports --jsonwith consistent schemas. No regex parsing, no scraping stdout. - Path-based addressing — every element has a stable path (/slide[1]/shape[2]). Agents navigate documents without understanding XML namespaces. (OfficeCLI syntax: 1-based indexing, element local names — not XPath.) - Progressive complexity (L1 → L2 → L3) — agents start with read-only views, escalate to DOM ops, fall back to raw XML only when needed. Minimizes token usage. - Self-healing workflow —validate, view issues, and the structured error codes (not_found, invalid_value, unsupported_property) return suggestions and valid ranges. Agents self-correct without human intervention. - Built-in agent-friendly rendering engine —view html / view screenshot / watchemit HTML and PNG natively. No Office required. Agents can see their output and fix layout issues, even inside CI / Docker / headless environments. - Built-in formula & pivot engine — 350+ Excel functions auto-evaluated on write (incl. spilling dynamic arrays, financial / bond and statistical families); native OOXML pivot tables from a source range with one command. Agents read computed values and shipped aggregations immediately, without round-tripping through Office. - Template merge — agent designs the layout once, downstream code fills{{key}}placeholders N times. Avoids burning tokens regenerating every report from scratch. - Round-trip dump —dump turns any .docx, .pptx, or .xlsxinto replayable batch JSON. Agents learn from human-authored samples by reading a structured spec, not raw OOXML XML. - Built-in help — when unsure about property names or value formats, the agent runsofficecli <format> set <element>instead of guessing. - Auto-install — OfficeCLI detects your AI tooling (Claude Code, Cursor, VS Code, …) and configures itself. No manual skill-file setup.

`Built-in Help`

Don't guess property names — drill into the help:

bash

officecli help pptx set              # All settable elements and properties
officecli help pptx set shape        # Detail for one element type
officecli help docx query            # Selector reference: attributes, :contains, :has(), etc.

Run officecli --help for the full overview.

`JSON Output Schemas`

All commands support --json. The general response shapes:

Single element (get --json):

json

{"tag": "shape", "path": "/slide[1]/shape[1]", "attributes": {"name": "TextBox 1", "text": "Hello"}}

List of elements (query --json):

json

[
  {"tag": "paragraph", "path": "/body/p[1]", "attributes": {"style": "Heading1", "text": "Title"}},
  {"tag": "paragraph", "path": "/body/p[5]", "attributes": {"style": "Heading1", "text": "Summary"}}
]

Errors return a non-zero exit code with a structured error object including error code, suggestion, and valid values when available:

json

{
  "success": false,
  "error": {
    "error": "Slide 50 not found (total: 8)",
    "code": "not_found",
    "suggestion": "Valid Slide index range: 1-8"
  }
}

Error codes: not_found, invalid_value, unsupported_property, invalid_path, unsupported_type, missing_property, file_not_found, file_locked, invalid_selector. Property names are auto-corrected -- misspelling a property returns a suggestion with the closest match.

Error Recovery -- Agents self-correct by inspecting available elements:

bash

Agent tries an invalid path

officecli get report.docx /body/p[99] --json
Returns: {"success": false, "error": {"error": "...", "code": "not_found", "suggestion": "..."}}
Agent self-corrects by checking available elements

officecli get report.docx /body --depth 1 --json
Returns the list of available children, agent picks the right path

Mutation confirmations (set, add, remove, move, create with --json):

json

{"success": true, "path": "/slide[1]/shape[1]"}

See officecli --help for full details on exit codes and error formats.

`Comparison`

| | OfficeCLI | Microsoft Office | LibreOffice | python-docx / openpyxl | |---|---|---|---|---| | Open source & free | ✓ (Apache 2.0) | ✗ (paid license) | ✓ | ✓ | | AI-native CLI + JSON | ✓ | ✗ | ✗ | ✗ | | Zero install (single binary) | ✓ | ✗ | ✗ | ✗ (Python + pip) | | Call from any language | ✓ (CLI) | ✗ (COM/Add-in) | ✗ (UNO API) | Python only | | Path-based element access | ✓ | ✗ | ✗ | ✗ | | Raw XML fallback | ✓ | ✗ | ✗ | Partial | | Built-in agent-friendly rendering engine | ✓ | ✗ | ✗ | ✗ | | Headless HTML/PNG output | ✓ | ✗ | Partial | ✗ | | Template merge ({{key}}) across formats | ✓ | ✗ | ✗ | ✗ | | Round-trip dump → batch JSON | ✓ | ✗ | ✗ | ✗ | | Live preview (auto-refresh on edit) | ✓ | ✗ | ✗ | ✗ | | Headless / CI | ✓ | ✗ | Partial | ✓ | | Cross-platform | ✓ | Windows/Mac | ✓ | ✓ | | Word + Excel + PowerPoint | ✓ | ✓ | ✓ | Separate libs |

`Command Reference`

| Command | Description | |---------|-------------| |create| Create a blank .docx, .xlsx, or .pptx (type from extension) | |view | View content (modes: outline, text, annotated, stats (--page-count), issues, html, svg, screenshot, pdf (via exporter plugin), forms (via format-handler plugin)). docx supports --render auto\|native\|html. | |load_skill| Print embedded SKILL.md content for a specialized skill (no install) | |get | Get element and children (--depth N, --json) | |query | CSS-like query with boolean and/or, row-by-column-name (row[Salary>5000]), --findflag | |set | Modify element properties; accepts selectors and Excel-native paths (parity with get/query), --find/--replaceflags | |add | Add element (or clone with --from <path>) | |remove| Remove an element | |move | Move element (--to <parent>, --index N, --after <path>, --before <path>) | |swap| Swap two elements | |validate| Validate against OpenXML schema | |view <file> issues| Enumerate document issues (text overflow, missing alt text, formula errors, ...) | |batch | Multiple operations applied in a single pass (stdin, --input, or --commands; atomic by default — any failed item rolls back the whole batch — --best-effort to keep partial progress, --stop-on-errorto abort early) | |dump | Serialize a .docx, .pptx, or .xlsx into a replayable batch JSON (round-trip via batch); accepts a subtree path | |refresh | Recalculate TOC page numbers / PAGE / cross-references (.docx; Word backend on Windows, headless-HTML fallback) | |plugins | List / inspect / lint installed plugins (extend to .doc, .hwpx, .pdfexport via dump-reader / exporter / format-handler kinds) | |merge | Template merge — replace {{key}}placeholders with JSON data | |watch| Live HTML preview in browser with auto-refresh | |mcp| Start MCP server for AI tool integration | |raw| View raw XML of a document part | |raw-set| Modify raw XML via XPath | |add-part| Add a new document part (header, chart, etc.) | |open| Start resident mode (keep document in memory) | |close| Save and close resident mode | |install | Install binary + skills + MCP (all, claude, cursor, etc.) | |config| Get or set configuration | |help <format> <command> | Built-in help (e.g. officecli help pptx set shape) |

`End-to-End Workflow Example`

A typical self-healing agent workflow: create a presentation, populate it, verify, and fix issues -- all without human intervention.

bash

1. Create

officecli create report.pptx
2. Add content

officecli add report.pptx / --type slide --prop title="Q4 Results"
officecli add report.pptx '/slide[1]' --type shape \
  --prop text="Revenue: $4.2M" --prop x=2cm --prop y=5cm --prop size=28
officecli add report.pptx / --type slide --prop title="Details"
officecli add report.pptx '/slide[2]' --type shape \
  --prop text="Growth driven by new markets" --prop x=2cm --prop y=5cm
3. Verify

officecli view report.pptx outline
officecli validate report.pptx
4. Fix any issues found

officecli view report.pptx issues --json
Address issues based on output, e.g.:

officecli set report.pptx '/slide[1]/shape[1]' --prop font=Arial

`Units & Colors`

All dimension and color properties accept flexible input formats:

| Type | Accepted formats | Examples | |------|-----------------|----------| | Dimensions | cm, in, pt, px, or raw EMU |2cm, 1in, 72pt, 96px, 914400| | Colors | Hex, named, RGB, theme |#FF0000, FF0000, red, rgb(255,0,0), accent1| | Font sizes | Bare number or pt-suffixed |14, 14pt, 10.5pt| | Spacing | pt, cm, in, or multiplier |12pt, 0.5cm, 1.5x, 150% |

`Common Patterns`

bash

Replace all Heading1 text in a Word doc

officecli query report.docx "paragraph[style=Heading1]" --json | ...
officecli set report.docx /body/p[1]/r[1] --prop text="New Title"
Export all slide content as JSON

officecli get deck.pptx / --depth 2 --json
Bulk-update Excel cells

officecli batch budget.xlsx --input updates.json --json
Import CSV data into an Excel sheet

officecli add budget.xlsx / --type sheet --prop name="Q1 Data"
officecli import budget.xlsx "/Q1 Data" sales.csv --header
Template merge for batch reports

officecli merge invoice-template.docx invoice-001.docx --data '{"client":"Acme","total":"$5,200"}'
Check document quality before delivery

officecli validate report.docx && officecli view report.docx issues --json

From Python or Node.js — install one of the thin resident-pipe SDKs (no per-call process spawn):

python

Python — pip install officecli-sdk

import officecli
with officecli.create("deck.pptx") as doc:          # or officecli.open("deck.pptx")
    doc.send({"command": "add", "parent": "/", "type": "slide"})
    print(doc.send({"command": "get", "path": "/slide[1]"}))

javascript

// Node.js — npm install @officecli/sdk`
const oc = require("@officecli/sdk");
const doc = await oc.create("deck.pptx");            // or oc.open("deck.pptx")
await doc.send({ command: "add", parent: "/", type: "slide" });
console.log(await doc.send({ command: "get", path: "/slide[1]" }));
await doc.close();

Both SDKs auto-provision the native CLI when missing (mirror-first, Windows-capable) and announce the install rather than doing it silently.

Or wrap subprocess directly, one-shot:

python

import json, subprocess
def cli(*args):
    return json.loads(subprocess.check_output(["officecli", *args, "--json"], text=True))
cli("create", "deck.pptx")

Documentation

The Wiki has detailed guides for every command, element type, and property:

- By format: Word | Excel | PowerPoint
- Workflows: End-to-end examples -- Word reports, Excel dashboards, PowerPoint decks, batch modifications, resident mode
- Runnable examples: examples/ -- copy-paste scripts (.sh/.py) for Word, Excel, and PowerPoint, with output files included
- Troubleshooting: Common errors and solutions
- AI agent guide: Decision tree for navigating the wiki

Build from Source

Requires .NET 10 SDK for compilation only. The output is a self-contained, native binary -- .NET is embedded in the binary and is not needed at runtime.

bash

./build.sh

License

Apache License 2.0

Bug reports and contributions are welcome on GitHub Issues.

---

If you find OfficeCLI useful, please give it a star on GitHub — it helps others discover the project.

OfficeCLI.AI | GitHub

<!--
yaml-frontmatter:
name: officecli
version: see GitHub Releases
description: The standard CLI for AI agents to create, read, and modify Office documents
formats: [docx, xlsx, pptx]
platforms: [macos, linux, windows]
license: Apache-2.0
keywords: [office, cli, ai-agent, automation, docx, xlsx, pptx, openxml, document-generation, mcp-server, word, excel, powerpoint]
ai-agent-compatible: true
mcp-server: true
skill-file: SKILL.md

install-command-unix: curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
install-command-windows: irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
-->

OfficeCLI

For AI Agents — Get Started in One Line Copy Chapter

For Humans Copy Chapter

For Developers — See It Live in 30 Seconds Copy Chapter

1. Install (macOS / Linux) — or: brew install officecli / npm install -g @officecli/officecli

Windows (PowerShell): irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex

2. Create a blank PowerPoint

3. Start live preview — opens http://localhost:26315 in your browser

4. Open another terminal, add a slide — watch the browser update instantly

Quick Start Copy Chapter

Create a presentation and add content

View as outline

→ Slide 1: Q4 Report

→ Shape 1 [TextBox]: Revenue grew 25%

View as HTML — opens a rendered preview in your browser, no server needed

Get structured JSON for any element

Save and close — flushes the resident session to disk

Why OfficeCLI? Copy Chapter

... 45 more lines ...

Use Cases Copy Chapter

Installation Copy Chapter

macOS / Linux

Windows (PowerShell)

Homebrew (macOS / Linux)

Scoop (Windows)

npm (all platforms — fetches the native binary for your platform)

Key Features Copy Chapter

Built-in Engines & Generation Primitives Copy Section

Resident Mode & Batch Copy Section

Resident mode — near-zero latency via named pipes

Batch mode — multi-command execution (atomic by default: any failed item rolls back the whole batch)

Inline batch with --commands (no stdin needed)

Keep whatever succeeds even if some items fail (pre-1.0.137 behavior)

Stop at the first failing command instead of running the rest (still rolls back everything unless combined with --best-effort)

Three-Layer Architecture Copy Section

L1 — high-level views

L2 — element-level operations

L3 — raw XML when L2 isn't enough

AI Integration Copy Chapter

MCP Server Copy Section

Direct CLI Integration Copy Section

Why your agent will thrive on OfficeCLI Copy Section

Built-in Help Copy Section

JSON Output Schemas Copy Section

Agent tries an invalid path

Returns: {"success": false, "error": {"error": "...", "code": "not_found", "suggestion": "..."}}

Agent self-corrects by checking available elements

Returns the list of available children, agent picks the right path

Comparison Copy Chapter

Command Reference Copy Chapter

End-to-End Workflow Example Copy Chapter

1. Create

2. Add content

3. Verify

4. Fix any issues found

Address issues based on output, e.g.:

Units & Colors Copy Section

Common Patterns Copy Chapter

Replace all Heading1 text in a Word doc

Export all slide content as JSON

Bulk-update Excel cells

Import CSV data into an Excel sheet

Template merge for batch reports

Check document quality before delivery

Python — pip install officecli-sdk

Documentation Copy Chapter

Build from Source Copy Chapter

License Copy Chapter

For AI Agents — Get Started in One Line

For Humans

For Developers — See It Live in 30 Seconds

Quick Start

Why OfficeCLI?

Use Cases

Installation

Key Features

Built-in Engines & Generation Primitives

Resident Mode & Batch

`Three-Layer Architecture`

`AI Integration`

`MCP Server`

`Direct CLI Integration`

`Why your agent will thrive on OfficeCLI`

`Built-in Help`

`JSON Output Schemas`

`Comparison`

`Command Reference`

`End-to-End Workflow Example`

`Units & Colors`

`Common Patterns`

`Python —` pip install officecli-sdk

Documentation

Build from Source

License