OfficeCLI Path Aliases for Document References: A Complete Guide

OfficeCLI path aliases let you use human-friendly names like paragraph and table instead of raw OpenXML tags like p and tbl when querying Word, Excel, and PowerPoint documents.

The iOfficeAI/OfficeCLI project includes a centralized alias system that transparently converts intuitive element names into their canonical OpenXML equivalents. This guide explains exactly how the alias resolution works, where the mappings are defined, and how to use them in both direct CLI commands and resident-mode queries.

How OfficeCLI Path Aliases Work

The Core Alias Dictionary

All path aliases are stored in the static PathAliases class located at src/officecli/Core/PathAliases.cs. This class maintains a case-insensitive dictionary that maps friendly names to their OpenXML counterparts:

// src/officecli/Core/PathAliases.cs
private static readonly Dictionary<string, string> Aliases = new(StringComparer.OrdinalIgnoreCase)
{
    // Word
    ["paragraph"] = "p",
    ["run"]       = "r",
    ["table"]     = "tbl",
    ["row"]       = "tr",
    ["cell"]      = "tc",
    // PowerPoint
    ["slide"]   = "slide",
    ["shape"]   = "shape",
    …
};

The dictionary uses StringComparer.OrdinalIgnoreCase so Paragraph, PARAGRAPH, and paragraph all resolve identically.

Alias Resolution Method

The resolution logic is implemented in the Resolve method at lines 30-33 of PathAliases.cs:

public static string Resolve(string name)
    => Aliases.TryGetValue(name, out var canonical) ? canonical : name;

If an alias exists, the method returns the canonical OpenXML name. If no alias matches, the original token passes through unchanged—this allows mixed usage of aliases and canonical names in the same selector.

Where Path Aliases Are Applied

Direct Command-Line Mode

In direct mode, the CommandBuilder.GetQuery.cs file normalizes selectors before the attribute-filter engine processes them. Your alias-containing selector is transformed to canonical form immediately after parsing, ensuring consistent downstream processing.

Resident Server Mode

The ResidentServer.cs file demonstrates equivalent handling at lines 73-82. Here, selector normalization occurs through a delegate (keyResolver) that calls specialized resolvers like ExcelHandler.ResolveCellAttributeAlias when targeting Excel cells. This ensures OfficeCLI path aliases for document references behave identically across both execution modes.

Schema Help Integration

Additional schema-level aliases (such as alignment for align) are collected by SchemaHelpLoader.cs at lines 198-207. These augment the officecli help schema output, surfacing available aliases to users exploring available selectors.

Practical Examples for Word, Excel, and PowerPoint

Word Document Selectors

Friendly Alias	Canonical OpenXML	Example CLI Usage
paragraph	p	officecli query --selector "/body/paragraph[2]"
table	tbl	officecli query --selector "/body/table[1]"
row	tr	officecli query --selector "/body/table[1]/row[3]"
cell	tc	officecli query --selector "/body/table[1]/row[3]/cell[2]"
run	r	officecli query --selector "/body/paragraph[1]/run[2]"

Chained Path Aliases in Nested Selectors

You can combine multiple aliases in a single path. The resolver processes each segment independently:

# Select the second cell of the third row in the first table

officecli query --selector "/body/table[1]/row[3]/cell[2]" --file document.docx

This resolves internally to /body/tbl[1]/tr[3]/tc[2] while remaining human-readable in your scripts and documentation.

PowerPoint and Excel Considerations

PowerPoint aliases like slide and shape map to themselves in the current dictionary, but the alias system allows future extensions without breaking existing selectors. Excel cell references use a specialized resolver path (ExcelHandler.ResolveCellAttributeAlias) to handle spreadsheet-specific notation.

Working with JSON Output

When using --json, aliases are resolved before serialization. The output contains canonical element names, ensuring programmatic consumers receive predictable OpenXML identifiers:

# Query using friendly alias, receive canonical structure

officecli query --selector "/body/paragraph[1]" --json document.docx

Example output:

[
  {
    "name": "p",
    "attributes": { ... },
    "text": "First paragraph content"
  }
]

Note that the element name field shows p (canonical) even though you queried with paragraph.

Resident-Mode Scripting Example

For automation scenarios, resident mode avoids process startup overhead while maintaining full alias support:

# Start resident server and pipe a query with path aliases

echo '{"command":"query","selector":"/body/paragraph"}' | officecli resident

The server normalizes paragraph → p using the same PathAliases.Resolve call as direct mode.

Key Source Files for Path Alias Implementation

• src/officecli/Core/PathAliases.cs – Central dictionary and Resolve() method (lines 14-33)
• src/officecli/ResidentServer.cs – Resident-mode query normalization (lines 73-82)
• src/officecli/CommandBuilder.GetQuery.cs – Direct-mode selector parsing with alias application
• src/officecli/Help/SchemaHelpLoader.cs – Schema-level alias collection for help output (lines 198-207)
• src/officecli/Help/SchemaHelpRenderer.cs – Renders aliases in officecli help schema display

Summary

• OfficeCLI path aliases are defined in PathAliases.cs as a case-insensitive dictionary mapping friendly names to OpenXML canonical names
• The Resolve() method transforms selectors transparently; unmatched tokens pass through unchanged
• Alias resolution occurs in both direct mode (CommandBuilder.GetQuery.cs) and resident mode (ResidentServer.cs)
• Word aliases include paragraph→p, table→tbl, row→tr, cell→tc, and run→r
• Schema help loads additional aliases dynamically through SchemaHelpLoader.cs
• JSON output always contains canonical names, not aliases, ensuring consistent programmatic consumption

Frequently Asked Questions

What happens if I use an undefined alias in a selector?

The PathAliases.Resolve method returns the original token unchanged when no alias matches. Your selector will proceed using the name as provided, which may cause a "not found" error if it doesn't match any canonical OpenXML element.

Can I mix aliases and canonical names in the same path?

Yes. The resolver processes each path segment independently, so /body/paragraph[1]/p[2]/tbl[3] is valid—paragraph resolves to p, while p and tbl pass through as canonical names.

Do path aliases work in resident mode scripts?

Absolutely. The ResidentServer.cs implementation (lines 73-82) ensures identical alias resolution through the keyResolver delegate, maintaining parity with direct CLI usage for automation and integration scenarios.

Where can I see all available aliases for my document type?

Run officecli help schema to view schema-specific aliases collected by SchemaHelpLoader.cs. The rendered help includes both built-in aliases from PathAliases.cs and additional schema-level mappings discovered from your document's OpenXML structure.

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