# OfficeCLI DOM Path System: How to Construct Paths Like `/slide[1]/shape[2]`

> Master the OfficeCLI DOM path system to select elements in Office docs. Learn how to construct paths like /slide[1]/shape[2] for precise document manipulation.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-08-08

---

**The OfficeCLI DOM path system uses slash-separated element selectors in the format `<tag>[<index>]` to uniquely address elements within Word, Excel, or PowerPoint documents through a hierarchical, 1-based indexing scheme.**

The OfficeCLI DOM path system provides a unified addressing model for manipulating Office Open XML (OOXML) documents programmatically. In the iOfficeAI/OfficeCLI repository, this system allows developers to target specific elements—whether slides in PowerPoint, paragraphs in Word, or cells in Excel—using intuitive, filesystem-like syntax. Understanding how to construct valid paths such as `/slide[1]/shape[2]` is essential for automating document modifications via the command line or SDK.

## Understanding the OfficeCLI DOM Path Syntax

### Element Selector Structure

Each segment in a DOM path follows the pattern `<tag>[<index>]`, where `<tag>` represents the local name of the OOXML element (e.g., `slide`, `shape`, `paragraph`, `cell`). The parser splits the path string on forward slashes, ignoring the leading empty segment, and validates each segment against the regular expression `^([a-zA-Z]+)(\[(\d+|[A-Za-z_]\w*)\])?$`.

### 1-Based Indexing and Parameterized Paths

OfficeCLI uses **1-based indexing**, meaning `shape[1]` refers to the first shape of its type under the current parent. When the index is omitted, the parser assumes the first element of that type. The system also supports **parameterized paths** where indices can be symbolic placeholders like `I` or `myIdx`, allowing runtime substitution in scripts and loops.

## How the Path Parser Resolves DOM Addresses

The resolution engine in [`PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.cs) implements a five-step validation and traversal process:

1. **Tokenization**: The input string is split on `/` characters, discarding the leading empty segment to produce a list of selectors.
2. **Pattern Matching**: Each segment is validated against the regex `^([a-zA-Z]+)(\[(\d+|[A-Za-z_]\w*)\])?$` to extract the tag name and optional index.
3. **OOXML Resolution**: The extracted tag is mapped to the concrete OOXML part (slides, shapes, rows, cells, etc.) within the document's in-memory model.
4. **Index Conversion**: Numeric indices are converted to integers; symbolic names are stored as variables for later substitution by the caller.
5. **DOM Traversal**: The resolver walks the hierarchical object tree, throwing a `not_found` error if any step cannot be resolved in the live DOM.

This same resolution logic is reused across document types via [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) and [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs).

## Constructing Paths for Different Office Document Types

### PowerPoint Path Examples

- `/slide[1]` — Targets the first slide in the presentation.
- `/slide[3]/shape[2]` — Targets the second shape on the third slide.
- `/slide[I]/shape[2]` — Uses a parameterized index for the slide number.

### Word and Excel Equivalents

Word documents support paths like `/body/p[1]` for paragraphs or `/tbl[2]` for tables, while Excel uses `/Sheet1/cell[A1]` or `/Sheet1/row[3]` to address spreadsheet elements.

## Practical Code Examples

The following examples demonstrate how to construct and use DOM paths in various scripting environments:

**Command Line (Bash)**

```bash

# Add a shape to slide 2 using a hard-coded index

officecli add deck.pptx '/slide[2]' \
  --type shape --prop text="Hello" --prop x=2cm --prop y=3cm

# Use a shell variable for parameterized access

I=5
officecli get deck.pptx "/slide[${I}]/shape[3]" --json

```

**Python SDK**

```python
import officecli

doc = officecli.create("deck.pptx")
for i in range(1, 4):
    # Build path dynamically with f-string

    shape_path = f"/slide[{i}]/shape[1]"
    doc.send({
        "command": "set", 
        "path": shape_path, 
        "props": {"text": f"Slide {i}"}
    })
doc.close()

```

**PowerShell**

```powershell
for ($i = 1; $i -le 3; $i++) {
    officecli set deck.pptx "/slide[$i]/shape[2]" --prop fill=FF0000
}

```

## Core Implementation Files

The DOM path resolution logic is implemented in the following source files within the iOfficeAI/OfficeCLI repository:

- **[`src/officecli/Handlers/Pptx/PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Pptx/PowerPointHandler.cs)** — Contains the core resolve routine that parses `/slide[…]` syntax and walks the in-memory slide DOM.
- **[`src/officecli/Handlers/Word/WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.cs)** — Provides analogous path resolution for Word documents, handling tags like `body`, `p`, and `tbl`.
- **[`src/officecli/Handlers/Excel/ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Excel/ExcelHandler.cs)** — Implements the path system for spreadsheets, resolving sheet names, rows, and cell references.
- **[`README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/README.md)** — Documents the high-level "Path-based addressing" conceptual model for end users.

## Summary

- The OfficeCLI DOM path system uses **slash-separated selectors** in the format `<tag>[<index>]` to address OOXML elements.
- Indices are **1-based** and can be either literal integers or **symbolic placeholders** (e.g., `I`, `myIdx`) for dynamic resolution.
- The parser validates segments using the regex `^([a-zA-Z]+)(\[(\d+|[A-Za-z_]\w*)\])?$` before traversing the document tree.
- Path resolution is implemented in [`PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.cs), [`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs), and [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs), with each handler mapping tags to document-specific OOXML parts.
- Unresolvable paths trigger a `not_found` error during DOM traversal.

## Frequently Asked Questions

### What is the syntax for OfficeCLI DOM paths?

OfficeCLI DOM paths consist of forward-slash-separated segments where each segment follows the pattern `<tag>[<index>]`. The tag represents the OOXML element name (such as `slide`, `shape`, or `cell`), and the index is a 1-based integer specifying which occurrence of that element to target. For example, `/slide[2]/shape[1]` addresses the first shape on the second slide.

### How do I use variables or placeholders in DOM paths?

You can use symbolic names like `I` or `myIdx` inside the brackets instead of literal numbers, creating parameterized paths such as `/slide[I]/shape[2]`. When executing commands, these placeholders are substituted at runtime by the calling script or application, enabling dynamic iteration over document elements.

### Which Office document types support the DOM path system?

The DOM path system supports Word (DOCX), Excel (XLSX), and PowerPoint (PPTX) documents. Each document type has specific handler implementations—[`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs) for paragraphs and tables, [`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs) for sheets and cells, and [`PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.cs) for slides and shapes—that parse the same path syntax against their respective OOXML structures.

### Where is the path parsing logic implemented in the source code?

The primary path parsing and resolution logic resides in [`src/officecli/Handlers/Pptx/PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Pptx/PowerPointHandler.cs) for PowerPoint files, with analogous implementations in [`src/officecli/Handlers/Word/WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.cs) and [`src/officecli/Handlers/Excel/ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Excel/ExcelHandler.cs). These handlers use the regex `^([a-zA-Z]+)(\[(\d+|[A-Za-z_]\w*)\])?$` to validate path segments before traversing the in-memory DOM.