# How OfficeCLI's Path-Based Addressing Scheme Works: /slide[1]/shape[2] Explained

> Understand OfficeCLI's path-based addressing scheme like /slide[1]/shape[2]. Learn how OfficeCLI simplifies element identification in Word, Excel, and PowerPoint files.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: internals
- Published: 2026-08-02

---

**OfficeCLI uses a simplified XPath-style addressing scheme where every element in Word, Excel, or PowerPoint files is identified by a slash-prefixed path with 1‑based indices, such as `/slide[1]/shape[2]`.**

The **path-based addressing scheme** in iOfficeAI/OfficeCLI provides a consistent, AI-friendly syntax for navigating Office documents without requiring knowledge of OOXML namespaces or XML hierarchy. This single convention works across all three major Office formats, enabling scripts and agents to locate, modify, and move elements predictably.

## Path Syntax Rules

OfficeCLI enforces seven core rules for path construction. These are implemented in [`CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.cs) and validated through [`ParseHelpers.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ParseHelpers.cs).

| Rule | Implementation Details |
|------|----------------------|
| **Root prefix** | Every path starts with `/` representing the document root |
| **Segment structure** | `elementName[optionalIndex]` — index in square brackets |
| **Default index** | Omitted indices default to `[1]`; `shape` equals `shape[1]` |
| **1‑based indexing** | First element is `[1]`; converted to 0‑based internally via `PathIndex.ToArrayIndex` |
| **No full XPath** | No predicates, functions, or namespace support |
| **Format-specific elements** | `slide`/`shape`/`paragraph`/`run` (PowerPoint); `sheet`/`cell` (Excel); `body`/`p`/`r` (Word) |
| **Cross-format consistency** | Same syntax regardless of file type |

## Internal Implementation

The addressing pipeline consists of three stages defined in `src/officecli/Core/` and dispatched through handlers.

### 1. Parsing

`CommandBuilder` in [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) splits incoming paths on `/` delimiters, tokenizes each segment, and extracts element names with their optional indices.

### 2. Index Conversion

`PathIndex` in [`src/officecli/Core/PathIndex.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/PathIndex.cs) handles the critical conversion between user-facing 1‑based indices and the 0‑based array indices required by the underlying OOXML object model. This separation allows intuitive `[1]` notation while maintaining compatibility with .NET collection semantics.

### 3. Handler Dispatch

Parsed segments route to format-specific handlers that walk the OOXML part structure:

- **[`PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.cs)** — navigates `/slide[n]` and `/slide[n]/shape[m]` hierarchies
- **[`WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/WordHandler.cs)** — processes `/body`, `/body/p[n]`, and `/body/p[n]/r[m]` for runs
- **[`ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.cs)** — resolves `/sheet[n]` and `/sheet[n]/cell[ref]` paths

[`SelectorPositionalIndex.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SelectorPositionalIndex.cs) provides the underlying utilities for locating *n*‑th children within parent containers.

## Practical Command Examples

```bash

# Create a new PowerPoint deck

officecli create deck.pptx

# Add the first slide (implicitly index 1)

officecli add deck.pptx / --type slide --prop title="Quarterly Report"

# Add a shape to the first slide

officecli add deck.pptx '/slide[1]' --type shape \
  --prop text="Revenue ↑ 25%" --prop x=2cm --prop y=5cm --prop size=24

# Retrieve the second shape on the first slide as JSON

officecli get deck.pptx '/slide[1]/shape[2]' --json

# Update the fill colour of that shape

officecli set deck.pptx '/slide[1]/shape[2]' --prop fill="FF0000"

# Move the third shape on slide 2 to slide 1, after shape 1

officecli move deck.pptx '/slide[2]/shape[3]' \
  --to '/slide[1]' --after '/slide[1]/shape[1]'

```

Every command accepting a `<path>` argument follows this addressing convention, making automation scripts portable across document types.

## Key Source Files

| File | Role in Path-Based Addressing |
|------|------------------------------|
| [`src/officecli/Core/PathIndex.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/PathIndex.cs) | Converts 1‑based path indices to 0‑based array indices |
| [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) | Parses path strings from command-line arguments |
| [`src/officecli/Handlers/PowerPointHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/PowerPointHandler.cs) | Implements slide and shape navigation for PPTX |
| [`src/officecli/Handlers/WordHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/WordHandler.cs) | Implements body, paragraph, and run navigation for DOCX |
| [`src/officecli/Handlers/ExcelHandler.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/ExcelHandler.cs) | Implements sheet and cell navigation for XLSX |
| [`src/officecli/Core/ParseHelpers.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/ParseHelpers.cs) | Tokenizes and validates path string syntax |
| [`src/officecli/Core/SelectorPositionalIndex.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/SelectorPositionalIndex.cs) | Locates n-th child elements for handler consumption |

## Summary

- **OfficeCLI path-based addressing** uses `/element[index]/child[index]` syntax with mandatory root `/` and optional 1‑based indices
- **Default index behavior** automatically assigns `[1]` when indices are omitted
- **Internal conversion** via `PathIndex.ToArrayIndex` bridges user-friendly 1‑based notation to 0‑based OOXML arrays
- **Format handlers** implement consistent navigation across PowerPoint, Word, and Excel document structures
- **AI-optimized design** eliminates OOXML complexity while maintaining precise element targeting

## Frequently Asked Questions

### What happens if I omit the index in a path segment?

The system defaults to `[1]`. Writing `/slide/shape` is equivalent to `/slide[1]/shape[1]`. This default is applied during parsing in [`CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.cs) before index conversion occurs.

### Why does OfficeCLI use 1‑based indexing instead of 0‑based?

1‑based indexing matches human intuition (first element is 1, not 0) and aligns with common document editing conventions. The `PathIndex` class in [`src/officecli/Core/PathIndex.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/PathIndex.cs) handles the translation to 0‑based indices required by the underlying OOXML libraries.

### Can I use full XPath expressions with predicates or namespaces?

No. The path-based addressing scheme intentionally supports only element names and positional indices. This constraint in [`ParseHelpers.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ParseHelpers.cs) ensures predictable, fast resolution without XPath parser overhead or namespace complexity.

### Does the same path syntax work for all Office file types?

Yes. While supported element names differ by format—`slide`/`shape` for PowerPoint, `sheet`/`cell` for Excel, `body`/`p`/`r` for Word—the addressing structure remains identical. This cross-document consistency enables single automation scripts to operate across multiple Office formats.