officecli

name	officecli
description	Create, analyze, proofread, and modify Office documents (.docx, .xlsx, .pptx) using the officecli CLI tool. Use when the user wants to create, inspect, check formatting, find issues, add charts, or modify Office documents.

officecli

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

Install & Update

Same command for both install and upgrade:

# 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

After installation, run source ~/.zshrc (macOS) or source ~/.bashrc (Linux) to make the officecli command available.

Verify: officecli --version

officecli auto-updates daily in the background.

---

Automation Policy

Act without asking for:

• Any read/inspect op (view, get, query, validate, stats) on any file
• create on a path that does not yet exist
• add / set on a local file the user named or just created
• remove / move / swap when the user explicitly named the target (e.g. "remove paragraph 4", "swap slides 2 and 5")
• clone via --from (non-destructive — original is untouched)
• Resident-mode open/close wrapping when issuing 3+ commands on the same file
• Batch mode when issuing 5+ operations on the same file

Pause and confirm before:

• create on a path that already exists ([[ -f <file> ]] → alert and stop)
• remove / move / swap on content not explicitly specified by the user
• Writing to a path outside the working directory or a shared/network location
• Gateway or external API calls

Always verify after any modification sequence:

officecli validate <file> && officecli view <file> issues --limit 10 || echo "VALIDATION FAILED — see errors above"

If validate exits non-zero, report the exact error and stop; do not silently continue.

---

Strategy

L1 (read) -> L2 (DOM edit) -> L3 (raw XML). Always prefer higher layers. Add --json for structured output.

---

Help System (IMPORTANT)

When unsure about property names, value formats, or command syntax, ALWAYS run help instead of guessing. One help query is faster than guess-fail-retry loops.

Three-layer navigation -- start from the deepest level you know:

officecli pptx set              # All settable elements and their properties
officecli pptx set shape        # Shape properties in detail
officecli pptx set shape.fill   # Specific property format and examples

Replace pptx with docx or xlsx. Commands: view, get, query, set, add, raw.

---

Performance: Resident Mode

For multi-step workflows (3+ commands on the same file), automatically use resident mode — no need to ask:

officecli open report.docx       # keep in memory — fast subsequent commands
officecli set report.docx ...    # no file I/O overhead
officecli close report.docx      # save and release

---

Quick Start

PPT:

officecli create slides.pptx
officecli open 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
officecli set slides.pptx /slide[1] --prop transition=fade --prop advanceTime=3000
officecli close slides.pptx
officecli validate slides.pptx && officecli view slides.pptx issues --limit 10 || echo "VALIDATION FAILED"

Word:

officecli create report.docx
officecli open 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."
officecli close report.docx
officecli validate report.docx && officecli view report.docx issues --limit 10 || echo "VALIDATION FAILED"

Excel:

officecli create data.xlsx
officecli open data.xlsx
officecli set data.xlsx /Sheet1/A1 --prop value="Name" --prop bold=true
officecli set data.xlsx /Sheet1/B1 --prop value="Score" --prop bold=true
officecli set data.xlsx /Sheet1/A2 --prop value="Alice"
officecli set data.xlsx /Sheet1/B2 --prop value=95
officecli close data.xlsx
officecli validate data.xlsx && officecli view data.xlsx stats || echo "VALIDATION FAILED"

---

L1: Create, Read & Inspect

officecli create <file>               # Create blank .docx/.xlsx/.pptx (type from extension)
officecli view <file> <mode>          # outline | stats | issues | text | annotated
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
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

get

Any XML path via element localName. Use --depth N to expand children. Add --json for structured output.

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

Run officecli docx get / officecli xlsx get / officecli pptx get for all available paths.

query

CSS-like selectors: [attr=value], [attr!=value], [attr~=text], [attr>=value], [attr<=value], :contains("text"), :empty, :has(formula), :no-alt.

officecli query report.docx 'paragraph[style=Normal] > run[font!=Arial]'
officecli query slides.pptx 'shape[fill=FF0000]'

validate

officecli validate report.docx    # Check for schema errors
officecli validate slides.pptx    # Must pass before delivery

For large documents, ALWAYS use --max-lines or --start/--end to limit output.

---

L2: DOM Operations

set — modify properties

officecli set <file> <path> --prop key=value [--prop ...]

Any XML attribute is settable via element path (found via get --depth N) — even attributes not currently present.

Run officecli <format> set for all settable elements. Run officecli <format> set <element> for detail.

