---
name: officecli
description: "OfficeCLI — AI-native single-binary CLI for .docx/.xlsx/.pptx creation, editing, inspection, and visual preview. Use for most Office document tasks instead of python-docx/python-pptx/openpyxl."
version: 1.0.0
---

# OfficeCLI

Single binary CLI for Office documents. No Office installation, no Python dependencies.
Path-based addressing, built-in HTML renderer, formula engine, MCP server.

**Binary**: `officecli` (installed at /usr/bin/officecli)

## When to Use

Use officecli for ALL .docx/.xlsx/.pptx creation/editing/inspection tasks. Falls back to python-docx/python-pptx/openpyxl only for:
- Complex programmatic layout that officecli can't express
- PDF/OCR (officecli doesn't support)
- Bidding workflow orchestration (bidding-documents skill)

## Quick Reference

| Task | Command |
|------|---------|
| Create blank | `officecli create file.pptx` |
| View outline | `officecli view file.pptx outline` |
| View as HTML | `officecli view file.pptx html` |
| Get element JSON | `officecli get file.pptx '/slide[1]' --depth 1 --json` |
| Add slide | `officecli add file.pptx / --type slide --prop title="Hello"` |
| Add shape | `officecli add file.pptx '/slide[1]' --type shape --prop text="Hi" --prop x=2cm --prop y=5cm` |
| Set property | `officecli set file.pptx '/slide[1]/shape[1]' --prop fill=FF0000` |
| Find & replace | `officecli set file.docx / --find draft --replace final` |
| Query elements | `officecli query file.docx 'paragraph[style=Heading1]'` |
| Remove element | `officecli remove file.docx '/body/p[4]'` |
| Validate | `officecli validate file.pptx` |
| Check issues | `officecli view file.pptx issues` |
| Live preview | `officecli watch file.pptx` → http://localhost:26315 |
| Template merge | `officecli merge template.pptx out.pptx '{"key":"val"}'` |
| Dump to JSON | `officecli dump file.pptx -o blueprint.json` |
| Batch replay | `officecli batch new.pptx --input blueprint.json` |
| Save (flush) | `officecli save file.pptx` |
| Close (save+release) | `officecli close file.pptx` |

## Help System (CRITICAL)

**Always run help instead of guessing property names:**
```bash
officecli help pptx                  # list pptx elements
officecli help pptx shape            # shape schema
officecli help pptx set shape        # settable props only
officecli help pptx shape --json     # machine-readable
```

Format aliases: `word`→`docx`, `excel`→`xlsx`, `ppt`/`powerpoint`→`pptx`.

## Shell Quoting Rules

- **Always quote paths**: `'/slide[1]/shape[2]'` (zsh globs unquoted brackets)
- **Single-quote values with `$`**: `--prop text='$15M'` (double-quoted `$15M` → `M`)
- **Newlines**: `\\n` in `text=` is a line break

## Built-in Specialized Skills

Load via `officecli load_skill <name>`:

| Skill | When |
|-------|------|
| `pptx` | Generic presentations (default) |
| `pitch-deck` | Fundraising/VC decks |
| `morph-ppt` | Morph transitions across slides |
| `morph-ppt-3d` | 3D models + Morph |
| `word` | Word documents (default) |
| `academic-paper` | Papers with citations/equations |
| `excel` | Spreadsheets (default) |
| `financial-model` | DCF/LBO/3-statement models |
| `data-dashboard` | KPI dashboards from CSV |

## Key Capabilities (vs python-*)

| Feature | officecli | python-pptx/docx |
|---------|-----------|-----------------|
| Visual feedback | `view html/screenshot` + `watch` live preview | None (blind generation) |
| Excel formulas | Auto-evaluate on write (350+ functions) | Need Excel to recalc |
| Pivot tables | One command from source range | VBA or raw XML |
| Path-based addressing | `/slide[1]/shape[2]` intuitive | Object model traversal |
| Template merge | Built-in `merge {{key}}` | Manual string replace |
| Error recovery | Structured error codes + suggestions | Python exceptions |
| MCP server | Built-in, auto-detects AI tools | None |

## Pitfalls

- PPT `shape[1]` is typically title placeholder — use `shape[2]+` for content
- zsh/bash: always quote paths with brackets `'/slide[1]'`
- After mutations, verify with `view issues` and `validate`
- Before non-officecli tools read the file, run `officecli save file.pptx`
- The binary auto-starts a resident on first access (60s idle timeout) — file-lock conflicts are auto-avoided