Metadata-Version: 2.3
Name: typer-alias
Version: 0.1.0
Summary: typer-alias is a lightweight extension for Typer that adds first-class command aliases while keeping the help output clean and user-friendly. Define a command once, expose it under multiple names, and display aliases directly in the CLI help.
Author: aaltatan
Author-email: aaltatan <a.altatan@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Dist: typer>=0.26.8
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/aaltatan/typer-alias
Project-URL: Issues, https://github.com/aaltatan/typer-alias/issues
Description-Content-Type: text/markdown

# typer-alias

> Add command aliases to your Typer CLI with clean, readable help output.

`typer-alias` is a tiny utility that extends
[Typer](https://typer.tiangolo.com/) by allowing a command to have one or
more aliases while keeping the generated help concise.

Instead of registering multiple command implementations, write your command
once and expose it under multiple names.

## Features

- ✅ Simple decorator API
- ✅ Support for unlimited aliases
- ✅ Aliases actually work as independent commands
- ✅ Clean help output
- ✅ Zero runtime dependencies besides Typer

---

## Installation

```bash
pip install typer-alias
```

---

## Quick Start

```python
import typer

from typer_alias import command

app = typer.Typer()


@command(
    app,
    name="list",
    aliases=("ls", "l"),
)
def get_all():
    """Get all users."""
    print("Getting users...")


if __name__ == "__main__":
    app()
```

All of the following commands execute the same function:

```bash
app list
app ls
app l
```

---

## Help Output

Instead of listing every alias as a separate command, the help is displayed as:

```text
Commands:

  list (ls, l)     Get all users.
```

This keeps the help page compact while still showing users every available
alias.

---

## API

### `command(...)`

A drop-in replacement for `@app.command`.

```python
command(
    app,
    *,
    name=None,
    aliases=None,
    help=None,
    hidden=False,
    ...
)
```

### Parameters

| Parameter | Description |
| ----------- | ------------- |
| `app` | The `typer.Typer` application. |
| `name` | Override the command name. Defaults to the function name. |
| `aliases` | Iterable of alternative command names. |
| `help` | Command help text. |
| `hidden` | Hide the command from help output. |
| `cls` | Custom `TyperCommand` class. |
| `context_settings` | Click context settings. |
| `epilog` | Help epilog. |
| `options_metavar` | Override options metavar. |
| `add_help_option` | Enable/disable `--help`. |
| `no_args_is_help` | Show help when no arguments are supplied. |
| `deprecated` | Mark the command as deprecated. |
| `rich_help_panel` | Rich help panel name. |

All other behavior matches Typer's built-in `@app.command`.

---

## Example

```python
import typer

from typer_alias import command

app = typer.Typer()


@command(
    app,
    aliases=("rm", "delete"),
)
def remove():
    """Remove an item."""
    print("Removing...")


@command(
    app,
    name="list",
    aliases=("ls",),
)
def get_all():
    """List all items."""
    print("Listing...")


if __name__ == "__main__":
    app()
```

Usage:

```bash
app remove
app rm
app delete

app list
app ls
```

---

## Why?

Typer (and Click) do not provide an ergonomic way to define command aliases
that also produce clean help output.

This package solves that by:

- registering each alias as a hidden command
- exposing a single visible command
- displaying aliases inline in the command list

---

## Compatibility

- Python 3.12+
- Typer

---

## License

MIT
