# OfficeCLI Path Aliases for Document References: A Complete Guide

> Master OfficeCLI path aliases to simplify document references. Use human friendly names like paragraph and table instead of raw OpenXML tags for Word, Excel, and PowerPoint.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/PathAliases.cs). This class maintains a case-insensitive dictionary that maps friendly names to their OpenXML counterparts:

```csharp
// 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PathAliases.cs):

```csharp
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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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:

```bash

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

```bash

# Query using friendly alias, receive canonical structure

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

```

Example output:

```json
[
  {
    "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:

```bash

# 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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/PathAliases.cs)** – Central dictionary and `Resolve()` method (lines 14-33)
- **[`src/officecli/ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentServer.cs)** – Resident-mode query normalization (lines 73-82)
- **[`src/officecli/CommandBuilder.GetQuery.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.GetQuery.cs)** – Direct-mode selector parsing with alias application
- **[`src/officecli/Help/SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Help/SchemaHelpLoader.cs)** – Schema-level alias collection for help output (lines 198-207)
- **[`src/officecli/Help/SchemaHelpRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Help/SchemaHelpRenderer.cs)** – Renders aliases in `officecli help schema` display

## Summary

- **OfficeCLI path aliases** are defined in [`PathAliases.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.GetQuery.cs)) and **resident mode** ([`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/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`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs). The rendered help includes both built-in aliases from [`PathAliases.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PathAliases.cs) and additional schema-level mappings discovered from your document's OpenXML structure.