OfficeCLI Path-Based Element Addressing System: Navigate Office Documents Without XPath

OfficeCLI implements a stable, 1-based path syntax using slash-separated segments and optional indices to address any element in Word, Excel, or PowerPoint documents without exposing raw XML namespaces or XPath complexity.

OfficeCLI provides a command-line interface for automating Microsoft Office document manipulation. Its path-based element addressing system abstracts away the underlying OOXML complexity, allowing scripts and agents to pinpoint specific document elements using human-readable paths rather than verbose XPath queries.

Path Syntax Fundamentals

Segment Structure and 1-Based Indexing

A valid path consists of slash-separated segments targeting elements by their local name (the element name without namespace prefixes). Each segment may include an optional index in square brackets using 1-based numbering.

/slide[1]/shape[2]          # second shape on first slide

/body/p[3]                  # third paragraph in document body

/body/table[1]/tr[2]/tc[4]  # fourth cell in second row of first table

Unlike zero-based array indexing common in programming languages, OfficeCLI indices start at 1 to align with human document conventions (first paragraph, second slide, etc.).

Attribute Selectors and Context References

Segments can include attribute predicates to match elements by property values using the syntax [@attr=VALUE]. This enables addressing bookmarks, named ranges, or specific shapes regardless of positional changes.

/bookmark[@name="Intro"]
/bookmark[@name="Conclusion"]

The special @ segment refers to the current element when chaining commands or establishing relative navigation contexts.

Internal Path Parsing Implementation

The GenericXmlQuery Parser

The core parsing logic resides in src/officecli/Core/GenericXmlQuery.cs. The ParsePathSegments method tokenizes path strings into discrete navigation instructions by splitting on "/" and extracting element names, optional indices, and attribute predicates.

This method returns a structured list of tuples containing the target element name and optional index, which handlers consume to traverse the document DOM.

Handler-Specific Navigation

Concrete implementations in src/officecli/Handlers/Word/WordHandler.Navigation.cs and src/officecli/Handlers/Pptx/PowerPointHandler.Resolve.cs utilize these parsed segments. The NavigateToElement method traverses the OOXML DOM hierarchy according to the parsed path instructions, locating the target node for both read (Get) and write (Set) operations.

Because the addressing scheme relies on local element names and deterministic traversal, paths remain stable across document edits—inserting rows or slides does not invalidate existing addresses for unchanged elements.

Practical Document Navigation Commands

OfficeCLI exposes six core operations driven by this addressing scheme: Get, Set, Add, Remove, Copy, and Move.

Retrieving and Modifying Content

Retrieve raw XML from a specific paragraph:

officecli get /body/p[3]

Update text content of a shape on a specific slide:

officecli set /slide[1]/shape[2] --text "Hello, world!"

Structural Modifications

Add a new row to the second table in a Word document:

officecli add /body/table[2] --row

Remove a bookmark by its name attribute:

officecli remove /bookmark[@name="Conclusion"]

Copy a paragraph and insert it after another element:

officecli copy /body/p[4] --to /body/p[6] --after

Schema-Aware Addressing Assistance

The src/officecli/Help/SchemaHelpRenderer.cs component generates contextual help listing valid path forms for each document type, ensuring users construct syntactically valid addresses for Word, Excel, or PowerPoint files.

Additionally, src/officecli/CommandBuilder.Goto.cs implements the goto command, which resolves a path to a human-readable location within the document structure, aiding debugging and verification of complex paths.

Summary

• OfficeCLI uses 1-based indexing where the first element is [1], not [0], matching natural document ordering.
• Paths use local element names only—no XML namespace prefixes are required, simplifying the syntax significantly over raw XPath.
• Attribute selectors allow addressing elements by properties like name or id using [@attr=value] syntax.
• Core parsing occurs in GenericXmlQuery.ParsePathSegments, while handlers like WordHandler.Navigation.cs execute the actual DOM traversal.
• Six operations support the addressing system: Get, Set, Add, Remove, Copy, and Move, providing comprehensive document manipulation capabilities.

Frequently Asked Questions

What makes OfficeCLI's addressing system different from standard XPath?

OfficeCLI's system uses only element local names and 1-based indices, eliminating the need for namespace prefixes and complex axis specifiers required by XPath. According to the source code in GenericXmlQuery.cs, the parser specifically strips namespace considerations and focuses on stable, document-relative addressing that survives structural changes.

Why does OfficeCLI use 1-based indexing instead of 0-based?

The 1-based indexing aligns with how humans reference document elements in natural language (first paragraph, second slide). As implemented in ParsePathSegments, this convention prevents off-by-one errors when non-programmers write automation scripts or when AI agents generate commands based on human instructions referencing document positions.

How do I address an element by attribute rather than position?

Append an attribute predicate to the segment using square brackets: /bookmark[@name="Intro"]. The parser in GenericXmlQuery.cs extracts these predicates during segment tokenization, and handlers match them against the underlying XML attributes during DOM traversal in NavigateToElement.

Which Office document types support path-based navigation?

The system supports Word (DOCX), PowerPoint (PPTX), and Excel (XLSX) documents through specialized handlers. WordHandler.Navigation.cs handles Word-specific structures like body paragraphs and tables, while PowerPointHandler.Resolve.cs manages slide and shape hierarchies, both utilizing the same underlying GenericXmlQuery parsing infrastructure.

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