Flatalias is a lightweight CLI tool that generates short, convenient command aliases for installed Flatpak applications and makes them available in your shell. For example, if you have the Mozilla Firefox Flatpak installed, you no longer have to remember the full Flatpak ID and can launch it with firefox instead.
Made with ❤️ by Daniel Rudolf (@PhrozenByte).
- 🔍 About
- 📥 Install
- 🚀 Usage
- ⚖️ License & Copyright
Flatalias' flatalias script scans all Flatpak applications installed on your system and automatically generates suitable short command aliases. It derives each alias from the command that is executed by default when launching the Flatpak. To ensure the alias makes sense, Flatalias performs a plausibility check by comparing the command's basename with the application ID using fuzzy matching (via fzf). If this check fails, no alias is created and an error is reported.
If Flatalias cannot determine a suitable alias automatically, aliases can also be defined manually. Flatpak maintainers can specify an alias using the x-command-alias field in the Flatpak metadata. Additionally, users can define aliases in flatalias.list configuration files. Each file contains lines in the format <Flatpak ID>=<Alias>. Set the alias name to - to disable creating an alias for that Flatpak. Empty lines and lines starting with # are ignored, while invalid entries are skipped and errors are logged accordingly. Flatalias reads aliases from multiple locations, in the following order: the bundled flatalias.list file, the system-wide /etc/flatalias/flatalias.list, and the user-specific $XDG_CONFIG_HOME/flatalias/flatalias.list (typically ~/.config/flatalias/flatalias.list).
When executing an alias generated by Flatalias, the application is not launched via flatpak run. Instead, Flatalias searches the $PATH for an executable matching the Flatpak application ID. This leverages the wrapper scripts automatically created by Flatpak in /var/lib/flatpak/exports/bin/ (system-wide) and ~/.local/share/flatpak/exports/bin/ (user installs). This approach also allows users to override behavior. For example, if you place a custom script at /usr/local/bin/org.mozilla.firefox, the firefox alias will execute that script instead.
Flatalias does not regenerate aliases on every shell startup. Instead, it caches them in $XDG_STATE_HOME/flatalias.profile (typically ~/.local/state/flatalias.profile). This file is automatically sourced in interactive login shells via Flatalias' /etc/profile.d/90-flatalias.sh hook script. Note that /etc/profile.d hooks are usually only called once per user session, not every time when opening a new shell (see shell integration instructions below). As with any cache, it can become outdated, for example when installing or removing a Flatpak. Aliases can be refreshed by running flatalias manually or by using the provided systemd units. To enable automatic updates, activate the flatalias.service unit and flatalias.path unit in your user session (see auto-update instructions below). Enabling the service unit tells systemd to run Flatalias on login. Enabling the path unit additionally tells systemd to monitor Flatpak changes and automatically run Flatalias whenever applications are installed, updated, or removed.
Pull requests adding more Flatpak aliases to flatalias.list are very welcome, provided Flatalias' algorithm fails to guess a suitable alias. A prerequisite is that stable versions of that Flatpak are published on Flathub. When in doubt, create a pull request – sharing is caring!
Flatalias is free and open-source software, released under the terms of the GNU General Public License v3. Pull requests to improve or extend Flatalias, or to fix any issues, are very welcome! For major changes, please open an issue first before starting development – it's always better to discuss major changes beforehand. If you encounter any issues with Flatalias, don't hesitate to open a new issue on GitHub – but please check Flatalias' documentation and previous GitHub issues first.
Flatalias was written for GNU Bash. It depends on Flatpak (obviously…), fzf, awk (e.g., GNU awk, or BSD awk, or any other implementation), and common Linux utilities (e.g., BusyBox (just its utilities, not ash), or GNU coreutils, or any other basic coreutils implementation).
If you're running Arch Linux, you can install the flatalias AUR package.
To install Flatalias from sources, you just need to obtain the source code (by either cloning the Git repository or by downloading one of Flatalias' source archives; see GitHub's releases page), and run make (e.g., GNU Make, but it should work with any make implementation):
$ git clone https://github.com/PhrozenByte/flatalias.git
$ cd ./flatalias
$ make installThis will install Flatalias to /usr/local (i.e., /usr/local/bin/flatalias). Flatalias' Makefile mostly follows GNU's Makefile Conventions and supports its well-known variables (most notably prefix and DESTDIR). So, if you want to install Flatalias to /usr instead, run make install prefix=/usr.
Installing Flatalias to your home directory is also possible. In that case, you must pass the SYSTEMD_USER_UNIT_PATH and PROFILE_PATH variables to tell make where to install Flatalias' systemd units (normally /etc/systemd/user, but ~/.config/systemd for user installs) and Flatalias' shell inclusion script (normally /etc/profile.d, but something like ~/.bashrc.d for user installs):
$ make install prefix=~/.local \
SYSTEMD_USER_UNIT_PATH=~/.config/systemd \
PROFILE_PATH=~/.bashrc.dTo uninstall Flatalias, run make uninstall with the same variables. However, please note that make uninstall does not remove skeleton directories. With prefixes like /usr and /usr/local (default), there is usually no need to worry about this. For custom prefixes such as /opt/flatalias, some empty directories may remain. You can remove them manually, e.g. using rm -rf /opt/flatalias.
Flatalias' Makefile requires the GNU coreutils (specifically), an implementation of find and xargs (e.g., GNU findutils, but any implementation should work), as well as sed (e.g., GNU sed, but any implementation should work).
Using Flatalias is simple: just run flatalias:
$ flatalias
+ alias ptyxis=/var/lib/flatpak/exports/bin/app.devsuite.Ptyxis
+ alias gimp=/var/lib/flatpak/exports/bin/org.gimp.GIMP
+ alias firefox=/var/lib/flatpak/exports/bin/org.mozilla.firefoxOpen a new login shell, or execute source <(flatalias -) to load the aliases into your current session.
If you have the Mozilla Firefox Flatpak installed, you can then start it by running firefox.
Flatalias installs a profile script at /etc/profile.d/90-flatalias.sh, which is automatically sourced for interactive login shells. This ensures that aliases are immediately available. However, most terminal emulators (e.g., the Ptyxis Flatpak, unless configured otherwise) start non-login interactive shells by default. In such cases, the profile script is not sourced again, and newly generated aliases may not be available immediately.
If you want aliases to be refreshed more frequently (e.g., for every new terminal session), you can source the Flatalias profile script manually from your shell configuration. For example, add the following to your ~/.bashrc (current user only) or /etc/bash.bashrc (system-wide):
[ -f /etc/profile.d/90-flatalias.sh ] && . /etc/profile.d/90-flatalias.shAlternatively, you can run source <(flatalias -) directly to update aliases in the current shell session.
Run flatalias whenever you install or remove a Flatpak.
If you prefer automation, enable Flatalias' systemd units: the flatalias.service unit and flatalias.path unit:
$ systemctl --user enable --now flatalias.service flatalias.pathThe service unit tells systemd to run Flatalias on login. The path unit monitors Flatpak changes and triggers the service again whenever Flatpak applications are installed or removed, keeping your aliases up-to-date.
Here is Flatalias' full CLI help (available with flatalias --help):
Usage:
flatalias [-q|--quiet] [FLATALIAS_FILE]
Generate short, convenient shell aliases for Flatpak applications.
Flatalias scans installed Flatpaks, derives suitable aliases from their
default commands, and makes them available in your shell environment.
Arguments:
FLATALIAS_FILE write cached Flatpak aliases to this file, or pass '-' to
print to stdout; default: '$XDG_STATE_HOME/flatalias.profile'
Application options:
-q, --quiet suppress Flatalias' logging
Help options:
--help display this help and exit
--version output version information and exit
Visit us on GitHub: <https://github.com/PhrozenByte/flatalias>
Made with ♥ by Daniel Rudolf <https://www.daniel-rudolf.de/>
Copyright (C) 2026 Daniel Rudolf <https://www.daniel-rudolf.de>
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License only.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.