Officecli

officecli

AI-friendly CLI for .docx, .xlsx, .pptx. Single binary, no dependencies, no Office installation needed.

Install

If officecli is not installed:

# macOS / Linux
curl -fsSL https://d.officecli.ai/install.sh | bash

# Windows (PowerShell)
irm https://d.officecli.ai/install.ps1 | iex

Verify with officecli --version. If still not found after install, open a new terminal.

---

Strategy

L1 (read) → L2 (DOM edit) → L3 (raw XML). Always prefer higher layers. Add --json 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 — load_skill 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.

officecli help ≡ officecli --help, and officecli --help ≡ officecli help — same content.

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: word→docx, excel→xlsx, ppt/powerpoint→pptx. Verbs: add, set, get, query, remove. MCP exposes the same schema via {"command":"help","format":"docx","type":"paragraph"}.

---

Performance: Resident Mode

Every command auto-starts a resident on first access (60s idle timeout) — file-lock conflicts are automatically avoided. Explicit open/close is still recommended for longer sessions (12min idle):

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.

⚠️ Resident mode + one-shot shell execution

A one-shot command runner (shell_exec, or any context that spawns a fresh shell per call) interacts badly with the resident process. create auto-starts a resident and returns "kept open in background"; if the shell then exits without an explicit close, that resident can outlive its shell session as a half-dead orphan holding the file lock. A follow-up open in a new shell then blocks trying to reach that orphan and times out (observed: first-run 120s timeout; clean retry succeeds). The reliable fixes:

1. Always pair create/open with a close in the same invocation. Chain the whole write cycle with the shell's sequence operator, and skip the redundant open (the resident is already running after create):

``bash officecli create report.docx --force ; officecli add report.docx /body --type paragraph --prop text="Title" --prop style=Heading1 ; officecli close report.docx ` Or use officecli batch to apply many ops in a single save cycle (still end with close`).

1. Use a persistent shell session. When the host supports shell_session_begin / shell_session_exec, open a session once, run each officecli step as its own shell_session_exec against the same session_id, then shell_session_end. The resident stays cleanly attached to the long-lived shell, so there is no orphan between calls.

Notes: create must carry --force when the file may already exist; appending to an already-closed file across calls with add ; close is fine (a fresh resident auto-starts).

---

Quick Start

PPT:

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:

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:

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

officecli create                # Create blank .docx/.xlsx/.pptx (type from extension)
officecli view            # outline | stats | issues | text | annotated | html
officecli get   --depth N # Get a node and its children [--json]
officecli query       # CSS-like query
officecli validate              # Validate against OpenXML schema

view modes

| Mode | Description | Useful flags | |------|-------------|-------------| | outline | Document structure | | | stats | Statistics (pages, words, shapes) | | | issues | Formatting/content/structure problems | --type format\|content\|structure, --limit N | | text | Plain text extraction | --start N --end N, --max-lines N | | annotated | Text with formatting annotations | | | html | Static HTML snapshot — same renderer as watch, no server needed | --browser, --page N (docx), --start N --end N (pptx) | | screenshot / svg / pdf / forms | PNG via headless browser / SVG (pptx slide) / PDF via exporter plugin / form-fields JSON via format-handler plugin | -o, --screenshot-width/-height, pptx --grid N |

Use view html for one-shot snapshots (CI artifacts, archival, diffing); use watch when you need live refresh or browser-side click-to-select.

get

Any XML path via element localName. Use --depth N to expand children. Add --json for structured output. Default text output is grep-friendly: path (type) "text" key=val key=val ...

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 @attr=value 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 @name= (e.g. shape[@name=Title 1]), with morph !! prefix awareness. Elements without stable IDs (slide, run, tr/tc, row) fall back to positional indices.

query

