Gear Lever: making AppImages behave like installed software

The gap between an AppImage and an installed app

An AppImage is a single file that runs. There is no installation step, no package manager entry, and no registry. That is what makes the format attractive and portable, and it is exactly why the file does not appear in your application menu, has no icon of its own, and updates itself only when its author publishes a newer file somewhere.

Gear Lever's feature list is written entirely in terms of that gap. Integrate AppImages into your app menu with just one click, drag and drop files directly from your file manager, keep all the AppImages organized in a custom folder, open new AppImages directly with Gear Lever, and manage updates by keeping older versions installed or replacing them with the latest release. Each item is a desktop integration concern rather than an application feature, which is the clearest statement of what this project is.

The project is a Python application distributed on Flathub, which is why the homepage points at a hosted documentation site rather than a docs directory in the repository. The description on GitHub is simply Manage AppImages with ease, and the stars sit at just over 2200 with 96 forks, a ratio that suggests a tool people install and keep rather than one they contribute to heavily.

A CLI that shares logic with the window

Since version 3.0.0 the application includes command line tools, and the README makes a point that matters for anyone automating this: the CLI uses the same logic as the UI. That is a design decision with real consequences. Tools that reimplement logic for a command line tend to drift from the interface, and drift is exactly what bites when you build a script against them.

flatpak run it.mijorus.gearlever --help

The flag set is small and readable: integrate, update, remove, list installed, list updates, set a custom update source, and fetch updates. The fetch flag is described as being used on system startup and sending a desktop notification, which tells you the intended deployment pattern is a session startup entry rather than something you run by hand.

There is a shell alias recommendation for convenience:

alias gearlever='flatpak run it.mijorus.gearlever'

Add that to your `.bashrc` and the command works without the flatpak prefix. The remove flag is described as trashing an AppImage together with its desktop file and icons, which is a much more considerate default than deleting, and it is the kind of detail that separates a tool built by someone who has cleaned up after a bad integration before.

JSON output with a declared schema

The list commands accept a `--json` flag for machine-readable output:

gearlever --list-installed --json
gearlever --list-updates --json

The README goes further than announcing the flag. It states that the documents have `schema_version: 1` and an `installed` or `updates` array, that each entry contains its name, path, desktop ID, current and available versions, download size, update manager, whether its source is embedded, and whether the AppImage is running, and that unavailable metadata is reported as `null` while an empty list is an empty array.

That is a genuine design document in four sentences. A versioned schema means a consumer can detect a format change rather than guessing. Explicit `null` rather than a missing key removes the most common class of parsing bug. Distinguishing an embedded update source from an external one tells you where the update will come from before you run it. And reporting whether the AppImage is currently running tells you whether updating it will fail because the file is open.

For a desktop utility, this is more care than most projects show, and it makes the difference between a command you run to look at something and a command you can build on.

Python, GTK, Meson and a small dependency list

The tree shows a GNOME-oriented project rather than a generic Python application. Beyond the usual `.github/`, `src/` and `tests/`, there is `po/` for translations, `data/` for icons and desktop files, `it.mijorus.gearlever.json` for the Flatpak manifest, `meson.build` for the native build, `pyrightconfig.json` for type checking, and a `gearlever.code-workspace` for the editor.

The runtime dependencies in `requirements.txt` are five and specific:

dbus-python == 1.2.18
pyxdg == 0.28
ftputil == 5.1.0
requests >= 2.25.1
desktop-entry-lib == 5.0

Each one maps to a described feature. `desktop-entry-lib` is the `.desktop` file handling the integration depends on. `pyxdg` deals with XDG directories, which is how it knows where to put icons and desktop files. `ftputil` is for FTP based update sources, which is an older transport that some AppImage authors still use. `dbus-python` is for talking to the session bus, which is how a freshly integrated application can be launched and how the menu gets refreshed. `requests` is HTTP. There is no web framework and no ORM, so the application logic is local file manipulation plus network requests, which matches the feature list exactly.

The Meson build and the Flatpak manifest coexist because there are two audiences: packagers who build the native application, and Flathub users who install the sandboxed build.

Two distributions, one deliberate permission gap

The README offers the Flathub listing as the primary download and also points to GitHub releases, with an explicit parenthetical: no auto-updates. That difference is the whole story of the two channels. The Flathub build is sandboxed but the host grants it the Flatpak system bus permission, so it can launch integrated applications and refresh the menu. The GitHub bundle is unsandboxed and portable, which means it can be moved between machines, but it has no auto-updates and no session startup hook.

The permission situation is documented explicitly:

--talk-name=org.freedesktop.Flatpak

The README explains that this is required to open apps and refresh the system menu when a new app is installed, and that if you disable it manually with Flatseal, Gear Lever should continue to work normally except that you could no longer open apps directly. Describing the degraded mode instead of just declaring the permission is good practice, and it tells you the failure mode is a missing feature rather than a broken application.

For someone packaging this themselves, that single permission is the one thing to get right. The maintenance instructions recommend opening the project in GNOME Builder and pressing the run button, and offer a flatpak-builder command line as the alternative:

flatpak-builder build/ it.mijorus.gearlever.json --user --force-clean

The test suite has its own documented workflow: download the release archive from the separate gearlever-test-files repository, extract it under `test/`, and run `python3 -m unittest tests/test_cli.py`. Using a fixture repository of real AppImages for CLI tests is the right call, since the interesting behaviour is all in how real files are parsed.

Editorial conclusion

Gear Lever occupies a narrow, real gap: the AppImage format is deliberately installation-free, so nothing in the desktop handles it, and Gear Lever is the layer that does. The feature list is short enough to read in one screen, the CLI mirrors the UI logic rather than duplicating it, and the Flathub and bundle distributions cover both the sandboxed and unsandboxed cases. What the repository does not settle is how updates behave for AppImages whose authors publish no update metadata, which is the question that decides whether you keep this installed. Try the CLI first with the json flags, since that tells you more about what it found than the UI would.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. mijorus/gearlever on GitHub
3. Project website
4. README
5. Releases