How to Use OfficeCLI's Path-Based Addressing System for Document Navigation

OfficeCLI converts every element in Word, Excel, and PowerPoint files into stable, human-readable paths like /slide[1]/shape[2] or /Sheet1!B5, replacing complex XML navigation with intuitive 1-based selectors that work uniformly across all Office formats.

OfficeCLI's path-based addressing system provides a uniform navigation layer across Office document formats. This design allows AI agents and automation scripts to reference any document element using concise, composable selectors rather than raw XPath or XML coordinates. Whether you're manipulating PowerPoint shapes, Excel cells, or Word paragraphs, the syntax remains consistent and predictable according to the iOfficeAI/OfficeCLI source code.

Understanding Path Syntax Structure

OfficeCLI paths follow three core principles that make them intuitive for both humans and AI agents.

1-Based Indexing and Local Names

Paths use 1-based indexing where the first element is [1], not [0]. The syntax relies on local-name based selectors, using only the element's tag name (slide, shape, sheet, row, paragraph) rather than full XML namespaces. For example, /slide[1]/shape[2] targets the second shape on the first slide, while /Sheet1!B5 uses Excel's familiar cell reference notation.

Composable Hierarchy Navigation

Sub-paths join with / to drill deeper into the document hierarchy. You can traverse from root to specific elements: /body/p[3]/r[2] reaches the second run within the third paragraph of a Word document's body. This composability allows precise targeting without understanding the underlying Open XML structure.

Core Implementation and Request Handling

The path resolution logic resides in two critical source files within the OfficeCLI repository.

Request Parsing in ResidentServer.cs

When executing commands, OfficeCLI extracts the --path argument (or its synonym --selector) through the resident server. In ResidentServer.cs, the code parses the request using req.GetArg("path", "/") where the default / denotes the document root. If the path cannot be resolved against the internal DOM representation, the system throws an ArgumentException with a contextual error message indicating what went wrong.

Validation via CommandBuilder

Before performing mutations, the CommandBuilder family of methods (Get, Set, Add) validates paths using MutationSelectorGuard.EnsureScoped(path, "set"). This guard ensures mutation commands receive properly scoped paths, preventing accidental modifications to unintended document regions. The validation occurs in CommandBuilder.cs (lines 2009-2017), enforcing path integrity before DOM manipulation.

Practical Usage Examples

OfficeCLI supports multiple commands that leverage path-based addressing across different document formats.

Reading Document Elements

To retrieve a slide's JSON description from a PowerPoint file:

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

Modifying Specific Elements

Update text in a specific shape using quoted paths for special characters:

officecli set deck.pptx '/slide[2]/shape[1]' \
  --prop text="Revenue grew 30%" \
  --json

Excel Cell Manipulation

Add a new worksheet and write values using Excel-style references:

# Add a new sheet named "Q1"

officecli add sales.xlsx / --type sheet --prop name="Q1"

# Write a value to cell B5

officecli set sales.xlsx '/Sheet1!B5' --prop value=12345 --json

Resident Mode for Batch Operations

For performance-critical workflows, resident mode keeps documents in memory:

# Open document in resident mode

officecli open report.docx

# Perform multiple mutations without disk I/O

officecli set report.docx /body/p[3]/r[2] --prop bold=true
officecli set report.docx /body/p[4]/r[1] --prop color=FF0000

# Persist changes and close

officecli close report.docx

Error Handling and Recovery

When paths fail to resolve, OfficeCLI returns structured JSON errors rather than raw exceptions. If you request /slide[10] in a deck containing only 8 slides, the system returns:

{
  "success": false,
  "error": {
    "error": "Slide 10 not found (total: 8)",
    "code": "not_found",
    "suggestion": "Valid Slide index range: 1-8"
  }
}

These error codes (not_found, invalid_path) allow AI agents to programmatically inspect failures and adjust their selectors. An agent can query the parent / to discover valid indices before retrying.

Summary

OfficeCLI's path-based addressing system transforms Office document manipulation through these key characteristics:

• Human-readable syntax using 1-based indices and local element names like /slide[1]/shape[2] or /Sheet1!B5
• Uniform implementation across Word, Excel, and PowerPoint via ResidentServer.cs and CommandBuilder.cs
• Built-in validation through MutationSelectorGuard.EnsureScoped() that prevents invalid mutations
• Structured error responses with specific codes and suggestions for programmatic recovery
• Resident mode support enabling fast, in-memory batch operations without repeated disk access

Frequently Asked Questions

How does OfficeCLI handle invalid path selectors?

When a path cannot be resolved, OfficeCLI returns a JSON error object with success: false, an error field containing the descriptive message, a machine-readable code (such as not_found or invalid_path), and a suggestion field with valid alternatives. This structure allows automated agents to parse failures and adjust their queries without manual intervention.

What is the difference between --path and --selector arguments?

There is no functional difference; --selector exists as a synonym for --path. Both arguments pass the path string to ResidentServer.cs where req.GetArg("path", "/") processes the value, defaulting to the document root (/) if unspecified. Use whichever aligns better with your scripting conventions.

Can I use OfficeCLI paths to navigate Word document styles?

Yes, the path system supports style-based querying through the query command. For example, officecli query report.docx "paragraph[style=Heading1]:contains(bold)" --json targets all Heading 1 paragraphs containing bold text. This combines CSS-like selectors with the path-based addressing system for complex document analysis.

What happens if I omit the path argument entirely?

The system defaults to / (document root), as implemented in ResidentServer.cs at line 1810. When operating on the root, commands like add create new top-level elements (such as adding a new worksheet to an Excel file), while get returns the document's root metadata structure.

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