command add

add

Add a new element to the document.

Synopsis

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]

Description

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.

Arguments

Name	Type	Required	Default	Description
file	FileInfo	Yes	-	Office document path
parent	string	Yes	-	Parent DOM path where the element will be inserted

Options

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 / find:r"regex"
--before	string	No	-	Insert before element path or find:text / find:r"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).

Format-Specific References

• Word add - All addable elements in .docx
• Excel add - All addable elements in .xlsx
• PowerPoint add - All addable elements in .pptx

Copy Mode (--from)

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

Text-Anchored Insert (--after find: / --before find:)

Insert elements at text positions within a paragraph. Word supports inline types (run, image, hyperlink, bookmark, field) and block types (table, paragraph, section, break — auto-splits paragraph). PowerPoint supports inline run insertion.

# Word: insert run after matched text
officecli add report.docx '/body/p[1]' --type run --after find:天气 --prop text=（晴）

# Word: insert table after matched text (splits paragraph)
officecli add report.docx '/body/p[1]' --type table --after find:第一句话。 --prop rows=2 --prop cols=3

# Word: insert before matched text
officecli add report.docx '/body/p[1]' --type run --before find:天气 --prop text=【

# Word: regex anchor
officecli add report.docx '/body/p[1]' --type run --after 'find:r"\d+"' --prop text=（新高）

# PPT: insert run after matched text in shape
officecli add slides.pptx '/slide[1]/shape[1]' --type run --after find:天气 --prop text=（晴）

See Also

• Command Reference
• set - Modify existing elements
• remove - Remove elements

---

Based on OfficeCLI v1.0.33