Skip to content

command add

Jump to bottom
zmworm edited this page Apr 29, 2026 · 54 revisions

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 (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).

Quick Start

# 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

Input Sources

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.

Format-Specific References

Position by DOM Path (--after / --before)

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]

Copy Mode (--from)

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

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

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 (run type) is supported with find: 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)"

See Also

Based on OfficeCLI v1.0.64

Clone this wiki locally