Value formats:

Type	Format	Examples
Colors	Hex, named, RGB, theme	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

add — add elements or clone

officecli add <file> <parent> --type <type> [--index N] [--prop ...]
officecli add <file> <parent> --from <path> [--index N]    # clone existing element

Element types (with aliases):

Format	Types
pptx	slide, shape (textbox), picture (image/img), chart, table, row (tr), connector (connection/line), group, video (audio/media), equation (formula/math), notes, paragraph (para), run, zoom (slidezoom)
docx	paragraph (para), run, table, row (tr), cell (td), image (picture/img), header, footer, section, bookmark, comment, footnote, endnote, formfield, sdt (contentcontrol), chart, equation (formula/math), field, hyperlink, style, toc, watermark, break (pagebreak/columnbreak)
xlsx	sheet, row, cell, chart, image (picture), comment, table (listobject), namedrange (definedname), pivottable (pivot), sparkline, validation (datavalidation), autofilter, shape, textbox, databar/colorscale/iconset/formulacf (conditional formatting), csv (tsv)

Clone: officecli add <file> / --from /slide[1] — copies with all cross-part relationships.

Run officecli <format> add for all addable types and their properties.

move, swap, remove

officecli move <file> <path> [--to <parent>] [--index N]
officecli swap <file> <path1> <path2>
officecli remove <file> '/body/p[4]'

batch — multiple operations in one save cycle

Use batch automatically for 5+ operations on the same file (fewer round-trips, single save):

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

Batch supports: add, set, get, query, remove, move, view, raw, raw-set, validate.

Batch fields: command, path, parent, type, from, to, index, props (dict), selector, mode, depth, part, xpath, action, xml.

---

L3: Raw XML

Use when L2 cannot express what you need. No xmlns declarations needed — prefixes auto-registered.

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)

raw-set actions: append, prepend, insertbefore, insertafter, replace, remove, setattr.

Run officecli <format> raw for available parts per format.

---

Failure Recovery

Symptom	Recovery
officecli: command not found	Re-run install script; then source ~/.zshrc
validate exits non-zero	Run officecli raw <file> <part> to inspect the offending part; fix via raw-set or undo the last L2 op
validate passes but view issues reports problems	Address issues before delivery; use --type format|content|structure to filter
Path not found (/slide[3] etc.)	Run officecli get <file> / to list available paths
File locked / permission denied	Close the file in PowerPoint/WPS/Excel first
set silently ignores a property	Run officecli <format> set <element>.<property> to confirm exact property name
create on existing file	Stop; confirm with user before overwriting

---

Common Pitfalls

Pitfall	Correct Approach
--name "foo"	❌ Use --prop name="foo" — all attributes go through --prop
x=-3cm	❌ Negative coordinates not supported. Use x=0cm or x=36cm
/shape[myname]	❌ Name indexing not supported. Use numeric index: /shape[3]
Guessing property names	❌ Run officecli <format> set <element> to see exact names
Modifying an open file	❌ Close the file in PowerPoint/WPS first
\n in shell strings	❌ Use \\n for newlines in --prop text="..."

---

Specialized Skills

This skill covers the officecli CLI basics. For complex scenarios, load the dedicated skill for better results:

Scenario	Skill	Min Version	When to Use
Word documents	officecli-docx	v1.0.23	Create, read, edit .docx — reports, letters, memos, proposals
Academic papers	officecli-academic-paper	v1.0.24	Research papers, white papers with TOC, equations, footnotes, bibliography
Presentations	officecli-pptx	v1.0.23	Create, read, edit .pptx — general slide decks
Pitch decks	officecli-pitch-deck	v1.0.24	Investor decks, product launches, sales decks with charts and stat callouts
Morph PPT	morph-ppt	v1.0.24	Morph-animated cinematic presentations
Excel	officecli-xlsx	v1.0.23	Create, read, edit .xlsx — financial models, trackers, formulas
Data dashboards	officecli-data-dashboard	v1.0.24	CSV/tabular data → Excel dashboards with KPI cards, charts, sparklines

How to load: Ask your AI tool to enable the skill by name, or load the skill file from skills/<skill-name>/SKILL.md.

---

Notes

• Paths are 1-based (XPath convention): '/body/p[3]' = third paragraph
• --index is 0-based (array convention): --index 0 = first position
• After modifications, run validate then view issues — don't skip
• When unsure, run officecli <format> <command> [element[.property]] instead of guessing