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.

---

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), use open/close:

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 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

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/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

---

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
xlsx	sheet, row, cell, chart, image (picture), comment, hyperlink

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

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.

---

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, verify with validate and/or view issues
• When unsure, run officecli <format> <command> [element[.property]] instead of guessing