Seafoam-Labs/Shelly-ALPM: bare shelly is an alias for upgrade everything, a diff-collapse default that applies to configs which never set it, and two package backends in one binary

Bare shelly is an alias for upgrade everything

Three separate configuration sections in this document make the same remark, which means it is load-bearing rather than incidental. Each one says its setting also applies to the combined-upgrade aliases, and then names them: bare shelly, and shelly with the all-upgrade flag. So invoking the program with no arguments upgrades every installed package it manages. A bare command name that silently performs a system-wide operation is a design choice with consequences for muscle memory, for shell history, and for any script that constructs a command by concatenating a variable. The document is not hiding it, and each section also points out that the explicit per-subsystem forms remain available, so an AppImage upgrade can still be asked for on its own, as can a Flatpak upgrade and a list of updates. The one-shot flags follow the same pattern, with an all-upgrade form that skips AppImages and another that skips Flatpak. What is missing is a line anywhere saying that running the bare command upgrades your system.

A diff default that reaches back into configs that never set it

The package-review setting is the one with a migration hazard. Collapsed diffs are the default, and the document states that this applies to existing configurations that do not contain the setting, which is the phrasing of a behaviour that was extended backwards rather than introduced for new installs. The effect is that a user upgrading the tool sees their terminal package reviews change shape without having asked for it. There is a documented command to show the whole file during review and another to restore the collapsed view. The second half of the paragraph is the part that makes the setting misnamed. The setting controls terminal review output only, and graphical reviews continue to receive the complete diff. So a key with a general name changes behaviour in one of three front ends. The surrounding safety machinery is unaffected, since security warnings, attached source files and approval prompts are all described as handled as before, and the first review with no previous recipe file shows the complete thing regardless.

Two cache settings exist and the documented one silently wins

The cache-cleanup section documents a key that skips the cleanup prompt and the deletion during a combined upgrade, gives it a default of false, and gives a command to restore the behaviour. One sentence in the middle says it takes precedence over a differently named setting. That other setting is named nowhere else in the document. It appears exactly once, as the thing the documented key overrides, which means a reader can learn that a second cache setting exists, learn its name, and learn nothing about what it does, what its default is, or how to set it. So the configuration surface contains at least six keys where five are documented. The consequences of that are small in the case at hand and larger in principle, because a key that overrides an undocumented key is a key whose behaviour you cannot reason about from the documentation. The rest of the section is clear: standalone upgrade of native packages keeps its own cleanup behaviour, and you can still clean the cache by hand.

The AUR removal check fails closed, and that is the best thing here

Four rules govern when a package may be built from the user repository, and all four point the same way. The requested package must be listed by the configured service, and so must every build dependency it needs. Cached checkouts and surviving git repositories do not authorise building a package that has been removed, which is the rule that matters, because it means deletion is enforced rather than merely discouraged and a machine that cloned a package before it was pulled cannot keep building it. The same applies to version-pinned installs, so pinning a version is not a way around the check. And when the service cannot be reached at all, the instruction is to retry once the connection is restored, which means no build happens on an unverifiable answer rather than a build happening optimistically. The escape routes are correctly scoped: an unavailable package with an exact match in a configured repository gets a suggestion, and explicit local builds from a recipe file on disk, plus removal of installed packages, need no availability check at all.

Two package backends ship in one binary and the default links the system library

The architectural decision is in a short section near the top. Shelly performs native package operations through either the system package library or the project's own reimplementation of it, and default builds include both. The switch is a configuration key with a documented value for each direction:

shelly config set NativePackageBackend rlpm

The default is the system library, which means the default binary links against whatever the distribution ships and inherits whatever patches that distribution carries, and the feature list notes the goal of retaining the extensions a particular distro adds. The alternative is a from-scratch reimplementation that has to reproduce another library's behaviour, including its extensions, to be a substitute. The backend guide covers defaults, packaging and verification, and it refers to release acceptance gates that are still open, which is the honest signal that the two engines are not yet equally finished. Building a binary with only the reimplementation is a compile-time option rather than a config switch, so the RLPM-only build is a different artefact rather than a different setting.

