Intro

Git aliases for any command-line program.

Inspired by git aliases, alias lets you define custom aliases, commands, and subcommands for any CLI — even if the program itself has no alias support.

Your aliases behave like built-in commands, without polluting your shell configuration or requiring separate wrapper scripts.

Technically, alias is just a thin wrapper around the target command-line application.

Table of contents

1. Technical notes
2. Installation
3. Alias types
4. Alias groups and subcommands
5. List of aliases
6. Override
7. Target executable location
8. Different operating systems
9. Shell scripts on Windows
10. Examples

Technical notes

Technically, it is just a thin wrapper (proxy) that conditionally runs the target program.
If an alias is found, it is expanded and the resolved version is used; otherwise, the target executable is called with the original arguments.

This app is independent of

1. the target program that needs alias support
2. the operating system
3. the shell/command interpreter

Configuration settings are stored in a separate config file,
therefore, you do not need to pollute the global namespace with shell aliases (using .zshrc/.bashrc/.profile, etc.).

Installation

Manual

1. Put the executable in a directory on your PATH, and name it the same as the target program (the program without alias support)
   You can get prebuilt binaries here
2. Write a config (config.toml) and put it next to the executable
   (a sample config will be created on the first launch if it does not exist)
3. Use custom aliases just as if they were supported out of the box.

Automatic

You can use this snippet to install the alias binary under a selected name into the ${HOME}/bin/<APP_NAME>-aliases directory, where <APP_NAME> is the name of the app that you want to configure

    curl -fsSL "https://raw.githubusercontent.com/yantonov/alias/master/bin/install/install.sh" | bash -s -- "<APP_NAME>"

Alias types

Regular alias — expands to a sequence of arguments passed to the target program:

[alias]
co = "checkout main"

Command	Expands to
git co	git checkout main

Shell alias — prefixed with !, executed by the current shell:

[alias]
clean = "!rm -rf *.tmp"

Command	Expands to
git clean	rm -rf *.tmp

Alias groups and subcommands

Aliases can be organized into groups using TOML table nesting — or, from the user's perspective, you are defining custom subcommands. Both metaphors describe the same thing: a multi-word prefix that routes to a specific alias.

This is useful when a tool lacks a subcommand you want (docker cleanup, git sync, etc.) or when you want to extend an existing one. Groups allow you to use multi-word alias prefixes and can be nested to arbitrary depth.

One-level group:

[alias]
ps  = "container ls"
rmi = "image rm"

Command	Expands to
docker ps	docker container ls

Nested groups:

[alias.container]
clean = "!docker container prune -f"

[alias.image]
build = "image build -t" # group / subcommand
ls    = "image ls"

[alias.container.log]
tail = "!docker logs -f"     # doubly-nested group

Command	Expands to
docker container clean	docker container prune -f
docker image build myapp	docker image build -t myapp
docker container log tail	docker logs -f

List of aliases

The list of aliases can be shown by using the --aliases parameter.

Override

You can add an additional configuration file 'override.toml' to the same directory.
This helps you to redefine existing aliases or introduce new ones that depend on the environment.
Motivation: some aliases may be specific to the working environment, and you do not want to expose them by sharing them in a public repository.

Target executable location

There are two options:

1. You can explicitly define the target executable using the 'executable' parameter (see the example here).
2. Without explicit configuration, the app tries to detect the target executable automatically by looking for an existing file with the same name later in the PATH.
   In that case, you have to place this alias application in front of the target executable in the PATH variable.

Different operating systems

Different operating systems place binary files in different directories.
To handle this, it is possible to reference the target executable using environment variables (example: executable="${HOME}/tools/bin/app")
This helps you to use the same config file across different operating systems.

Shell scripts on Windows

When you try to use a shell script directly as a target executable, you can face the problem '%1 is not a valid win32 application'.
To deal with this issue, you can add the run_as_shell=true parameter to the config (or to the override file if you prefer); this will allow you to run the script using the current shell.

Examples

Sample config can be found here.

A few more realistic examples:

1. docker aliases
2. podman aliases
3. uv aliases
4. cdt aliases
5. gw aliases
6. arc aliases
7. ya tool aliases