-
Notifications
You must be signed in to change notification settings - Fork 528
command add
zmworm edited this page Apr 29, 2026
·
54 revisions
Add a new element to the document.
officecli add <file> <parent> --type <type> [--index N] [--prop key=value ...]
officecli add <file> <parent> --type <type> [--after <path-or-find>] [--prop key=value ...]
officecli add <file> <parent> --type <type> [--before <path-or-find>] [--prop key=value ...]
officecli add <file> <parent> --from <source-path> [--index N]
Adds a new element to the document at the specified parent path. You can either create a new element with --type and --prop, or copy an existing element with --from. Returns the path to the newly created element.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
file |
FileInfo | Yes | - | Office document path |
parent |
string | Yes | - | Parent DOM path where the element will be inserted |
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
--type |
string | Yes (unless --from) |
- | Element type to create |
--from |
string | No | - | Path to an existing element to copy (alternative to --type) |
--index |
int | No | append to end | Insert position (0-based) |
--after |
string | No | - | Insert after element path or find:text (add --prop regex=true for regex) |
--before |
string | No | - | Insert before element path or find:text (add --prop regex=true for regex) |
--prop |
string (repeatable) | No | - | Property in key=value format |
Either --type or --from must be specified. Position is determined by --index, --after, or --before (mutually exclusive).
# Insert a new paragraph at the end of document body officecli add report.docx /body --type paragraph --prop text="New paragraph" # Insert a paragraph after the 2nd paragraph (by DOM path) officecli add report.docx /body --type paragraph --after /body/p[2] --prop text="Inserted here" # Insert a row at the end of a table officecli add report.docx /body/tbl[1] --type row # Insert a picture into a paragraph officecli add report.docx '/body/p[1]' --type picture --prop file=logo.png # Add a new slide at position 2 officecli add slides.pptx / --type slide --index 1 # Add a text box to slide 1 officecli add slides.pptx /slide[1] --type shape --prop text="Hello" --prop left=100 --prop top=100
Properties that accept file input (src, path, data, poster, etc.) support three source formats:
| Format | Example |
|---|---|
| Local file path | --prop src=/tmp/photo.png |
| HTTP(S) URL | --prop src=https://example.com/video.mp4 |
| Data URI (base64) | --prop "src=data:image/png;base64,iVBOR..." |
This applies to images, media (video/audio), 3D models, CSV table data, and any other file-based property.
-
Word add - All addable elements in
.docx -
Excel add - All addable elements in
.xlsx -
PowerPoint add - All addable elements in
.pptx
Use --after or --before with a DOM path to insert relative to a sibling element:
# Insert a paragraph after the 3rd paragraph officecli add report.docx /body --type paragraph --after /body/p[3] --prop text="After p3" # Insert a paragraph before a table officecli add report.docx /body --type paragraph --before /body/tbl[1] --prop text="Table intro" # Insert a slide before slide 2 officecli add slides.pptx / --type slide --before /slide[2]
Copies an existing element. --from cannot be combined with --type or --prop — it is a full clone of the source element.
officecli add slides.pptx / --from /slide[1] officecli add slides.pptx /slide[2] --from /slide[1]/shape[1] officecli add report.docx /body --from /body/p[1] --index 5
Insert elements at text positions within a paragraph. Use find: prefix to locate the insertion point by matching text content. Add --prop regex=true for regex matching.
- Word inline types (run, image, hyperlink, bookmark, field): inserted within the paragraph, adjacent to the matched text.
- Word block types (table, paragraph, section, break): the paragraph is automatically split at the match point; the new block element is inserted between the two halves.
-
PowerPoint: only inline insertion (
runtype) is supported withfind:anchoring. Block types are not supported and will result in an error.
# Word: insert run after matched text officecli add report.docx '/body/p[1]' --type run --after find:weather --prop "text= (sunny)" # Word: insert table after matched text (splits paragraph) officecli add report.docx '/body/p[1]' --type table --after "find:first sentence." --prop rows=2 --prop cols=3 # Word: insert before matched text officecli add report.docx '/body/p[1]' --type run --before find:weather --prop "text=[" # Word: regex anchor officecli add report.docx '/body/p[1]' --type run --after 'find:\d+' --prop regex=true --prop "text= (new high)" # PPT: insert run after matched text in shape officecli add slides.pptx '/slide[1]/shape[1]' --type run --after find:weather --prop "text= (sunny)"
- Command Reference
- set - Modify existing elements
- remove - Remove elements
Based on OfficeCLI v1.0.64