Seven packaging recipes, one unexplained name, and the default branch is development

The repository root holds seven recipe files. There is a base one, a binary one, a command-line-only one, a source-build one, a split one, and git-tracking variants of two of those. The split variants exist to match the project layout, since the code is a set of separate components that could reasonably be one package or several. The git variants track the source branch, which matters because the default branch is named development rather than main, so a git-flavoured install follows unreleased work rather than a release. The seventh recipe is named for a variant the document never mentions, and no visible section explains what it contains or who it is for. That is a small thing and an odd one to find in a project otherwise careful about naming its settings. Two other files at the root explain the release process rather than the software: a manual testing document and a security policy. A manual testing checklist committed alongside the code is the mark of a project that expects a human to press the buttons before a version ships, which pairs with the backend acceptance gates and with a release naming convention that is not consistent. Of the three most recent releases, one is titled with the version repeated and the word Bug Fix, one uses a hyphen and a marketing phrase about views and builds, and one uses a pun on a term from the package world that a newcomer will not decode. The install commands are consistent, at least: one command from the distribution's own repositories, and two alternatives for the two most common AUR helpers, with matching removal commands for each of the three.

Purge deletes archives and signatures but keeps recipes, in one cache location only

The cache-cleaning command has an option that deletes built user-repository package archives and their matching signatures from the invoking user's cache directory, defaulting to a path under the home directory. The word all is emphasised in the documentation, and the boundary is drawn carefully: recipe files, checkout history, source files and build directories are all retained, so what goes is compiled output rather than the instructions that produced it. Signatures are deleted paired with their archives rather than independently, which is the correct pairing. Two limits are stated. The option works without the standard cache flag, in which case the standard check still looks for corrupted archives. And archives written to a custom build output destination outside the cache are not included, so a user who redirected build output will find purge does nothing for it. The cache is scoped to the invoking user, and the documented install path runs under administrative privileges, so the two commands have to be run by the same person for the purge to hit the cache the installer filled.

Isolated builds ship with two named gaps and one incompatibility

There is a flag that builds a package from the user repository inside a fresh native build root before installing it, and the division of labour is specific: repository build dependencies stay inside the guest, while the exported package and its runtime dependencies are installed on the host. That is a deliberate boundary rather than a full chroot, and it means the host is exposed to the finished package while the build inputs stay contained. The documentation then names what does not work: user-repository-only build dependencies are unsupported, package signing is unsupported, and the flag cannot be combined with the chroot mode or with dependency-only installation. Naming three limitations for a new build mode is more disclosure than most installers of this kind provide, and it tells a reader exactly which of their workflows will need to stay on the older path. The pure local route stays open, since building straight from a recipe file on disk needs no availability check and no guest at all. The roadmap confirms the surface is still moving, listing repository modification as in progress, which is the capability that would change what a package manager like this is for.

Editorial conclusion

This is a package manager with real design thought behind it, and three decisions deserve credit before the caveats. The AUR availability check is the part to read twice: it gates the package and its build dependencies, it applies to version-pinned installs, a deleted package cannot be rebuilt from a surviving checkout, and an unreachable service produces a retry rather than a build. That is a supply chain designed by someone who has thought about deletions. The two-tier escape hatch for AppImage and Flatpak handling, where each subsystem has both a persistent key with a documented default and a one-shot flag for a single run, is applied consistently and is what other projects should copy. And Flatpak is an optional add-on package rather than a dependency of the base one. Four things to weigh. Bare shelly performs a full upgrade, which is not what an unqualified command name suggests, so script against the explicit verbs. Five documented settings plus one referenced and unexplained means the configuration surface is still growing, and the roadmap says so. Both backends ship in one binary with acceptance gates still open on one of them, so check which engine your build actually linked. And seven packaging variants, one of them named in a way nothing explains, is a lot of surface for a project at 3.1.6. For an Arch or CachyOS user who wants a graphical front end and does not mind reading a release's gates, that is a fair trade. For automation, use the explicit verbs and pin your backend.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes