# How Path Aliases Work in OfficeCLI: Defining Custom Shortcuts for Document Paths

> Learn how OfficeCLI path aliases create custom shortcuts for document paths. Define aliases in schema files or .officeclialiases for easier command execution.

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

---

**OfficeCLI path aliases are human-friendly identifiers that the CLI expands to full internal document paths before command execution, allowing you to use shortcuts like `/body` instead of `/document/body` by defining them in schema files or a `.officeclialiases` JSON configuration file.**

OfficeCLI is a command-line interface for automating Microsoft Office documents (Word, Excel, PowerPoint) through a resident server architecture. Understanding how **path aliases** function in OfficeCLI is essential for writing concise, maintainable automation scripts. This guide explains the alias resolution mechanism implemented in the source code and demonstrates how to create custom shortcuts for your document paths.

## Understanding OfficeCLI Path Aliases

In OfficeCLI, a **path alias** is a short identifier that the CLI expands to a full internal document path before the command reaches the resident process. This mechanism allows you to write commands such as:

```bash
officecli set my.docx /body/paragraph[1] --prop text="Hello"

```

Instead of the longer canonical form `"/document/body/paragraph[1]"`.

The alias resolution is performed **before any command execution**, ensuring the same shortcuts work for all CLI verbs (`set`, `add`, `get`, `delete`) and across every document type (Word `.docx`, Excel `.xlsx`, PowerPoint `.pptx`). According to the OfficeCLI source code, this normalization happens in two critical locations:

- **[`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs)** (around line 2073) – Receives batch items and applies the alias-normalisation step before forwarding to the document resident (see the comment "`path` aliases `selector`").
- **[`CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.cs)** (around line 2080) – Contains the core `RewritePath` routine that expands aliases, ensuring consistency with the UI-layer behavior (marked by the "CONSISTENCY(cell-selector-alias)" comment).

## How Alias Resolution Works

When the CLI parses a batch item, it **normalises the `path` field** through a three-step process:

1. **Element Aliases** – Looks up aliases declared in the document schema (e.g., `"body"` maps to the root element of a Word document).
2. **Positional Aliases** – Applies shorthand patterns (e.g., `"/toc[N]"` expands to `"/document/toc[N]"`).
3. **Legacy Rewrites** – Converts legacy shortcuts (e.g., `"/body"` → `"/document/body"`).

Because this logic lives in the resident server and command builder, the expansion happens transparently regardless of which operation you perform.

## Where OfficeCLI Aliases Are Defined

Aliases are **declared in the schema files** that describe each document type. Each schema contains an `elementAliases` array that maps short names to canonical element paths. For example, the Word schema includes:

```json
{
  "elementAliases": [
    "body",
    "section",
    "paragraph",
    "table"
  ]
}

```

During startup, the **`SchemaHelpLoader`** class (see the static dictionary around line 198 in [`SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs)) builds an in-memory cache called `_aliasCache`. This cache maps the canonical format to the real element name and is consulted by the resident server whenever a path alias appears in your command.

## Creating Custom Path Aliases in OfficeCLI

You can define project-specific shortcuts using two pure-data methods that require no code changes:

### Method 1: Schema Extension

Extend the existing schema JSON with custom aliases. Edit the appropriate schema file under `schemas/` (e.g., [`schemas/word.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/word.json)) to add your entries. The CLI automatically picks up these changes the next time the schema loads.

### Method 2: User-Level Alias File (Recommended)

Create a JSON file named **`.officeclialiases`** in your project root. The CLI looks for this file at startup and merges its entries into the alias cache, allowing per-project overrides without modifying official schemas.

```json
{
  "myIntro": "/document/section[1]/paragraph[1]",
  "summary": "/document/section[2]/paragraph[3]"
}

```

Place this file next to your `.docx` or `.xlsx` files. For temporary overrides, you can also use the environment variable `OFFICECLI_PATH_ALIASES`:

```bash
export OFFICECLI_PATH_ALIASES='{"summary":"/document/section[2]/paragraph[3]"}'
officecli get report.docx /summary --prop text

```

## Using Path Aliases in Commands

Once defined, use aliases in any CLI command:

```bash

# Built-in alias

officecli get my.docx /body --prop text

# Custom alias from .officeclialiases

officecli set my.docx /myIntro --prop text="Welcome"

# Positional alias for Excel tables

officecli add my.xlsx /table[2] --prop rows=5 cols=3

```

When using the Node SDK, aliases work identically:

```typescript
import { open } from '@officecli/sdk';

const doc = await open('reports/annual.docx');

// Built-in alias
await doc.send({ command: 'get', path: '/body' });

// Custom alias
await doc.send({ command: 'set', path: '/myIntro', props: { text: 'Welcome!' } });

```

## Summary

- **OfficeCLI path aliases** are resolved in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) and [`CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.cs) before commands execute, making them universally available across all verbs and document types.
- Built-in aliases are defined in schema files (e.g., [`schemas/word.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/word.json)) and cached by [`SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs) at startup.
- Custom shortcuts can be added by editing schema files or creating a `.officeclialiases` JSON file in your project root.
- The `RewritePath` routine in [`CommandBuilder.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.cs) (around line 2080) handles the expansion logic, ensuring consistency with the UI layer.
- Aliases work in both the CLI interface and the Node SDK without requiring code changes.

## Frequently Asked Questions

### Can I use path aliases with all OfficeCLI commands?

Yes. Because alias resolution occurs during the path normalization phase in [`ResidentServer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ResidentServer.cs) before dispatch, shortcuts work transparently with all verbs including `get`, `set`, `add`, and `delete`. The expansion happens uniformly regardless of which operation you perform or which document type you target.

### What format does the `.officeclialiases` file use?

The `.officeclialiases` file uses standard JSON format with key-value pairs where the key is your custom alias (e.g., `"myIntro"`) and the value is the full canonical path (e.g., `"/document/section[1]/paragraph[1]"`). The CLI merges these entries into the `_aliasCache` built by [`SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs) during startup.

### Where should I place my custom alias definitions?

Place the `.officeclialiases` file in your project root directory alongside your document files. Alternatively, you can modify the schema files in the `schemas/` directory (such as [`word.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/word.json) or [`excel.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/excel.json)), though the `.officeclialiases` approach is preferred for project-specific shortcuts that shouldn't affect the global schema configuration.

### Do custom aliases work across different Office document types?

Yes, but they are scoped by schema. An alias defined in `.officeclialiases` or a Word schema file will work for any `.docx` file, while Excel-specific aliases apply to `.xlsx` files. If you define a custom alias in `.officeclialiases`, it becomes available for all document types processed in that directory, provided the underlying path structure is valid for the specific document format.