OfficeCLI Path-Based Addressing Syntax: How to Navigate Office Documents with XPath-Style Paths

OfficeCLI path-based addressing syntax uses an XPath-inspired string format to locate any element within PowerPoint, Word, or Excel documents through a combination of root selectors, element names, positional indexes, and attribute filters.

The iOfficeAI/OfficeCLI repository implements a uniform path-based addressing syntax that enables precise targeting of document elements across multiple Office formats. This lightweight addressing model treats document hierarchies as navigable tree structures, allowing automation scripts to reference specific slides, shapes, tables, or cells using plain-text strings. Unlike full XPath implementations, the parser operates on a flat list of tokens without namespace handling, making it ideal for command-line interfaces and CI/CD pipelines.

Core Components of the Addressing Syntax

Root and Element Names

Every address begins with the root forward slash /, which serves as a read-only container representing the document entry point. Valid element names vary by format but include slide, shape, group, table, chart, textbox, picture, and body. As documented in README.md, the root itself is never modified directly; rather, you address its children to perform operations. Certain top-level containers like presentation, document, and workbook are also read-only and addressed implicitly through their parent root.

Positional Indexing

Select specific instances using 1-based numeric indexes in square brackets. The syntax /slide[2] targets the second slide in a presentation, while /body/textbox[3] selects the third text box in a Word document according to examples/word/textbox.md. Be aware that numeric indexes shift when elements are added or removed, making them less stable than named references for long-term automation.

Attribute Selectors

For stable addressing that survives reordering, use attribute selectors with the [@name=...] or [@id=...] syntax. The skills/officecli-pptx/SKILL.md file demonstrates that naming elements creates persistent addresses—for example, /shape[@name=HeroTitle] maintains validity even when slides are rearranged. This approach is recommended for automation scripts that require idempotent operations across multiple executions.

Special Functions

The syntax currently supports the last() function, which evaluates to the most recently added element of a given type. This is particularly useful when adding new elements and immediately configuring them, such as /slide[last()] to target the slide just appended to a presentation. The function resolves to the highest available index for the specified element type.

Format-Specific Addressing Patterns

PowerPoint Presentations

PowerPoint documents use hierarchical paths that can traverse groups and nested shapes. The examples/ppt/tables/tables-nested.md file illustrates deep addressing like /slide[2]/group[@name=G]/shape[1], which navigates into grouped objects. When working with slides, you can combine positional and named selectors: /slide[N]/shape[@name=Logo] provides both specificity and stability across edits.

Word Documents

Word documents organize content under the /body element. According to examples/word/textbox.md, text boxes are addressed as /body/textbox[N], while other elements like paragraphs, tables, and charts appear as siblings within this container. Comments and other annotations can be targeted using attribute selectors such as /slide[2]/comment[@name=ReviewerNote].

Excel Workbooks

Excel uses a sheet-specific addressing model where worksheets are addressed directly under the root by name. As shown in examples/excel/sparklines.md, paths follow the pattern /Sheet1/table[@name=Sales] or /Sheet1/sparkline[N]. Cells within tables can be targeted using coordinate-based indexes like /cell[2,3] to modify specific row-column intersections.

Practical Command Examples

The following examples demonstrate real-world usage of the OfficeCLI path-based addressing syntax. Replace $FILE with your actual document path:

Create a slide and immediately configure it using the last() function:

officecli add "$FILE" --type slide
officecli set "$FILE" "/slide[last()]" --prop title="Quarterly Review"

Create a named shape for stable future reference:

officecli add "$FILE" "/slide[1]" --type shape --prop name=Logo --prop preset=ellipse
officecli set "$FILE" "/slide[1]/shape[@name=Logo]" --prop fill=red

Update Excel table cells by name:

officecli set "$FILE" "/Sheet1/table[@name=Sales]/cell[2,3]" --prop value=12345

Modify PowerPoint element properties:

officecli set "$FILE" "/slide[2]/picture[3]" --prop fill=blue

Reorder elements using positional indexes:

officecli move "$FILE" "/slide[1]/shape[5]" --to "/slide[1]/shape[2]"

Remove elements by name:

officecli remove "$FILE" "/slide[2]/comment[@name=ReviewerNote]"

Summary

• OfficeCLI path-based addressing syntax uses / as the root, followed by element names, positional indexes [N], and attribute selectors [@name=...] or [@id=...].
• The last() function targets the most recently added element of a specified type.
• PowerPoint supports deep nesting through groups with paths like /slide[2]/group[@name=G]/shape[1].
• Word documents require the /body prefix for content elements as implemented in examples/word/textbox.md.
• Excel addresses sheets by name directly under root, followed by element types like table or sparkline.
• Named attributes provide stable addresses that survive reordering, while numeric indexes are volatile but useful for positional operations.

Frequently Asked Questions

What characters are allowed in the OfficeCLI path-based addressing syntax?

The syntax accepts alphanumeric element names, forward slashes as separators, square brackets for indexing, and equals signs within attribute predicates. Paths are treated as flat token lists without namespace support or complex XPath predicates, keeping the grammar simple for command-line usage. Special characters in names should be handled according to standard shell escaping rules when passing arguments.

How does the last() function work in OfficeCLI addressing?

The last() function evaluates to the highest index of the specified element type, effectively targeting the most recently added element. For example, /slide[last()] selects the final slide in a presentation, making it useful for immediate configuration after adding new content without knowing the total count. This function is implemented uniformly across all supported document formats.

Can I use OfficeCLI path-based addressing syntax across all Office formats?

Yes, the syntax is uniform across PowerPoint, Word, and Excel, though element names vary by format. PowerPoint uses slide and shape, Word uses body as a container, and Excel uses sheet names as direct children of root. All formats support the same indexing and attribute selection mechanisms as documented in the respective examples/ directories.

Why should I use [@name=...] instead of positional indexes?

Attribute selectors create stable addresses that persist when other elements are added, removed, or reordered. Positional indexes [N] are 1-based and shift when the document structure changes, requiring script updates. The examples/ppt/textboxes/textboxes-advanced.md file demonstrates how named elements maintain valid references across document modifications, making them essential for reliable automation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}