# How to Use Path Aliases in OfficeCLI: A Complete Guide to Simplified Document Navigation

> Master path aliases in OfficeCLI to simplify document navigation. This guide shows you how to use short, human-friendly names for easy access to elements like selected, bold, or toc.

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

---

**OfficeCLI supports path aliases—short, human-friendly names that resolve to full internal paths—allowing you to reference document elements like `selected`, `bold`, or `/toc` without memorizing complex OpenXML paths.**

The **iOfficeAI/OfficeCLI** repository provides a powerful command-line interface for automating Microsoft Office documents. Using **path aliases in OfficeCLI**, you can write concise commands that target specific elements inside Word, Excel, or PowerPoint files without needing to know the underlying XML structure.

## How Path Aliases Work in OfficeCLI

The alias system operates through a layered resolution pipeline. Each layer handles different types of shortcuts, from global commands to format-specific attribute mappings.

### Root-Level Shortcuts

OfficeCLI recognizes special pseudo-paths early in the command pipeline. The most common example is the **`selected`** alias, which resolves to the current watch selection in a resident server session.

According to the source code in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) (lines 1950-1958), this shortcut is intercepted before standard path parsing occurs:

```bash

# Retrieves the element currently selected in the watch session

officecli get myDoc.docx selected

```

### Schema-Defined Element Aliases

Each document format—**docx**, **xlsx**, and **pptx**—can declare its own aliases in schema definitions. These mappings translate human-friendly terms like `header` or `bold` into their full OpenXML path equivalents.

The [`SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs) file (lines 198-207) builds a per-format alias map at runtime by loading these definitions. This means you can reference `style=Heading1` simply as `header` if the schema defines that relationship.

### Excel Cell-Attribute Aliases

For Excel spreadsheets, OfficeCLI provides specialized shortcuts for cell formatting properties. When a selector targets a specific cell (e.g., `/Sheet1!A1`), the CLI normalizes attributes using short names like **`bold`**, **`size`**, or **`color`**.

In [`CommandBuilder.GetQuery.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.GetQuery.cs) (lines 218-222), the query builder detects when the handler is an `ExcelHandler` and injects the resolver. The actual implementation appears in [`ExcelHandler.Selector.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.Selector.cs) (lines 224-229) within the `ResolveCellAttributeAlias` method, which maps `bold` to `font.bold` and `size` to `font.size`.

```bash

# The 'bold' alias resolves to font.bold internally

officecli query mySheet.xlsx "Sheet1!A1[bold]" --compact

```

### Query Pipeline Normalization

Both `get` and `query` commands retrieve the alias map from the active handler and pass it to `AttributeFilter.FilterSelector`. This normalization step, found in [`CommandBuilder.GetQuery.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.GetQuery.cs) (lines 207-214), ensures that any alias used in a path—such as `/toc` for the table of contents—is resolved before the underlying OpenXML query executes.

## Practical Examples of Path Aliases

The following commands demonstrate how aliases simplify document interaction:

**1. Access the current selection in a watch session:**

```bash
officecli get myDoc.docx selected

```

**2. Query Excel cell formatting using short attribute names:**

```bash
officecli query mySheet.xlsx "Sheet1!A1[bold]" --compact

```

**3. Retrieve the table of contents using a standard shortcut:**

```bash
officecli get myDoc.docx /toc

```

**4. Use schema-defined aliases for paragraph styles:**

```bash

# Assuming the schema defines 'header' as an alias for Heading1 style

officecli get myDoc.docx /body/paragraph[header]

```

**5. Combine multiple aliases in complex selectors:**

```bash
officecli query mySheet.xlsx "Sheet1!B2[size] && Sheet1!B2[color=red]"

```

## Key Implementation Files

Understanding the source architecture helps when debugging alias resolution or planning custom extensions:

- **[`CommandBuilder.GetQuery.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.GetQuery.cs)** – Injects the alias resolver for Excel selectors and builds the final query after normalization (lines 207-214 and 218-222).
- **[`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs)** – Recognizes the special `selected` pseudo-path before other dispatch logic (lines 1950-1958).
- **[`SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs)** – Loads per-format alias definitions from schema files at runtime (lines 198-207).
- **[`ExcelHandler.Selector.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.Selector.cs)** – Implements `ResolveCellAttributeAlias` for mapping cell attribute shortcuts (lines 224-229).
- **[`AttributeFilter.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/AttributeFilter.cs)** – Core engine that applies the alias map while parsing CSS-like selectors.

## Summary

- **Path aliases** in OfficeCLI provide short, memorable names for complex OpenXML paths.
- The system operates at multiple layers: root-level shortcuts (`selected`), schema-defined mappings, and Excel-specific cell attributes.
- **Alias resolution** occurs in [`CommandBuilder.GetQuery.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.GetQuery.cs) before query execution, ensuring consistent behavior across `get` and `query` commands.
- **Fallback handling** ensures that unrecognized paths are treated literally or raise helpful errors, preventing silent failures.
- Developers can extend the system by adding new aliases to schema files without modifying core code.

## Frequently Asked Questions

### What happens if I use an alias that doesn't exist?

OfficeCLI implements fallback handling that treats unrecognized aliases as literal paths. If the literal path also fails, the CLI returns a descriptive error indicating that the path could not be resolved, ensuring predictable behavior rather than silent failures.

### Can I create custom path aliases for my documents?

Yes. According to the implementation in [`SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs), aliases are defined in per-format schema files (for docx, xlsx, and pptx). By modifying these schema definitions, you can add new aliases that map to specific OpenXML paths, and the CLI will automatically load them at runtime without requiring code changes.

### Are path aliases supported for all Office document formats?

The alias system supports **docx**, **xlsx**, and **pptx** formats, though the specific aliases available vary by format. Excel files benefit from additional cell-attribute aliases (like `bold` and `size`) handled by `ExcelHandler`, while Word documents support structural aliases like `/toc` for table-of-contents elements.

### How do Excel cell aliases differ from document element aliases?

Excel cell aliases are **attribute-specific shortcuts** that only work within cell selectors (e.g., `Sheet1!A1[bold]`). These are resolved by `ExcelHandler.ResolveCellAttributeAlias` in [`ExcelHandler.Selector.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ExcelHandler.Selector.cs). Document element aliases, in contrast, are **structural shortcuts** that resolve to full element paths (like `/toc` or `selected`) and are handled earlier in the command pipeline.