| name | stella-office |
| description | Create, analyze, proofread, and modify Office documents (.docx, .xlsx, .pptx) using Stella's bundled `stella-office` CLI. Use when the user wants to create, inspect, check formatting, find issues, add charts, or modify Office documents. |
stella-office
AI-friendly CLI for .docx, .xlsx, .pptx. Stella bundles this command directly into exec_command. No Office installation and no separate CLI install flow.
Availability
- Call
stella-office through exec_command with cmd: "stella-office ...". Stella auto-injects the binary into shell PATH.
- If the command is unexpectedly unavailable, the bundled binary for this platform may not be present yet.
- For live chat previews inside Stella, use
exec_command with cmd: "stella-office preview <file>".
{ "cmd": "stella-office docx view /abs/path/report.docx text" }
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:
stella-office pptx set
stella-office pptx set shape
stella-office pptx set shape.fill
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:
stella-office open report.docx
stella-office set report.docx /body/p[1]/r[1] --prop bold=true
stella-office set report.docx /body/p[2]/r[1] --prop color=FF0000
stella-office close report.docx
Inline Live Preview
Use this when you want Stella to keep a document preview embedded in chat while you continue editing the underlying file.
stella-office preview slides.pptx
stella-office preview report.docx
stella-office preview budget.xlsx --interval-ms 1000
Notes:
preview is Stella-specific wrapper behavior. It is not an upstream OfficeCli subcommand.- The command starts a Stella-owned preview session and returns immediately.
- Stella watches the document and refreshes the inline preview automatically as the file changes.
- Use it before or during multi-step edit workflows when visual feedback matters.
Quick Start
PPT:
stella-office create slides.pptx
stella-office add slides.pptx / --type slide --prop title="Q4 Report" --prop background=1A1A2E
stella-office 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
stella-office set slides.pptx '/slide[1]' --prop transition=fade --prop advanceTime=3000
Word:
stella-office create report.docx
stella-office add report.docx /body --type paragraph --prop text="Executive Summary" --prop style=Heading1
stella-office add report.docx /body --type paragraph --prop text="Revenue increased by 25% year-over-year."
Excel:
stella-office create data.xlsx
stella-office set data.xlsx /Sheet1/A1 --prop value="Name" --prop bold=true
stella-office set data.xlsx /Sheet1/B1 --prop value="Score" --prop bold=true
stella-office set data.xlsx /Sheet1/A2 --prop value="Alice"
stella-office set data.xlsx /Sheet1/B2 --prop value=95
L1: Create, Read, and Inspect
stella-office create <file>
stella-office view <file> <mode>
stella-office get <file> <path> --depth N
stella-office query <file> <selector>
stella-office validate <file>
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.
stella-office get report.docx '/body/p[3]' --depth 2 --json
stella-office get slides.pptx '/slide[1]' --depth 1
stella-office get data.xlsx '/Sheet1/B2' --json
Run stella-office docx get / stella-office xlsx get / stella-office pptx get for all available paths.
Stable ID Addressing
Elements with stable IDs return @attr=value paths instead of positional indices. These paths survive insert/delete operations, so prefer them in multi-step workflows.
/slide[1]/shape[@id=550950021]
/slide[1]/shape[@id=550950021]/paragraph[1]
/slide[1]/table[@id=1388430425]/tr[1]/tc[2]
/body/p[@paraId=1A2B3C4D]
/comments/comment[@commentId=1]
/footnote[@footnoteId=2]
/endnote[@endnoteId=1]
/body/sdt[@sdtId=123456]
Use returned paths directly:
stella-office set slides.pptx '/slide[1]/shape[@id=550950021]' --prop bold=true
stella-office set slides.pptx '/slide[1]/shape[@name=Title 1]' --prop text="New"
stella-office set slides.pptx '/slide[1]/shape[2]' --prop color=red
query
CSS-like selectors: [attr=value], [attr!=value], [attr~=text], [attr>=value], [attr<=value], :contains("text"), :empty, :has(formula), :no-alt.
stella-office query report.docx 'paragraph[style=Normal] > run[font!=Arial]'
stella-office query slides.pptx 'shape[fill=FF0000]'
validate
stella-office validate report.docx
stella-office validate slides.pptx
For large documents, always use --max-lines or --start / --end to limit output.
L2: DOM Operations
set — modify properties
stella-office set <file> <path> --prop key=value [--prop ...]
Any XML attribute is settable via the element path. Without find=, set applies formatting to the whole element.
Run stella-office <format> set for all settable elements. Run stella-office <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 |
find — format or replace matched text
Use find= with set to target specific text within a paragraph or broader scope. The matched text is automatically split into its own run(s). Add regex=true for regex matching.
stella-office set doc.docx '/body/p[1]' --prop find=weather --prop highlight=yellow
stella-office set doc.docx '/body/p[1]' --prop find=weather --prop bold=true --prop color=red
stella-office set doc.docx '/body/p[1]' --prop 'find=\d+%' --prop regex=true --prop color=red
stella-office set doc.docx / --prop find=draft --prop replace=final
stella-office set doc.docx '/body/p[1]' --prop find=TODO --prop replace=DONE --prop bold=true
stella-office set doc.docx / --prop 'find=\d{4}-\d{2}-\d{2}' --prop regex=true --prop color=red
stella-office set doc.docx '/header[1]' --prop find=Draft --prop replace=Final
PPT find works the same way:
stella-office set slides.pptx '/slide[1]/shape[1]' --prop find=weather --prop bold=true --prop color=red
stella-office set slides.pptx '/slide[1]/shape[1]' --prop 'find=\d+%' --prop regex=true --prop color=red
stella-office set slides.pptx / --prop find=draft --prop replace=final
stella-office set slides.pptx '/slide[1]/shape[1]' --prop find=TODO --prop replace=DONE --prop bold=true
stella-office set slides.pptx '/slide[1]/table[1]' --prop find=old --prop replace=new
Notes:
- Path controls search scope.
- If
find= matches nothing, the command succeeds with no changes.
--json output includes a "matched" field.- Matching is case-sensitive by default.
- Excel supports
find + replace, but not find + format-only styling.
add — add elements or clone
stella-office add <file> <parent> --type <type> [--prop ...]
stella-office add <file> <parent> --type <type> --after <path> [--prop ...]
stella-office add <file> <parent> --type <type> --before <path> [--prop ...]
stella-office add <file> <parent> --type <type> --index N [--prop ...]
stella-office add <file> <parent> --from <path>
Insert position (--after, --before, --index are mutually exclusive):
--after "p[@paraId=1A2B3C4D]" — insert after the anchor element--before "/body/p[@paraId=5E6F7A8B]" — insert before the anchor element--index N — insert at 0-based position- No position flag — append to end
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) |
Text-anchored insert (--after find:X / --before find:X):
stella-office add doc.docx '/body/p[1]' --type run --after find:weather --prop text=" (sunny)"
stella-office add doc.docx '/body/p[1]' --type table --after "find:First sentence." --prop rows=2 --prop cols=2
stella-office add doc.docx '/body/p[1]' --type run --before find:weather --prop text="["
stella-office add slides.pptx '/slide[1]/shape[1]' --type run --after find:weather --prop text=" (sunny)"
stella-office add slides.pptx '/slide[1]/shape[1]' --type run --before find:weather --prop text="["
Clone example:
stella-office add slides.pptx / --from '/slide[1]'
Run stella-office <format> add for all addable types and properties.
move, swap, remove
stella-office move <file> <path> [--to <parent>] [--index N] [--after <path>] [--before <path>]
stella-office swap <file> <path1> <path2>
stella-office remove <file> '/body/p[4]'
When using --after or --before, --to can often be omitted because the target container is inferred from the anchor path.
batch — multiple operations in one save cycle
Stops on first error by default. Use --force to continue past errors.
echo '[
{"command":"set","path":"/Sheet1/A1","props":{"value":"Name","bold":"true"}},
{"command":"set","path":"/Sheet1/B1","props":{"value":"Score","bold":"true"}}
]' | stella-office batch data.xlsx --json
stella-office batch data.xlsx --commands '[{"op":"set","path":"/Sheet1/A1","props":{"value":"Done"}}]' --json
stella-office batch data.xlsx --input updates.json --force --json
Batch supports: add, set, get, query, remove, move, swap, view, raw, raw-set, validate.
L3: Raw XML
Use raw XML only when L2 cannot express what you need. No xmlns declarations are needed because prefixes are auto-registered.
stella-office raw <file> <part>
stella-office raw-set <file> <part> --xpath "..." --action replace --xml '<w:p>...</w:p>'
stella-office add-part <file> <parent>
raw-set actions: append, prepend, insertbefore, insertafter, replace, remove, setattr.
Run stella-office <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 are not supported. Use x=0cm or a positive value |
PPT shape[1] for content | shape[1] is usually the title placeholder. Use shape[2] or higher for content |
/shape[myname] | Name indexing is not supported. Use numeric index: /shape[3] |
| Guessing property names | Run stella-office <format> set <element> to see exact names |
| Modifying an open file | Close the file in PowerPoint, Word, Excel, or WPS first |
\n in shell strings | Use \\n for newlines inside --prop text="..." |
stella-office set f.pptx /slide[1] | Always single-quote paths with brackets: '/slide[1]' |
Format-Specific Extras
- Cross-format core:
create, view, get, query, set, add, remove, move, swap, raw, raw-set, validate, merge, batch, open, close
- XLSX-only:
import
- PPTX-only:
check, view svg
- DOCX-only:
view forms
When you need deeper detail, prefer the command help tree:
stella-office docx help
stella-office xlsx help
stella-office pptx help
Notes
- Paths are 1-based:
'/body/p[3]' means the third paragraph
--index is 0-based: --index 0 means the first position- After modifications, verify with
validate and/or view issues
- When unsure, run
stella-office <format> <command> [element[.property]] instead of guessing
