officecli

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

Install

If

officecli

macOS / Linux

if ! command -v officecli >/dev/null 2>&1; then
    curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash
fi

Windows (PowerShell)

if (-not (Get-Command officecli -ErrorAction SilentlyContinue)) {
    irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex
}

Verify:

officecli --version

If

officecli

Strategy

L1 (read) → L2 (DOM edit) → L3 (raw XML). Always prefer higher layers. Add

--json

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

docx

xlsx

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

outline

stats

issues

--type format|content|structure

--limit N

text

--start N --end N

--max-lines N

annotated

get

Any XML path via element localName. Use

--depth N

--json

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

Stable ID Addressing

Elements with stable IDs return

@attr=value

Returned path format (output):

/slide[1]/shape[@id=550950021]                    # PPT shape (cNvPr.Id)
/slide[1]/shape[@id=550950021]/paragraph[1]       # child inherits parent's @id=
/slide[1]/table[@id=1388430425]/tr[1]/tc[2]       # PPT table
/body/p[@paraId=1A2B3C4D]                         # Word paragraph
/comments/comment[@commentId=1]                    # Word comment
/footnote[@footnoteId=2]                           # Word footnote
/endnote[@endnoteId=1]                             # Word endnote
/body/sdt[@sdtId=123456]                           # Word content control

All formats accepted as input — use returned paths directly for subsequent

set

remove

officecli set slides.pptx '/slide[1]/shape[@id=550950021]' --prop bold=true
officecli set slides.pptx '/slide[1]/shape[@name=Title 1]' --prop text="New"   # @name= also works (PPT)
officecli set slides.pptx '/slide[1]/shape[2]' --prop color=red                # positional still works

Elements without stable IDs (slide, paragraph, run, tr/tc, row) use positional indices as fallback.

When to use stable IDs: Prefer

@id=

@paraId=

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

--start

--end

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

Without

find=

set

find=

Run

officecli <format> set

officecli <format> set <element>

Value formats:

FF0000

red

rgb(255,0,0)

accent1

accent6

12pt

0.5cm

1.5x

150%

914400

2.54cm

1in

72pt

96px

find — format or replace matched text

Use

find=

set

regex=true

--prop

--prop bold=true

--prop format=bold:true

# Format matched text (auto-splits runs)
officecli set doc.docx '/body/p[1]' --prop find=weather --prop highlight=yellow
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
officecli set doc.docx / --prop find=draft --prop replace=final

# Replace + format
officecli set doc.docx '/body/p[1]' --prop find=TODO --prop replace=DONE --prop bold=true

# Bulk: color all dates red across all paragraphs
officecli set doc.docx / --prop 'find=\d{4}-\d{2}-\d{2}' --prop regex=true --prop color=red

# Replace in header
officecli set doc.docx '/header[1]' --prop find=Draft --prop replace=Final

PPT find works the same way:

# Format matched text
officecli set slides.pptx '/slide[1]/shape[1]' --prop find=weather --prop bold=true --prop color=red

# Regex
officecli set slides.pptx '/slide[1]/shape[1]' --prop 'find=\d+%' --prop regex=true --prop color=red

# Replace across all slides
officecli set slides.pptx / --prop find=draft --prop replace=final

# Replace + format
officecli set slides.pptx '/slide[1]/shape[1]' --prop find=TODO --prop replace=DONE --prop bold=true

# Replace in table
officecli set slides.pptx '/slide[1]/table[1]' --prop find=old --prop replace=new

Path controls search scope:

/

/slide[N]

/slide[N]/shape[M]

/slide[N]/table[M]

/slide[N]/notes

Known limitation: Notes pane find+format writes correctly, but

get

returns plain text only — run-level formatting cannot be verified via CLI.

Behavior matrix:

find

find

replace

find

replace

• Add

  regex=true

  to enable regex matching:

  --prop 'find=\d+%' --prop regex=true

  • Batch JSON:

    {"props":{"find":"\\d+%","regex":"true","color":"FF0000"}}

• Path controls search scope:

  /

  = body only (excludes headers/footers),

  /header[1]

  = first header,

  /footer[1]

  = first footer,

  /body/p[1]

  = specific paragraph, etc.
• If

  find=

  matches nothing, the command succeeds with no changes (no error)

• --json

  output includes a

  "matched": N

  field indicating the number of matches found
• Matching is case-sensitive by default. For case-insensitive, use regex:

  --prop 'find=(?i)error' --prop regex=true

• find:

  /

  find=

  matches work across run boundaries — text split across multiple runs is still found

Excel limitations: Excel only supports

find

replace

find

find

replace

add — add elements or clone

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 ...]        # insert at position (legacy)
officecli add <file> <parent> --from <path>                               # clone existing element

Insert position (

--after

--before

--index

• --after "p[@paraId=1A2B3C4D]"

  — insert after the anchor element (short or full path)

• --before "/body/p[@paraId=5E6F7A8B]"

  — insert before the anchor element

• --index N

  — insert at 0-based position (legacy, prefer --after/--before)
• No position flag — append to end (default)

Element types (with aliases):

Text-anchored insert (

--after find:X

--before find:X

The

--after

--before

find:

# Insert run after matched text (inline, within the same paragraph)
officecli add doc.docx '/body/p[1]' --type run --after find:weather --prop text=" (sunny)"

# Insert table after matched text (block — auto-splits the paragraph)
officecli add doc.docx '/body/p[1]' --type table --after "find:First sentence." --prop rows=2 --prop cols=2

# Insert before matched text
officecli add doc.docx '/body/p[1]' --type run --before find:weather --prop text="["

• Inline types (run, picture, hyperlink...) insert within the paragraph
• Block types (table, paragraph) auto-split the paragraph and insert between the two halves

PPT text-anchored insert (inline only):

officecli add slides.pptx '/slide[1]/shape[1]' --type run --after find:weather --prop text=" (sunny)"
officecli add slides.pptx '/slide[1]/shape[1]' --type run --before find:weather --prop text="["

PPT only supports inline types (run) with

find:

Clone:

officecli add <file> / --from '/slide[1]'

Run

officecli <format> add

move, swap, remove

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

--after

--before

--to

batch — multiple operations in one save cycle

Stops on first error by default. Use

--force

# Via stdin
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

# Via --commands (inline, no stdin needed)
officecli batch data.xlsx --commands '[{"op":"set","path":"/Sheet1/A1","props":{"value":"Done"}}]' --json

# Via --input (file)
officecli batch data.xlsx --input updates.json --force --json

Batch supports:

add

set

get

query

remove

move

swap

view

raw

raw-set

validate

Batch fields:

command

op

path

parent

type

from

to

index

after

before

props

selector

mode

depth

part

xpath

action

xml

JSON output is wrapped in an envelope:

{"results": [...], "summary": {"total", "executed", "succeeded", "failed", "skipped"}}

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

Common Pitfalls

--name "foo"

--prop name="foo"

--prop

x=-3cm

x=0cm

x=36cm

shape[1]

shape[1]

shape[2]

/shape[myname]

/shape[3]

officecli <format> set <element>

\n

\\n

--prop text="..."

officecli set f.pptx /slide[1]

'/slide[1]'

Specialized Skills

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

officecli-docx

officecli-academic-paper

officecli-pptx

officecli-pitch-deck

morph-ppt

officecli-xlsx

officecli-data-dashboard

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