# How to Use Path‑Based Element Addressing for Document Navigation in OfficeCLI

> Learn how to use path-based element addressing in OfficeCLI to navigate, query, and edit elements in Word, Excel, and PowerPoint documents using slash-separated paths and indexed selectors.

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

---

**OfficeCLI uses slash-separated paths with indexed selectors (`[N]`) to pinpoint any element inside Word, Excel, or PowerPoint documents for navigation, querying, and editing.**

Path-based element addressing is the core navigation system in `iOfficeAI/OfficeCLI`. A path is a hierarchical string that describes exactly where an element lives in a document's structure, enabling precise targeting without manual traversal of OpenXML internals. This article explains the syntax, implementation, and practical workflows for path-based element addressing across all supported Office formats.

## Path Syntax and Structure

Every path in OfficeCLI starts with `/` and follows a consistent pattern across document types:

```

/topLevelContainer/elementType[index]/childElement[index]...

```

The first segment identifies the document container—`body` for Word, `sheet` for Excel, `slide` for PowerPoint. Subsequent segments name child elements, with optional bracketed indices for repeated items.

### Word Document Paths

| Path Pattern | Element Targeted |
|-------------|------------------|
| `/body/p[N]` | The *N*-th paragraph |
| `/body/table[N]` | The *N*-th table |
| `/body/table[N]/tr[R]` | The *R*-th row of table *N* |
| `/body/table[N]/tr[R]/tc[C]` | The *C*-th cell of that row |

### Excel and PowerPoint Paths

Excel uses `/sheet[index]/row[index]/cell[reference]`:

```bash
officecli get workbook.xlsx "/sheet[1]/row[5]/cell[C5]" --json

```

PowerPoint uses `/slide[index]/shape[index]`:

```bash
officecli set presentation.pptx "/slide[2]/shape[3]" --prop text="Updated title"

```

## How Path Resolution Works

The path-based element addressing system in OfficeCLI operates through four coordinated stages, implemented across several core files.

### 1. Path Parsing and Normalization

User-provided paths first pass through `OfficeCli.Core.MsysPathHint.Restore` in [`src/officecli/Core/MsysPathHint.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/MsysPathHint.cs). This method:

- Expands Microsoft-style shortcuts into canonical paths
- Validates format compliance
- Normalizes index notation

### 2. Element Resolution

For Word documents, the navigation logic resides in `WordHandler.GetRootNode` and surrounding helpers in [`src/officecli/Handlers/Word/WordHandler.Navigation.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Word/WordHandler.Navigation.cs). The handler:

1. Builds a tree of **DocumentNode** objects
2. Assigns each node a `Path` property
3. Matches the input path against the tree to return the exact OpenXML element

A lookup like `/body/table[2]/tr[3]/tc[1]` resolves directly to the corresponding `TableCell` element.

### 3. Live Preview Scrolling

When `officecli watch` monitors a file, the `goto` command converts paths to HTML anchors. The `WatchMessage.ExtractWordScrollTarget` method in [`src/officecli/Core/Watch/WatchNotifier.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/Watch/WatchNotifier.cs) transforms `/body/p[5]` into selector `#p5`, broadcasting it via Server-Sent Events (SSE) to scroll all connected preview clients instantly.

### 4. Command Integration

Mutating commands—`add`, `set`, `remove`, `move`, `swap`—accept `--path` arguments restored by the command builder and passed to appropriate handlers. See [`src/officecli/CommandBuilder.Goto.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Goto.cs) and [`src/officecli/CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.cs) for the integration layer.

## Practical Workflow

Follow this three-step pattern for path-based element addressing in daily use.

### Step 1: Identify Element Paths

Use the outline view or JSON output to discover correct paths:

```bash
officecli view report.docx outline

```

Output:

```text
/body/p[1]                   Introduction
/body/p[2]                   Methodology
/body/table[1]               Summary Table
/body/table[1]/tr[1]         Header Row
/body/table[1]/tr[1]/tc[1]   Column A
/body/table[1]/tr[2]/tc[2]   Value B2

```

Or query specific elements:

```bash
officecli get report.docx /body/table[1] --json

```

### Step 2: Navigate to Elements

Scroll the live preview to any element (Word only):

```bash
officecli goto report.docx /body/p[2]

```

The browser window opened by `officecli watch` jumps immediately to paragraph 2.

### Step 3: Modify Targeted Elements

Combine paths with mutation commands:

```bash

# Update paragraph text

officecli set report.docx /body/p[3] \
    --prop text="Updated paragraph"

# Modify table cell content

officecli set report.docx /body/table[1]/tr[1]/tc[1] \
    --prop text="New header"

# Remove a specific row

officecli remove report.docx /body/table[1]/tr[4]

# Add shape to PowerPoint slide

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

```

## Common Path Patterns by Task

| Task | Command Pattern |
|------|-----------------|
| Read element properties | `officecli get <file> <path> --json` |
| Update text content | `officecli set <file> <path> --prop text="..."` |
| Insert new element | `officecli add <file> <parent-path> --type <type>` |
| Delete element | `officecli remove <file> <path>` |
| Reorder elements | `officecli move <file> <path> --after <other-path>` |
| Swap two elements | `officecli swap <file> <path1> <path2>` |

## Summary

- **Path syntax** uses `/container/element[N]/child[M]` format with required leading slash and bracketed 1-based indices
- **Path restoration** happens in [`Core/MsysPathHint.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Core/MsysPathHint.cs) via `MsysPathHint.Restore`
- **Word navigation** builds DocumentNode trees in [`Handlers/Word/WordHandler.Navigation.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Handlers/Word/WordHandler.Navigation.cs)
- **Live scrolling** converts paths to HTML anchors in [`Core/Watch/WatchNotifier.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Core/Watch/WatchNotifier.cs)
- **Command integration** flows through [`CommandBuilder.Goto.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Goto.cs) and [`CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.cs)
- **Discovery workflow**: `view outline` → `goto` for preview → `set`/`add`/`remove` for changes

## Frequently Asked Questions

### What happens if I use an invalid path?

OfficeCLI validates paths during restoration and returns an error indicating which segment failed to resolve. For Word documents, the handler checks each path segment against the DocumentNode tree and reports the deepest valid prefix if the full path cannot be matched.

### Are path indices 0-based or 1-based?

Indices are **1-based**, matching conventional document numbering. `/body/p[1]` refers to the first paragraph, not the second. This aligns with how Office applications display element numbering to users.

### Can I use paths without the `watch` command running?

Yes. Paths work for all read and write operations. The `goto` command specifically requires an active `watch` session because it relies on SSE broadcasting to connected preview clients. Mutation commands like `set` and `remove` operate directly on files without live preview.

### Does Excel support the same depth of path nesting as Word?

Excel paths currently support `/sheet[N]/row[N]/cell[reference]` depth. Unlike Word tables, Excel cells are addressed by alphanumeric reference (e.g., `cell[C5]`) rather than row/column indices. The underlying implementation in `ExcelHandler` follows the same resolution pattern but adapts to spreadsheet structure conventions.