CSS-like selectors: [attr=value], [attr!=value], [attr~=text], [attr>=value], `[attr 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  [--port N]      # Start preview server (default port 26315)
officecli unwatch                # Stop
officecli goto             # Scroll watching browser(s) to element (docx: p / table / tr / tc)

Open the printed http://localhost:N 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).

get selected — read what the user clicked

officecli get  selected [--json]

Returns DocumentNodes for whatever is currently selected. Empty result if nothing selected. Exit code != 0 if no watch is running.

# 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 @id= 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: .pptx shapes/pictures/tables/charts/connectors/groups; .docx top-level paragraphs and tables. Inherited layout/master decorations and Word nested elements (table cells, run-level) are not addressable. .xlsx does not emit data-path — mark/selection on xlsx always resolve stale=true (v2 candidate).

Marks — edit proposals waiting for review

Use mark when changes need human review BEFORE they hit the file. Marks live in the watch process only; a separate set pipeline applies accepted ones. For one-shot changes use set directly; for permanent file annotations use add --type comment (Word native).

officecli mark   [--prop find=... color=... note=... tofix=... regex=true] [--json]
officecli unmark  [--path  | --all] [--json]
officecli get-marks  [--json]

Props: find (literal or regex when regex=true; raw form find='r"[abc]"'), color (hex / rgb(...) / 22 named whitelist), note, tofix (drives apply pipeline). Path must be data-path format from watch HTML — see subskills for full pipeline.

---

L2: DOM Operations

set — modify properties

officecli set   --prop key=value [--prop ...]

Any XML attribute is settable via element path (found via get --depth N) — even attributes not currently present. Without find=, set applies format to the entire element.

Value formats:

| Type | Format | Examples | |------|--------|---------| | Colors | Hex (with/without #), named, RGB, theme | FF0000, #FF0000, red, rgb(255,0,0), accent1..accent6 | | Spacing | Unit-qualified | 12pt, 0.5cm, 1.5x, 150% | | Dimensions | EMU or suffixed | 914400, 2.54cm, 1in, 72pt, 96px |

Dotted-attr aliases — font. 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 for the full list.

find — format or replace matched text

Use find= with set to target specific text for formatting or replacement. Format props are separate --prop flags — do NOT nest them.

# Format matched text (auto-splits runs)
officecli set doc.docx '/body/p[1]' --prop find=weather --prop bold=true --prop color=red

# Regex matching
officecli set doc.docx '/body/p[1]' --prop 'find=\d+%' --prop regex=true --prop color=red

# Replace text (use `/` for whole-document scope)
officecli set doc.docx / --prop find=draft --prop replace=final

# PPT — same syntax, different paths
officecli set slides.pptx / --prop find=draft --prop replace=final

Path controls search scope: / = whole document, /body/p[1] or /slide[N]/shape[M] = specific element, /header[1] / /footer[1] = 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. --json includes "matched": N
• Excel: only find + replace supported (no find + format props)

add — add elements or clone

officecli add   --type  [--prop ...]
officecli add   --type  --after  [--prop ...]   # insert after anchor
officecli add   --type  --before  [--prop ...]  # insert before anchor
officecli add   --type  --index N [--prop ...]        # 0-based position (legacy)
officecli add   --from                                # clone existing element

--after, --before, --index 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, 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|bySeries, line dropLines/hiLowLines/upDownBars, anchor=x,y,w,h shorthand), table (cell direction=rtl, fill/background, built-in PowerPoint style catalogue, /col[C] get + swap/copyFrom, row/col Move/CopyFrom), row (tr), connector (from/to accept @name=, startshape/endshape SetByPath), group (link, tooltip, deep walk by get/query/add/remove), video/audio (loop, autoStart alias), equation, notes (direction=rtl, lang), comment (legacy + modern p188 threaded round-trip), animation (15 emphasis + 16 exit presets, multi-effect chains, motion-path presets, repeat/restart/autoReverse, chart animations), transition (12 p15 presets + morph/p14), paragraph (para), run, zoom, ole (preview=, full dump round-trip via add-part+raw-set), placeholder (phType=...), model3d (rotation=ax,ay,az; full dump round-trip), smartart (dump round-trip via add-part). | | 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 — /revision[@author=X] selector for filtered accept/reject), table (direction=rtl, hMerge, 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 (full Add+Get; geometry, fill, line, wrap, alt, anchor). docDefaults.rtl, autoHyphenation, get / exposes locale + /comments /footnotes /endnotes. create --minimal 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, [@name=X]; formula-body inlined at parse), pivottable (cache CoW + cross-pivot sharing, labelFilter, topN, fillDownLabels, calculatedField), sparkline, validation, autofilter, shape, textbox, CF (databar/colorscale/iconset/formulacf/cellIs/topN/aboveAverage), ole, csv. Query supports merge/mergedrange. Workbook: password. Shape selector enumerates leaves inside grpSp. |

Pivot tables (xlsx)

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: rows, cols, values (Field:func[:showDataAs]), filters, source, position, layout (compact/outline/tabular), repeatLabels, blankRows, aggregate, showDataAs (percentoftotal/row/col, running_total), grandTotals, subtotals, sort. Aggre

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zhu1090093659
• Source: zhu1090093659/deepseek-pp
• License: Apache-2.0
• Homepage: https://chromewebstore.google.com/detail/deepseek++/kdmpkkahkhdmdhfkdihkopikgcocbpbf?hl=zh-CN&authuser=0

Install and usage instructions live in the source repository linked above.