# How to Create an Alias Page for an Existing Command in tldr-pages

> Easily create alias pages for existing commands in tldr pages using the set alias page script. Generate standardized pages, apply translation templates, and sync across languages.

- Repository: [tldr pages/tldr](https://github.com/tldr-pages/tldr)
- Tags: how-to-guide
- Published: 2026-03-05

---

**Use the [`scripts/set-alias-page.py`](https://github.com/tldr-pages/tldr/blob/main/scripts/set-alias-page.py) helper script to interactively generate standardized alias pages that reference existing commands, automatically applying translation templates and optionally syncing across all supported languages.**

The tldr-pages project maintains community-driven simplified manual pages for thousands of command-line tools. When a command functions as an alias of another—such as `gsum` being an alias for `gnumfmt`—the project uses lightweight alias pages rather than duplicating content. This guide explains how to create an alias page for an existing command in tldr-pages using the official maintainer scripts and repository structure.

## Understanding the Alias Page Architecture

Alias pages in tldr-pages are minimal Markdown files stored alongside regular command pages. Each alias page indicates that one command name redirects to another, containing a standardized message that directs users to the original command's documentation. The repository organizes these files into platform-specific subdirectories within language folders: `pages/` for English, `pages.fr/` for French, `pages.pt_BR/` for Brazilian Portuguese, and over 30 other locales.

## The set-alias-page.py Script

The tldr-pages repository provides a dedicated automation tool at [`scripts/set-alias-page.py`](https://github.com/tldr-pages/tldr/blob/main/scripts/set-alias-page.py) that handles the entire alias creation workflow. This script implements an interactive wizard for metadata collection, template rendering, file writing, and cross-language synchronization. It depends on shared utilities in [`scripts/_common.py`](https://github.com/tldr-pages/tldr/blob/main/scripts/_common.py), including the `create_argument_parser` function for CLI flag handling and the `stage` helper for git operations.

### Interactive Metadata Collection

When you execute the script with a target path, the `prompt_alias_page_info` function (lines 44-80 in [`scripts/set-alias-page.py`](https://github.com/tldr-pages/tldr/blob/main/scripts/set-alias-page.py)) initiates an interactive session to collect three essential fields:

- **Page title**: The display name for the command (defaults to the filename)
- **Original command**: The target command that this alias references
- **Documentation command**: The command users should look up for help (defaults to the original command)

### Template Generation and File Writing

After collecting metadata, the `generate_alias_page_content` function (lines 20-41) loads the language-specific template from [`contributing-guides/translation-templates/alias-pages.md`](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/translation-templates/alias-pages.md) and substitutes the collected values. The `set_alias_page` function (lines 45-61) then writes the generated Markdown to the appropriate location—such as [`pages/osx/gsum.md`](https://github.com/tldr-pages/tldr/blob/main/pages/osx/gsum.md)—and reports whether the operation added a new file or updated an existing one.

### Cross-Language Synchronization

To maintain consistency across the project's internationalization efforts, the `sync_alias_page_to_locale` function (lines 85-103) propagates alias pages from the English `pages/` directory to all translated locales. This ensures that when you create an alias in English, corresponding files automatically appear in `pages.fr/`, `pages.de/`, `pages.zh/`, and other language folders with appropriate template localization.

## Step-by-Step Workflow Examples

### Creating a New Alias Page Interactively

To create an alias page for `gsum` that points to `gnumfmt` on the macOS platform:

```bash
python3 scripts/set-alias-page.py -p osx/gsum

```

The script prompts you for metadata:

1. **Title**: Press Enter to accept `gsum` or type a custom title
2. **Original command**: Type `gnumfmt`
3. **Documentation command**: Press Enter to use `gnumfmt` (or specify if documentation lives under a different name)
4. **Confirmation**: Type `Y` to proceed

The resulting file at [`pages/osx/gsum.md`](https://github.com/tldr-pages/tldr/blob/main/pages/osx/gsum.md) contains:

```markdown

# gsum

> This command is an alias of `gnumfmt`.

- View documentation for the original command:

`tldr gnumfmt`

```

### Synchronizing Across All Translations

After creating the English alias page, propagate it to all supported languages:

```bash
python3 scripts/set-alias-page.py -S

```

This executes the `sync_alias_page_to_locale` function, creating matching files in `pages.fr/`, `pages.pt_BR/`, and other locale directories while preserving existing translations.

### Dry-Run and Staging Options

Verify changes before writing to disk:

```bash
python3 scripts/set-alias-page.py -p osx/gsum -n

```

The `-n` flag triggers a dry-run, displaying "page would be added" or "page would be updated" messages without modifying files.

To automatically stage created files for git commit:

```bash
python3 scripts/set-alias-page.py -p osx/gsum -s

```

The `-s` flag invokes the `stage` helper from [`scripts/_common.py`](https://github.com/tldr-pages/tldr/blob/main/scripts/_common.py) (lines 24-33) to execute `git add` on the generated files.

## Key Files and Components

Understanding the repository structure helps when debugging or manually editing alias pages:

- **[`scripts/set-alias-page.py`](https://github.com/tldr-pages/tldr/blob/main/scripts/set-alias-page.py)**: The main CLI tool containing `prompt_alias_page_info`, `generate_alias_page_content`, `set_alias_page`, and `sync_alias_page_to_locale`
- **[`scripts/_common.py`](https://github.com/tldr-pages/tldr/blob/main/scripts/_common.py)**: Shared utilities including `create_argument_parser` for CLI handling and `stage` for git operations
- **[`contributing-guides/translation-templates/alias-pages.md`](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/translation-templates/alias-pages.md)**: The template file used to render localized alias page content
- **`pages/`**: English language directory where alias pages are stored (e.g., [`pages/osx/gsum.md`](https://github.com/tldr-pages/tldr/blob/main/pages/osx/gsum.md))
- **`pages.<locale>/`**: Translated versions (e.g., `pages.fr/`, `pages.pt_BR/`) that receive synchronized alias pages

## Summary

Creating an alias page for an existing command in tldr-pages involves:

- Using the **[`scripts/set-alias-page.py`](https://github.com/tldr-pages/tldr/blob/main/scripts/set-alias-page.py)** helper to generate standardized alias pages through an interactive wizard
- Providing three metadata points: the **page title**, **original command**, and **documentation command**
- Leveraging **templates** from [`contributing-guides/translation-templates/alias-pages.md`](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/translation-templates/alias-pages.md) to ensure consistent formatting across languages
- Synchronizing across **all language translations** using the `-S` flag to maintain consistency in `pages.<locale>/` directories
- Utilizing **dry-run** (`-n`) and **staging** (`-s`) options to verify and prepare changes before committing

## Frequently Asked Questions

### What is the difference between an alias page and a regular tldr page?

A regular tldr page contains detailed examples, descriptions, and usage instructions for a specific command. An alias page is a lightweight placeholder that indicates one command name is an alias of another, containing only a reference to the original command's documentation rather than duplicated content. This prevents maintenance overhead when the original command's examples are updated.

### Can I create an alias page manually without using the set-alias-page.py script?

Yes, you can manually create an alias page by copying the template from [`contributing-guides/translation-templates/alias-pages.md`](https://github.com/tldr-pages/tldr/blob/main/contributing-guides/translation-templates/alias-pages.md) and placing it in the appropriate `pages/` subdirectory with the correct filename. However, using the script is strongly recommended because it validates metadata, ensures correct formatting, and can automatically synchronize the page across all language translations via the `sync_alias_page_to_locale` function.

### How do I update an existing alias page when the original command changes?

If the original command name changes or the documentation reference needs updating, run [`scripts/set-alias-page.py`](https://github.com/tldr-pages/tldr/blob/main/scripts/set-alias-page.py) with the `-p` flag pointing to the existing alias page path. The interactive wizard will prompt you for the new metadata, and the `set_alias_page` function will update the existing file. Afterward, use the `-S` flag to propagate these changes to all translated versions in other locale directories.

### Does the script support creating alias pages for all operating system platforms?

Yes, the script supports all platform-specific directories within the `pages/` structure, including `common/`, `linux/`, `osx/`, `windows/`, `android/`, and `sunos/`. When specifying the path with the `-p` argument, include the platform directory (for example, `linux/gsum` or `common/gnumfmt`) to ensure the alias page is created in the correct location according to the command's platform availability.