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

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 and validated through 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 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 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 — navigates /slide[n] and /slide[n]/shape[m] hierarchies
• WordHandler.cs — processes /body, /body/p[n], and /body/p[n]/r[m] for runs
• ExcelHandler.cs — resolves /sheet[n] and /sheet[n]/cell[ref] paths

SelectorPositionalIndex.cs provides the underlying utilities for locating n‑th children within parent containers.

Practical Command Examples

# 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	Converts 1‑based path indices to 0‑based array indices
src/officecli/CommandBuilder.cs	Parses path strings from command-line arguments
src/officecli/Handlers/PowerPointHandler.cs	Implements slide and shape navigation for PPTX
src/officecli/Handlers/WordHandler.cs	Implements body, paragraph, and run navigation for DOCX
src/officecli/Handlers/ExcelHandler.cs	Implements sheet and cell navigation for XLSX
src/officecli/Core/ParseHelpers.cs	Tokenizes and validates path string syntax
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 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 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 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.

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