officecli
AI-friendly CLI for .docx, .xlsx, .pptx. Single binary, no dependencies, no Office installation needed.
Install
bash
# macOS / Linux
curl -fsSL https://d.officecli.ai/install.sh | bash
# Windows (PowerShell)
irm https://d.officecli.ai/install.ps1 | iex
Verify with
. If still not found after install, open a new terminal.
Strategy
L1 (read) → L2 (DOM edit) → L3 (raw XML). Always prefer higher layers. Add
for structured output.
Before doc work, check Specialized Skills (bottom of this file). Fundraising decks, academic papers, financial models, dashboards, and Morph animations need their own skill loaded first —
once, then proceed.
Help System (IMPORTANT)
When unsure about property names, value formats, or command syntax, ALWAYS run help instead of guessing. One help query beats guess-fail-retry loops.
≡
, and
≡
— same content.
bash
officecli help # All commands + global options + schema entry points
officecli help docx # List all docx elements
officecli help docx paragraph # Full schema: properties, aliases, examples, readbacks
officecli help docx set paragraph # Verb-filtered: only props usable with `set`
officecli help docx paragraph --json # Structured schema (machine-readable)
Format aliases:
→
,
→
,
/
→
. Verbs:
,
,
,
,
. MCP exposes the same schema via the single
string param:
{"command":"help docx paragraph"}
(not a structured
{"format":...,"type":...}
object — the MCP tool has exactly one param,
, and passes it through to the CLI verbatim).
Performance: Resident Mode
Every command auto-starts a resident on first access (60s idle timeout) — file-lock conflicts are automatically avoided. Explicit
/
is still recommended for longer sessions (12min idle):
bash
officecli open report.docx # explicitly keep in memory
officecli set report.docx ... # no file I/O overhead
officecli close report.docx # save and release
Opt out of auto-start:
OFFICECLI_NO_AUTO_RESIDENT=1
.
Flush only at the non-officecli boundary. officecli's own reads (
/
/
/
) always see your latest edits, so you never need to save mid-workflow. Run
(keeps the resident) or
(flush + release) only
before a non-officecli program reads the file — python-docx/openpyxl, Word, a renderer, delivery/upload. (Idle sessions auto-flush within seconds;
OFFICECLI_RESIDENT_FLUSH=each
makes every mutation flush before returning.)
Quick Start
PPT:
bash
officecli create slides.pptx
officecli add slides.pptx / --type slide --prop title="Q4 Report" --prop background=1A1A2E
officecli add slides.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
Word:
bash
officecli create report.docx
officecli add report.docx /body --type paragraph --prop text="Executive Summary" --prop style=Heading1
officecli add report.docx /body --type paragraph --prop text="Revenue increased by 25% year-over-year."
Excel:
bash
officecli create data.xlsx
officecli set data.xlsx /Sheet1/A1 --prop value="Name" --prop bold=true
officecli set data.xlsx /Sheet1/A2 --prop value="Alice"
L1: Create, Read & Inspect
bash
officecli create <file> # Create blank .docx/.xlsx/.pptx (type from extension)
officecli view <file> <mode> # outline | stats | issues | text | annotated | html
officecli get <file> <path> --depth N # Get a node and its children [--json]
officecli query <file> <selector> # CSS-like query
officecli validate <file> # Validate against OpenXML schema
view modes
| Mode | Description | Useful flags |
|---|
| Document structure | |
| Statistics (pages, words, shapes) | |
| Formatting/content/structure problems | --type format|content|structure
|
| Plain text extraction | , |
| Text with formatting annotations | |
| Static HTML snapshot — same renderer as , no server needed | , (docx), (pptx) |
| / / / | PNG via headless browser / SVG (pptx slide) / PDF via exporter plugin / form-fields JSON via format-handler plugin | , --screenshot-width/-height
|
Use
for one-shot snapshots (CI artifacts, archival, diffing); use
when you need live refresh or browser-side click-to-select.
get
Any XML path via element localName. Use
to expand children. Add
for structured output. Default text output is grep-friendly:
path (type) "text" key=val key=val ...
bash
officecli get report.docx '/body/p[3]' --depth 2 --json
officecli get slides.pptx '/slide[1]' --depth 1 # list all shapes on slide 1
officecli get data.xlsx '/Sheet1/B2' --json
Stable ID Addressing
Elements with stable IDs return
paths instead of positional indices. Prefer these in multi-step workflows — positional indices shift on insert/delete, stable IDs do not.
/slide[1]/shape[@id=550950021] # PPT shape
/slide[1]/table[@id=1388430425]/tr[1]/tc[2] # PPT table
/body/p[@paraId=1A2B3C4D] # Word paragraph
/comments/comment[@commentId=1] # Word comment
PPT also accepts
(e.g.
), with morph
prefix awareness. Elements without stable IDs (slide, run, tr/tc, row) fall back to positional indices.
query
CSS-like selectors:
,
,
,
,
,
,
,
,
. Boolean
/
supported across
/
/
:
cell[value>5000 or value<100]
,
cell[(type=Number or type=Date) and value>0]
. Excel row-by-column-name:
.
accepts selectors and Excel-native paths (parity with
/
). Bare unscoped selectors rejected on
/
.
bash
officecli query report.docx 'paragraph[style=Normal] > run[font!=Arial]'
officecli query slides.pptx 'shape[fill=FF0000]'
Watch & Interactive Selection
Live HTML preview that auto-refreshes on every file change. Browsers can click / shift-click / box-drag to select shapes; the CLI can read the current browser selection and act on it.
bash
officecli watch <file> [--port N] # Start preview server (default port 26315)
officecli unwatch <file> # Stop
officecli goto <file> <path> # Scroll watching browser(s) to element (docx: p / table / tr / tc)
Open the printed
URL. Click to select; shift/cmd/ctrl+click to multi-select; drag from empty space to box-select. PPT/Word use blue outline; Excel uses native-style green selection (double-click cell to edit inline; drag a chart to reposition).
— read what the user clicked
bash
officecli get <file> selected [--json]
Returns DocumentNodes for whatever is currently selected. Empty result if nothing selected. Exit code != 0 if no watch is running.
bash
# User clicks shapes in the browser, then asks "make these red"
PATHS=$(officecli get deck.pptx selected --json | jq -r '.data.Results[].path')
for p in $PATHS; do officecli set deck.pptx "$p" --prop fill=FF0000; done
Key properties
- Selection survives file edits. Paths use stable form.
- All connected browsers share one selection. Last-write-wins.
- Same-file single-watch. A given file can have only one watch process at a time.
- Group shapes select as a whole. Drilling into individual children of a group is not supported in v1.
- Coverage: shapes/pictures/tables/charts/connectors/groups; top-level paragraphs and tables. Inherited layout/master decorations and Word nested elements (table cells, run-level) are not addressable. does not emit — / on xlsx always resolve (v2 candidate).
Marks — edit proposals waiting for review
Use
when changes need human review BEFORE they hit the file. Marks live in the watch process only; a separate
pipeline applies accepted ones. For one-shot changes use
directly; for permanent file annotations use
(Word native).
bash
officecli mark <file> <path> [--prop find=... color=... note=... tofix=... regex=true] [--json]
officecli unmark <file> [--path <p> | --all] [--json]
officecli get-marks <file> [--json]
Props:
(literal or regex when
; raw form
),
(hex /
/ 22 named whitelist),
,
(drives apply pipeline).
Path must be
format from watch HTML — see subskills for full pipeline.
L2: DOM Operations
set — modify properties
bash
officecli set <file> <path> --prop key=value [--prop ...]
Any XML attribute is settable via element path (found via
) — even attributes not currently present. Without
,
applies format to the entire element.
Value formats:
| Type | Format | Examples |
|---|
| Colors | Hex (with/without ), named, RGB, theme | , , , , .. |
| Spacing | Unit-qualified | , , , |
| Dimensions | EMU or suffixed | , , , , |
Dotted-attr aliases —
forms accepted on shape/run/paragraph/table/row/cell/section/styles, e.g.
--prop font.color=red --prop font.bold=true --prop font.size=14pt
. Run
officecli help <fmt> <element>
for the full list.
find — format or replace matched text
Use top-level
/
on
(and
on
). Legacy
still works but emits a hint.
bash
# Format matched text (auto-splits runs)
officecli set doc.docx '/body/p[1]' --find weather --prop bold=true --prop color=red
# Regex matching (regex= still a prop flag)
officecli set doc.docx '/body/p[1]' --find '\d+%' --prop regex=true --prop color=red
# Replace text (use `/` for whole-document scope)
officecli set doc.docx / --find draft --replace final
# docx: tracked Find&Replace
officecli set doc.docx / --find draft --replace final --prop revision.author=Alice
# PPT — same syntax, different paths
officecli set slides.pptx / --find draft --replace final
Path controls search scope: = whole document,
or
= specific element,
/
= headers/footers.
Notes:
- Case-sensitive by default. Case-insensitive:
--prop 'find=(?i)error' --prop regex=true
- Matches work across run boundaries
- No match = silent success. includes
- Excel: only + supported (no find + format props)
add — add elements or clone
bash
officecli add <file> <parent> --type <type> [--prop ...]
officecli add <file> <parent> --type <type> --after <path> [--prop ...] # insert after anchor
officecli add <file> <parent> --type <type> --before <path> [--prop ...] # insert before anchor
officecli add <file> <parent> --type <type> --index N [--prop ...] # 0-based position (legacy)
officecli add <file> <parent> --from <path> # clone existing element
,
,
are mutually exclusive. No position flag = append to end.
Element types (with aliases):
| Format | Types |
|---|
| pptx | slide (incl. hidden), shape (font.latin/ea/cs, direction=rtl, underline.color, highlight=COLOR (Add/Set/Get/HTML preview), effective.X+effective.X.src; arrow alias for rightArrow; slideMaster/slideLayout typed add/set/remove), picture (SVG, brightness/contrast/glow/shadow, rotation, link, tooltip), chart (direction=rtl, pieOfPie, barOfPie, axisLine/gridline per-attr setters, animation+chartBuild=byCategory |
| docx | paragraph (direction/font.latin/ea/cs, bold.cs/italic.cs/size.cs, lang.latin/ea/cs, wordWrap, framePr.*, tabs shorthand), run (lang slots, direction, underline.color, position half-pts, revision.type=ins|del|format|moveFrom|moveTo + revision.action=accept|reject with .author/.date — bare / selector on for filtered accept/reject, but needs the dotted / form; move+revision is run-level paths only, not paragraph-level; range=START:END on a paragraph/shape path formats a char span by explicit 0-based half-open offset instead of addressing a run — the offset sibling of find=), table (direction=rtl, hMerge, cantSplit on row/nowrap on cell (both add+set), virtual column ops: add/remove/move/copyfrom on /body/tbl[N]/col), row (tr), cell (td), image, header/footer (direction), section (pageNumFmt full enum, direction=rtl, rtlGutter, pgBorders=box), bookmark, comment, footnote, endnote, formfield, sdt, chart, equation, field (28 types), hyperlink, style (direction, indents, pbdr, lineSpacing on Add/Set), toc, watermark, break, ole, num/abstractNum/lvl, tab, textbox/shape (add-mostly — Get returns raw XML preview only, no structured readback; Set is limited to width/height/geometry/fill/line.*; position is / not bare x/y; textbox-only /rotation/gradient/shadow — docx shape itself has neither rotation nor gradient), embedded OLE round-trip on dump→batch, diagram (add-only mermaid → native shapes or rendered image, /, no x/y at add-time — reposition via ). docDefaults.rtl, autoHyphenation, exposes locale + /comments /footnotes /endnotes. for raw OOXML scaffolding. |
| xlsx | sheet (visible/hidden/veryHidden, print margins, printTitleRows/Cols, rightToLeft sheetView, cascade-aware rename), row (c{N}= cell-content shorthand; add accepts --from /Sheet/col[L]; formula-ref rewrite on insert), col (formula-ref rewrite, named-range follow on move), cell (type=richtext+runs, merge=range/sweep, direction=rtl, phonetic; --shift left|up on remove, shift=right|down on add — Excel UI dialog parity; formula auto-detect; OFFSET/INDIRECT in calc), chart (per-axis RTL/title, anchor=x,y,w,h, pareto), image (SVG), comment (direction=rtl), table (listobject), namedrange (definedname, volatile, ; formula-body inlined at parse), pivottable (cache CoW + cross-pivot sharing, labelFilter=field:type:value add-time-only, topN=integer add-time-only, fillDownLabels is an alias of repeatLabels not a separate feature, calculatedField), sparkline, validation, autofilter, shape, textbox, CF (databar/colorscale/iconset/formulacf/cellIs/topN/aboveAverage), ole, csv. Query supports /. Workbook: password. Shape selector enumerates leaves inside grpSp. |
Pivot tables (xlsx)
bash
officecli add data.xlsx /Sheet1 --type pivottable \
--prop source="Sheet1!A1:E100" --prop rows=Region,Category \
--prop cols=Year --prop values="Sales:sum,Qty:count" \
--prop grandTotals=rows --prop subtotals=off --prop sort=asc
Key props:
,
,
(Field:func[:showDataAs]),
,
,
,
(compact/outline/tabular),
,
,
,
(percent_of_total/row/col, running_total),
,
,
. Aggregators: sum, count, average, max, min, product, stdDev, stdDevp, var, varp, countNums. Date columns auto-group. Run
officecli help xlsx pivottable
for full schema.
Document-level properties (all formats)
bash
officecli set doc.docx / --prop docDefaults.font=Arial --prop docDefaults.fontSize=11pt
officecli set doc.docx / --prop protection=forms --prop evenAndOddHeaders=true
officecli set data.xlsx / --prop calc.mode=manual --prop calc.refMode=r1c1
officecli set slides.pptx / --prop defaultFont=Arial --prop show.loop=true --prop print.what=handouts
Run
officecli help <format> /
for all document-level properties (docDefaults, docGrid, CJK spacing, calc, print, show, theme, extended).
Sort (xlsx)
bash
officecli set data.xlsx /Sheet1 --prop sort="C desc" --prop sortHeader=true
officecli set data.xlsx '/Sheet1/A1:D100' --prop sort="A asc" --prop sortHeader=true
Format:
. Rejects ranges with merged cells or formulas. Sidecar metadata (hyperlinks, comments, conditional formatting, drawings) follows rows automatically.
Text-anchored insert ( / )
Locate an insertion point by text match within a paragraph. Inline types (run, picture, hyperlink) insert within the paragraph; block types (table, paragraph) auto-split it. PPT only supports inline.
bash
# Word: inline run after matched text
officecli add doc.docx '/body/p[1]' --type run --after find:weather --prop text=" (sunny)"
# Word: block table after matched text (auto-splits paragraph)
officecli add doc.docx '/body/p[1]' --type table --after "find:First sentence." --prop rows=2 --prop cols=2
Clone
officecli add <file> / --from '/slide[1]'
— copies with all cross-part relationships.
move, swap, remove
bash
officecli move <file> <path> [--to <parent>] [--index N] [--after <path>] [--before <path>]
officecli swap <file> <path1> <path2>
officecli remove <file> '/body/p[4]'
When using
or
,
can be omitted — the target container is inferred from the anchor.
batch — multiple operations in one save cycle
Atomic by default (v1.0.137+): every item still runs and is reported (so
stays meaningful and every failure surfaces), but if
any item fails the whole batch rolls back — the file on disk is left byte-identical to before the batch ran (confirmed live in both standalone and resident mode). Use
to restore the old apply-what-succeeds behavior (useful for lossy
replays where losing the whole thing over one unsupported item is worse than a partial result).
only changes how early the run stops (remaining items are
), not whether what ran gets kept — combine it with
if you want "stop at first failure but keep what already succeeded."
is unrelated — it's only the docx-protection bypass. Failed items carry a machine-readable
field (same list as
); a rolled-back batch's JSON summary carries
.
officecli dump <file> [<path>]
emits a replayable batch JSON for round-trip —
(full coverage),
(text/tables/pictures/charts/notes/theme + OLE/3D/video/audio/SmartArt/morph/p15 transitions via raw-set passthrough), and
(cells/formulas/styles + tables, conditional formatting, validations, comments, charts, sparklines, pictures, shapes, pivot tables; slicers/chartEx/OLE via verbatim carrier). Path defaults to
(whole document); pass a subtree path (docx:
,
,
,
,
,
,
; xlsx:
,
) to scope the dump.
officecli refresh <file.docx>
recalculates TOC page numbers / PAGE / cross-references after replay (Word backend on Windows; headless-HTML fallback elsewhere).
extends support to
,
,
export.
bash
echo '[
{"command":"set","path":"/Sheet1/A1","props":{"value":"Name","bold":"true"}},
{"command":"set","path":"/Sheet1/B1","props":{"value":"Score","bold":"true"}}
]' | officecli batch data.xlsx --json
officecli batch data.xlsx --commands '[{"op":"set","path":"/Sheet1/A1","props":{"value":"Done"}}]' --json
officecli batch data.xlsx --input updates.json --best-effort --json # keep whatever succeeds even if some items fail
Supports:
,
,
,
,
,
,
,
,
,
,
. Fields:
(or
),
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
.
L3: Raw XML
Use when L2 cannot express what you need. No xmlns declarations needed — prefixes auto-registered.
bash
officecli raw <file> <part> # view raw XML
officecli raw-set <file> <part> --xpath "..." --action replace --xml '<w:p>...</w:p>'
officecli add-part <file> <parent> # create new document part (returns rId)
actions:
,
,
,
,
,
,
. Run
officecli help <format> raw
for available parts.
Common Pitfalls
| Pitfall | Correct Approach |
|---|
| Use — all attributes go through |
| Unquoted paths in zsh/bash | Always quote: or (shell glob-expands brackets) |
| PPT for content | is typically the title placeholder. Use for content shapes |
| Name indexing not supported. Use numeric index or (PPT only) |
| Guessing property names | Run officecli help <format> <element>
|
| Modifying an open file | Close the file in PowerPoint/WPS first |
| in shell strings | Use for newlines in |
| in shell text | strips . Use single quotes: , or heredoc batch |
Specialized Skills
officecli load_skill <name>
— output is a SKILL.md, follow its rules.
Loading rule:
- Pick the most specific match in "When to use"; if none fits, load the format default ( / / ).
- Scenes already contain the format default's rules — load one skill per artifact, never stack.
- Loaded rules persist across turns; don't re-load each reply.
- Two distinct artifacts → two separate loads.
Word (.docx)
| Name | When to use |
|---|
| Reports, letters, memos, proposals, generic documents |
| Journal / conference / thesis: APA / Chicago / IEEE / MLA citations, equations, SEQ + PAGEREF cross-refs, multi-column journal layout, bibliography. NOT for business reports or letters (route those to ) |
PowerPoint (.pptx)
| Name | When to use |
|---|
| Generic decks: board reviews, sales decks, all-hands, product launches |
| Fundraising only — seed / Series A-C / SAFE / convertible / strategic raise. NOT for sales / product / board decks (route those to ) |
| Cinematic Morph-animated presentations. NOT for static decks (route those to ) |
| 3D Morph: GLB models, camera moves, depth. NOT for 2D-only Morph (route those to ) |
Excel (.xlsx)
| Name | When to use |
|---|
| Generic workbooks, formulas, pivots, trackers |
| Financial models, scenarios, projections. NOT for general data analysis (route those to ) |
| CSV/tabular data → KPI / analytics / executive dashboards with charts and sparklines. NOT for raw data tracking (route those to ) |
Example: a fundraising deck task →
officecli load_skill pitch-deck
→ use the printed rules.
Notes
- Paths are 1-based (XPath convention): = third paragraph
- is 0-based (array convention): = first position
- Excel exception: for and , is 1-based (matches OOXML RowIndex / column letter index). inserts at row 5 / column 5.
- After modifications, verify with and/or
- When unsure, run
officecli help <format> <element>