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

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]:

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

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

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. 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. 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 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 and 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:

officecli view report.docx outline

Output:

/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:

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

Step 2: Navigate to Elements

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

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:

# 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 via MsysPathHint.Restore
• Word navigation builds DocumentNode trees in Handlers/Word/WordHandler.Navigation.cs
• Live scrolling converts paths to HTML anchors in Core/Watch/WatchNotifier.cs
• Command integration flows through CommandBuilder.Goto.cs and 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.

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