Skip to content
Seafoam Labs

All versions since v3.1.2

All versions

v3.1.2

What’s Changed

New Contributors

Full Changelog: https://github.com/Seafoam-Labs/Shelly-ALPM/compare/v3.1.1...v3.1.2

Shelly-ALPM v3.1.3 — A Little Housekeeping, a Lot of Building

Shelly v3.1.3 gives your AUR cache a cleanup button, your AppImages their own environment settings, and the package builder another round of fixes for the PKGBUILDs you use every day.

There is plenty happening on the desktop, too: Flathub links take you to the app you wanted, package conflict prompts explain what is being removed, and the parallel download setting now does what it says. Behind the scenes, isolated builds gain Shelly’s own provisioning helper and new tools for build automation.

🧹 Give your AUR cache some breathing room

Built AUR packages can add up. You can now preview and remove those archives with --aur-cache:

Terminal window
# See what would be removed
shelly purify standard --aur-cache --dry-run


# Review and confirm the cleanup
shelly purify standard --aur-cache

This removes all built AUR package archives and their matching signatures from Shelly’s cache. Your PKGBUILDs, checkout history, sources, and build directories stay in place. You can also combine it with --cache to clean the standard package cache in the same command.

Prefer to handle cleanup yourself after upgrades? There is a setting for that:

Terminal window
shelly config set DisableCacheClean true

It skips the cleanup prompt and deletion during shelly upgrade all and its aliases. Cleanup remains enabled by default, and standalone shelly upgrade standard keeps its existing behavior.

🎛️ Your AppImages, your environment

Each installed AppImage can now have its own environment variables, configurable from the UI or CLI:

Terminal window
shelly config appimage "MyApp" --set-env "MY_VARIABLE=my-value"
shelly config appimage "MyApp" --unset-env "MY_VARIABLE"

Replace MyApp with the exact installed AppImage name. Overrides apply when launching from the desktop or through shelly run, and they survive AppImage updates. The CLI also supports clearing or replacing the full set of overrides.

StaticURL update checks now follow redirects correctly, too.

🏗️ More PKGBUILDs feeling at home

This release fixes several cases where valid package recipes could trip up Shelly’s native builder:

  • Fixed shell here-string and command-substitution parsing that could leave build wrapper scripts with syntax errors.
  • Added a consistent SOURCE_DATE_EPOCH throughout PKGBUILD evaluation, build steps, and package metadata.
  • Improved dependency planning for conditional arrays, architecture-specific dependencies, and split packages.
  • Improved archive detection and extraction, including extensionless archives.
  • Added standalone gzip/Unix compress, bzip2, xz, and zstd decompression before prepare(), respecting source aliases and noextract.
  • Fixed empty optional file assignments such as install='' being rejected as unsafe paths.
  • Failed binary stripping now produces a warning and keeps the original file. This fixes builds such as pi that include binaries the host’s strip tool cannot process.
  • Fixed source verification with multiple PGP signatures to follow signature-status handling, plus keyserver argument ordering during key imports.

🛠️ Shellystrap and build automation

Isolated builds now use shellystrap, Shelly’s own libalpm-based helper, to provision fresh build roots. This replaces the pacstrap dependency and keeps provisioning inside private namespaces.

Required public source-signing keys can now travel from the invoking user’s keyring into the isolated build. Reviewed-file staging, dependency checks against freshly synchronized private repository databases, and cancellation cleanup across privilege elevation have also been improved.

For automated builders, this release adds:

  • shelly --version --json for version and capability discovery.
  • JSON build review and result output, with review-digest validation.
  • Configurable package output destinations.
  • shelly resolve to map exact repository or AUR package names to package bases.

Using isolated builds? You need unshare from util-linux alongside systemd-nspawn. For unattended builds, import required source-signing keys into the invoking user’s keyring beforehand; --no-confirm does not approve missing-key imports.

✨ A smoother desktop

  • Flathub links open the right app, even if Shelly is already running or still loading its catalog. Flatpak reference files and AppStream links are handled, too.
  • Flatpak details gain uninstall controls, installed and verified indicators, better remote selection, and clearer loading feedback.
  • Conflict prompts name the packages involved, including which installed package will be removed and what replaces it.
  • Tray checks can follow your schedule with a cron mode that waits for the configured weekly time before the first check. Weekly scheduling also no longer depends on the symbolic tray icon setting.
  • Fixed the installed AUR view failing to restore correctly after a reload.
  • Improved dependency download progress, long package-name display, and error messages across the CLI, TUI, and GTK interface.
  • Support setup now skips dependencies you already have installed.

⚡ Parallel means parallel

Repository database and package downloads now respect ParallelDownloadCount. The setting accepts 1–255, with a default of 100. Older configurations with invalid values fall back to the default.

🌍 Translations and thanks

Italian and Simplified Chinese translations have been updated. Thank you to everyone contributing translations, reporting troublesome packages, and helping test the fixes in this release!

Full Changelog: v3.1.2…234f1e0a

Release pull request: #1876

v3.1.4 A slice of builds

Shelly Pi 3.14 gives the native builder another round of fixes for real-world PKGBUILDs, adds a way to reclaim space from the AUR build cache, and makes package reviews easier to navigate.

There is plenty happening on the desktop, too: Flathub links open the app you wanted, package conflicts explain what will be removed, and package details are easier to read and copy. Behind the scenes, isolated builds gain Shelly’s own provisioning helper, stronger PGP support, and more reliable dependency handling.

🧹 Give your AUR cache some breathing room Built AUR packages can add up. You can now preview and remove cached build archives with –aur-cache, making it possible to recover disk space without manually digging through Shelly’s cache.

shelly purify standard –aur-cache

Standard purge behavior has also been corrected.

🏗️ A sturdier native builder The native builder now supports more complex PKGBUILDs and fixes failures involving SOURCE_DATE_EPOCH, install declarations, shell parsing, unsafe source paths, and sources that share the same filename.

Git sources are cloned from their original URLs, required files are detected more reliably, and regression tests cover the corrected behavior. Package-specific failures affecting Anydesk, Mandolin, Remora, and Pi have also been addressed.

🛠️ Shellystrap and isolated builds Isolated environments now use Shellystrap, Shelly’s own provisioning helper. Required PGP keys can be handed off to isolated builds, dependency handling has been improved, and systemd home-directory issues have been corrected.

🔍 Review upgrades your way AUR PKGBUILD reviews now support collapsed diffs, making large changes easier to navigate. Individual upgrades can also be reviewed separately before continuing.

Optional dependencies are handled more clearly, ignored packages remain visible in filtered lists, and conflict prompts identify which installed package will be removed.

✨ A smoother desktop experience Package columns now use ellipses instead of overflowing, while package-detail text can be selected and copied. Installation status updates display more reliably, and PGP key-import confirmations no longer crash the interface.

Flathub links open directly to the requested application, Flatpak pages show the correct installed and update versions, and dependency download progress is represented more accurately.

📦 AppImage, Flatpak, and tray improvements Each installed AppImage can now have its own environment variables, and StaticURL update checks correctly follow redirects.

Flatpak installation and update flows have been refined, including fixes for application selection and version display. The notification tray can now follow a cron schedule, and tray-service updates initiated from the CLI work correctly.

⚡ Downloads and package operations Parallel package and repository downloads now respect the configured setting. Package installation places –needed correctly, package status is updated more reliably, and command output uses clearer wording.

🌍 Translations This release updates the Simplified Chinese, Italian, Brazilian Portuguese, and Japanese translations. It also introduces Azerbaijani translations for the UI and notification components.

❤️ Thank you, contributors! Thank you to everyone who contributed fixes, translations, testing, and improvements to this release:

@VinnyQF, @caroberrie, @ZoeyErinBauer, @azdanov, @square-235, @Mattyan89, @StKob, @jamalkamaladdin, and @utuhiro78.

A special welcome to first-time contributors @square-235, @StKob, and @jamalkamaladdin!

v3.1.5 - A Better View, a Better Build

Release Notes

Shelly v3.1.5 brings an optional Atoll-powered AUR browser, a build-and-install command, and native tools for maintaining your own package repositories. The builder also gets another round of compatibility fixes, from dependency-only metapackages to packages with unusual permissions and source archives.

Everyday package management gets some attention, too: standard searches return matching packages again, AUR installs gain --needed, AppImages are easier to remove, and errors explain more of what went wrong.

🏝️ Explore the AUR with Atoll

Enable Atoll Powered AUR in Advanced settings to use the new AUR page. Browse a paginated package list, sort by votes or popularity, and choose Best Match, Name, Provides, or Words from the Search By dropdown. Package details include dependency information, with installed and out-of-date indicators in the list.

The option is off by default. Switching it on also points Shelly’s CLI AUR service at Atoll; switching it off restores the Arch AUR service.

Terminal AUR search results now include clickable package links when using the Arch AUR or Atoll. Other configured services keep plain-text package names, and failed AUR requests provide more useful diagnostics.

🏗️ Build it, then install it

shelly build now supports --install (-l). Combine it with --sync-deps to install missing build dependencies, build the package, and install the resulting archives:

Terminal window
shelly build --sync-deps --install
# Short form:
shelly build -s -l

Administrator credentials are requested up front, while the build runs as your regular user. Installation also works with isolated builds after the completed archives are exported.

The install shortcut is -l; -i remains the shortcut for --isolated.

🛠️ More PKGBUILDs, fewer build failures

This release improves several parts of the native builder:

  • Dependency-only metapackages, including recipes without a package() function, can now produce valid packages.
  • Empty or zero epochs no longer introduce a leading colon into package versions. AUR update comparisons also handle affected installed versions correctly, fixing repeated update offers.
  • Packages with restrictive directory permissions, such as snapd, can be assembled and cleaned up without leaving failed builds that block retries.
  • Global build dependencies are kept separate from split-package runtime dependencies, allowing conflicting outputs to be built together.
  • Source extraction handles hard links, forward hard-link chains, and literal backslashes in filenames more accurately. Array expansion and here-string parsing have also been improved.
  • Isolated builds run guest package hooks during provisioning, improve compatibility with restrictive umasks, and preserve virtual ownership for external packaging helpers.

These changes address build failures involving packages such as Heroic, GStreamer, libblockdev, CUPS, and FUSE, alongside improvements for automated builds.

⚙️ Take control of your build environment

Native builds now use a predictable system PATH, fixing failures caused by inheriting an unsuitable path from privilege elevation. Add custom toolchain directories through build.extra_path in shellybuild.conf.

The new build.env setting supplies literal environment variables to the unprivileged builder:

[build]
extra_path = ["/home/your-user/.cargo/bin"]
env = { JAVA_HOME = "/usr/lib/jvm/default" }

Elevated native builds also preserve the caller’s locale settings, with C.UTF-8 as the fallback for a missing or empty LANG.

Upgrade note: tools previously found only through your terminal’s PATH must now be listed in build.extra_path. Use absolute paths; shell variables and ~ are not expanded. For isolated builds, configured paths must exist inside the guest.

📦 Repository tools built into Shelly

The new shelly repo-db commands maintain pacman-compatible repository databases directly:

Terminal window
shelly repo-db add ./myrepo.db.tar.zst ./example-1.0-1-x86_64.pkg.tar.zst
shelly repo-db list ./myrepo.db.tar.zst
shelly repo-db remove ./myrepo.db.tar.zst example
shelly repo-db verify ./myrepo.db.tar.zst

Database updates maintain both package and file indexes. Options cover signing, downgrade prevention, waiting for database locks, and removing replaced package archives after publication.

🔍 Search and install improvements

  • shelly search standard and shelly -Ss search available repository packages by default again, including compound names such as phonon-qt6. Use --detail for one exact package’s metadata or --installed to search installed packages.
  • AUR installs now accept --needed to skip building and reinstalling matching installed versions, including individual split-package members. Dynamic versions and VCS packages may still require a build.
  • AUR installs verify that requested packages and AUR build dependencies are still listed by the configured service. Removed packages cannot be installed from a leftover checkout; when an exact repository match exists, Shelly suggests a standard install. Explicit local builds remain available.
  • Fixed repository Include parsing so server URLs and policies stay associated with the correct repository.
  • Expanded TLS support fixes secure-connection failures with repositories such as BlackArch.
  • Added Nerd Font progress-bar rendering for compatible terminal fonts. For this release, enable it by setting "ProgressBarStyle": "Nerdfont" directly in the CLI’s config.json; shelly config set does not yet accept the new value.

✨ Desktop and AppImage improvements

  • Install optional dependencies directly from package details, with clearer selection controls and installed-state indicators.
  • Package details load more smoothly, reducing content flicker while navigating.
  • Open local .flatpakref and .flatpak files with Shelly to start installation. Shelly now appears in the file manager’s Open With choices for these files.
  • Remove stale AppImage entries even when their files are missing, and correctly handle installations whose recorded name differs from the filename.
  • Improved AppImage desktop-entry detection and icon selection, including choosing higher-resolution icons.
  • Malformed JSON settings recover to defaults across the CLI, desktop, and tray, keeping a .corrupt copy when possible. Settings writes also better withstand interruption.
  • Clearer errors across package operations explain the failure and retain technical details for troubleshooting.

🌍 Translations and thanks

This release completes the European Portuguese translation and updates German, Italian, Polish, Russian, and Turkish translations.

Thank you to everyone who contributed code, translations, testing, and reports: @ZoeyErinBauer, @caroberrie, @azdanov, @VinnyQF, @NateKing204, @Henry2o1o, @Mattyan89, @adem4ik, @juliazero, @pdf, @Ricardo-Simoes, and @mehmetakifongun.

Full Changelog: v3.1.4…4a0d0348

Release pull request: #1972

3.1.6 Bug Fix

Fixes Bug in UI using wrong CLI command to fetch information.

v3.1.7

Shelly 3.1.7 patch notes

Shelly 3.1.7 introduces RLPM, Shelly’s native Zig package-management engine, alongside the existing libalpm backend. RLPM now covers the complete native package workflow: reading repositories, resolving dependencies, verifying and downloading archives, checking filesystem changes, running hooks and scriptlets, installing payloads, and updating the installed-package database.

This release also expands isolated builds, adds pinned build-environment plans, introduces split packaging, improves PKGBUILD previews and Flatpak permission displays, and fixes AppImage installation and native builder issues.

Comparison scope: changes since v3.1.6 through 833e1964, plus the prepared 3.1.7 version and packaging updates. The 3.1.7 release tag has not yet been created in this checkout.

Changes at a glance

Area Change from 3.1.6
Native package engine Adds an independent RLPM implementation and a shared interface for selecting RLPM or libalpm.
Build variants Adds binaries that omit libalpm entirely, with RLPM as their default engine.
Distribution integration Adds configurable Arch and Devario path profiles, explicit native configuration selection, and hook-directory policy.
Isolated builds Adds AUR installation through fresh build roots, complete dependency plans, and RLPM provisioning.
Package output Adds compression presets and a separate output architecture setting.
Packaging Adds CLI, Flatpak backend, notification tray, and no-tray split packages.
User interface Improves accessibility, Atoll PKGBUILD previews, permission explanations, and AppImage integration.
Cache cleanup Expands --aur-cache to clear the contents of Shelly’s entire AUR cache.

RLPM in detail

An independent engine for native packages

In 3.1.6, Shelly’s native package operations used libalpm. In 3.1.7, the package-manager interface can dispatch those operations to either libalpm or Shelly.Rlpm. RLPM implements its own database handling, resolver, transaction lifecycle, and executor; selecting it does not delegate the transaction back to libalpm.

The engine follows an owning Owner → Database → Package → Transaction model. The owner holds configuration, repository registrations, caches, callbacks, and the active transaction. Package references carry generation information so a reference from an invalidated database can be rejected. Prepared plans own their review data, allowing the selected package set, dependency relationships, answers, and warnings to remain stable while the operation proceeds.

The shared PackageManager layer gives the CLI and GTK application a common view of package records, progress, questions, errors, and cancellation. GTK continues to perform native operations through the CLI, so the selected backend also applies to those operations.

RLPM’s core is written in Zig. It still uses libraries and tools for specific jobs, including libarchive, SQLite, the shared HTTP/download stack, libcurl where needed, and GPG for signature verification. An RLPM-only build removes the libalpm dependency; it does not make every dependency disappear.

Backend selection and defaults

Default upstream builds include both engines and initially select libalpm. The selection is persistent and takes effect on the next CLI invocation:

Terminal window
shelly config get NativePackageBackend
shelly config set NativePackageBackend rlpm

On a build that includes libalpm, select it again with:

Terminal window
shelly config set NativePackageBackend libalpm

The setting lives in Shelly’s user configuration, separately from the native repository configuration. An explicit saved selection survives changing build variants. An omitted setting uses the binary’s compiled default.

Build the CLI without libalpm with:

Terminal window
cd Shelly.Cli.Zig
zig build -Dlibalpm=false

This variant defaults to RLPM and omits libalpm imports, header translation, discovery, and linkage. Selecting libalpm in it produces BackendUnavailable. Invalid backend settings fail explicitly, and transaction failures do not trigger an automatic switch to another engine. Configuration commands remain available to correct the setting.

The dedicated packaging/arch/shelly-git and Devario recipes build RLPM-only variants. Their behavior therefore differs from the default dual-backend upstream build.

Existing package databases and repository formats

RLPM reads and writes the native version 9 local database format, including package descriptions, file inventories, backup hashes, installation reasons, validation history, and install/changelog/mtree members. It preserves CachyOS installed-repository provenance through the INSTALLED_DB field.

Repository support includes traditional tar databases and CachyOS repositories containing an embedded SQLite pacman.db. Both formats become the same internal package model. Tar ingestion uses libarchive’s supported compression filters; SQLite metadata is read in memory without extracting the database member into the installation root.

Database queries include exact lookup, groups, searches, file ownership data, reverse dependencies, and optional-dependency relationships. Repository usage settings distinguish synchronization, search, installation, and upgrade eligibility. Local descriptions and file lists load lazily rather than all being required for the initial identity scan.

Reloads build a replacement cache before publishing it. A malformed or rejected replacement retains the previous usable generation. Successful reloads invalidate old package references. This lets callers distinguish a failed refresh from an empty repository and prevents partially loaded indexes from becoming visible.

RLPM targets native database interoperability. Dedicated tests alternate RLPM and a pinned libalpm implementation against disposable roots, checking records, upgrades, downgrades, removals, and backup outcomes. That coverage is narrower than a claim of complete libalpm equivalence.

Version ordering and dependency resolution

RLPM adds native comparison of epochs, package versions, and releases, including permissive version strings found in package metadata. Numeric runs are compared without converting them to bounded integers. Package release is compared when both values contain it, following the reference behavior. Strict metadata construction remains separate from permissive comparison.

The resolver prepares installation, removal, and system-upgrade plans. It handles named and repository-qualified targets, package archives, versioned dependencies, virtual providers, conflicts, replacements, ignored packages, and assumed installed provisions.

Selection respects repository priority. A newer version in a lower-priority repository does not automatically override the preferred repository. Literal package candidates take precedence over provider selection, and multiple providers can be presented as a frontend question. Plans retain the selected providers and dependency edges so the result can be inspected.

Before accepting a plan, RLPM checks the proposed final state: surviving installed packages, scheduled removals, replacements, and incoming versions. That catches dependencies broken by the operation while avoiding rejection solely because an unrelated installed package already has a broken dependency.

Removal planning supports cascading removals, recursive dependency cleanup, inclusion of explicitly installed dependencies when requested, and unneeded filtering. Optional dependencies generate warnings rather than becoming mandatory removal blockers. Upgrade planning honors ignore rules, considers replacements, preserves packages absent from the repositories, and carries forward installation reasons.

Plans include ordered additions and removals, download and installed-size information, questions, warnings, and structured failures such as missing requirements or conflicting packages. A read-only resolution plan is review data; an executable transaction additionally requires a live lock and validation of the database state.

Transaction lifecycle and shared locking

A normal RLPM transaction follows this sequence:

  1. Acquire the configured database’s db.lck and load current state.
  2. Resolve targets and prepare a stable plan.
  3. Acquire and verify the required archives.
  4. Check the proposed filesystem and database changes.
  5. Run applicable pre-transaction hooks.
  6. Process removals and additions, including package scriptlets and local-record publication.
  7. Perform linker-cache maintenance and applicable post-transaction hooks.
  8. Release transaction resources and the owned lock.

RLPM and libalpm use the same database lock, allowing cooperating writers to exclude each other. RLPM retains the lock descriptor, checks its identity before removal, and refuses to delete a replacement lock belonging to another operation. Ordinary initialization does not silently remove a stale or foreign lock. Commit is rejected when the transaction lacks its required lock, including under NOLOCK.

The engine fingerprints local and sync state around preparation and before commit. Out-of-band database changes produce StaleDatabaseState instead of silently executing a different package set. Configuration and repository mutations are frozen while the transaction is active.

Typed states distinguish preparation, execution, completion, failure, and interruption. Callback reentry is rejected. Cancellation is checked during resolution, transfers, preflight, actions, and payload work, and deferred frontend questions are connected to the same cancellation path.

Lock errors now report the actual configured database path before the operation completes, including custom paths containing spaces or quotes.

Integrity checks and signing policy

RLPM applies effective package and database signature policy, including inherited repository policy and the distinction between local and remote archive sources. Required signatures must be present. Optional policy permits an absent signature but still requires a present signature to satisfy validity and trust requirements.

Signature handling uses the configured package keyring and its trust database. Unknown-key import requires a frontend decision. A successful import triggers verification again and does not grant trust by itself. Structured results retain signing fingerprints, trust and validity information, and GPG diagnostics.

Repository digest checks prefer SHA-256 and can fall back to MD5. Embedded and detached signatures follow their respective reference policy rules. Disabling signature verification does not disable supplied digest checks.

Verified input is copied into a sealed Linux memory-backed file. Verification, archive parsing, and subsequent extraction read the retained bytes, so replacing the original pathname after verification cannot substitute another archive. This requires memfd sealing and /proc, and consumes RAM or swap proportional to the retained archives.

The API distinguishes metadata inspection from authenticated loading: Package.loadArchive parses metadata without claiming verification, while Owner.loadPackage applies policy and retains verified bytes. Seeing a checksum or signature advertised in repository metadata is not represented as having already checked the package archive.

Downloads and repository refresh

RLPM uses the shared Shelly.Download transport for package acquisition and database refresh. It searches configured caches, verifies cache hits under current policy, supports resumable transfers, handles mirror retries, and keeps payload/signature acquisition within the bounded download queue.

ParallelDownloads governs package and repository transfers, with a maximum worker count of 255. Independent repository payload/signature pairs can download concurrently. Verification, key questions, parsing, and publication remain on the owning thread.

Download progress now distinguishes bytes transferred from final acceptance. A completed transfer can still be undergoing integrity checks or publication, and a failed candidate can move to another mirror. CLI and isolated-build progress show these stages without treating a finished transfer bar as a successful transaction.

Refresh reports updated, unchanged, skipped, and failed outcomes separately for each repository. Candidates are verified and parsed before publication. Invalid downloads retain the previous usable database. Journals and directory locks protect publication of a database and its detached signature for cooperating RLPM readers, with recovery for interrupted publication.

When privileged downloads use a configured sandbox user, worker processes can drop credentials and apply Landlock filesystem restrictions and seccomp syscall restrictions. Setup failure aborts that request. The parent retains its own credentials and verifies worker output before publication. These protections depend on the configured switches and kernel facilities.

Download-only transactions with additions acquire verified archives without installing package payloads or running package actions.

Filesystem preflight and configuration files

Before extraction, RLPM traverses the archives and constructs a manifest of the intended effects. It checks archive identity and dependency metadata against the plan, inventories payload paths, and detects both package-to-package and package-to-filesystem conflicts.

Checks account for existing owners, shared directories, scheduled removals, and ownership transfers during upgrades. A permissive overwrite pattern does not authorize replacing an unowned directory tree. Missing installed file records fail preflight instead of making ownership disappear.

The manifest covers backup handling, NoUpgrade, NoExtract, overwrite rules, .pacnew, and .pacsave. Backup decisions compare the previous package hash, current local content, and incoming content. The executor recomputes relevant decisions after hooks and scriptlets, since those actions may change the files being considered.

Archive paths are confined to the installation root with openat2. Absolute archive entry names, traversal components, invalid hardlinks, duplicate payload paths, and inconsistent inventories are rejected. The implementation does not fall back to unconstrained path resolution when the required kernel support is unavailable.

Preflight also checks mount access and available space. Estimates include temporary extraction, directories, database records, and publication staging. They are deliberately more conservative than a payload-only estimate and can reject work on a nearly full filesystem that the reference implementation would accept.

Hooks and package scriptlets

RLPM discovers and evaluates native package hooks, including package and path triggers, operation matching, dependencies, ordering, NeedsTargets, AbortOnFail, and CachyOS NetworkAccess. Later hook directories can override earlier definitions; empty files and /dev/null masks disable lower-priority hooks of the same name.

Package installation, upgrade, downgrade, reinstall, and removal run the corresponding scriptlet stages. Incoming scripts come from retained archive data, and post-installation stages use the newly installed local record. Version arguments are quoted literally before being passed to shell functions.

Actions run in a fresh worker process rooted in the target filesystem. Parent working directory, credentials, and environment remain separate. Output is streamed back to the operation, and cancellation terminates the action process group.

CachyOS-style network isolation applies to hooks and scriptlets by default, with explicit controls for permitting access. Download filesystem/syscall sandbox controls and action network controls remain distinct.

Fatal pre-hook conditions prevent package mutation. Failures treated as nonfatal by the native behavior, such as ordinary scriptlet or post-hook failures, are retained as warnings and action outcomes. Failed or interrupted payload execution does not run successful-completion post hooks. Isolated provisioning additionally treats package setup failures as a failed provisioning operation.

Payload execution and database recovery

RLPM installs payloads through held directory descriptors and private staging, then publishes entries with descriptor-relative operations. It preserves supported file modes, ownership, timestamps, sparse extents, extended attributes, and file capabilities. Its extraction flags follow the pinned native behavior, which does not enable ACL extraction. Removal preserves nonempty directories rather than recursively deleting their contents.

Payload writeback is batched at package boundaries. Changed filesystems are flushed with syncfs() before a new package record is published. The CLI can report Finishing writes for <package> while that barrier runs. A flush failure stops the operation and prevents publication of the current package’s new record.

Local records are staged, synchronized, and published using a durable journal. Interrupted record publication causes DatabaseRecoveryRequired. The library’s Owner.recoverLocalDatabase API acquires the normal writer lock and restores a coherent record state; it does not remove a foreign or stale writer lock automatically.

Record recovery is not full package rollback. Payload changes, scriptlet effects, and previously completed packages can remain after failure or cancellation. Execution reports retain the current boundary, affected path, completed and remaining packages, publication status, and underlying errors. RLPM stops at a failed mutation instead of continuing to report the package as successfully extracted.

One executable for worker operations

Download and action workers are private modes of the hosting executable. Shelly re-executes /proc/self/exe, including when an upgrade has replaced the installed pathname. Deployments no longer need separate worker executables or paths into a build cache.

Library embedders must dispatch worker modes before normal application initialization or provide an explicit worker executable implementing the dispatcher. A dual-backend host still carries its compiled libalpm dynamic dependency into workers; an RLPM-only host excludes it.

Compatibility status

RLPM is integrated and can execute package transactions, but complete libalpm compatibility remains unfinished. The compatibility ledger continues to track missing, partial, and representation-only coverage. It does not certify full parity across the public API, malformed inputs, all repository configurations, or every production workflow.

The repository adds independent reference fixtures and focused tests for version ordering, database formats, signature policy, dependency resolution, locking, downloads, preflight, hooks, execution, and interoperability. Privileged namespace, GPG, and pinned-binary tests have additional environment requirements. Historical test results in the component documentation are not a fresh validation of every 3.1.7 build.

Intentional differences include stricter archive validation, conservative disk-space estimates, explicit stale-state rejection, safer lock cleanup, sealed archive ownership, and retained partial-failure diagnostics. Large-database fingerprint costs and wider production acceptance remain relevant limitations; this release does not establish a universal performance advantage over libalpm.

See the native backend guide, RLPM overview, and compatibility ledger for the implementation contracts and evidence.

Arch and Devario integration

Backend selection and distribution paths are independent. An RLPM-only build can use Arch’s existing paths, while the Devario profile supplies Shelly-owned locations:

Resource Arch profile Devario profile
Native configuration /etc/pacman.conf /etc/shelly.conf
Package database /var/lib/pacman /var/lib/shelly
Package cache /var/cache/pacman/pkg /var/cache/shelly/pkg
Keyring /etc/pacman.d/gnupg /etc/shelly.d/gnupg
Public key bundles /usr/share/pacman/keyrings /usr/share/shelly/keyrings
System hooks /usr/share/libalpm/hooks /usr/share/rlpm/hooks
Administrator hooks /etc/pacman.d/hooks /etc/shelly.d/hooks

Changing profiles supplies different defaults; it does not move or convert an existing database, cache, or keyring. Runtime selection of RLPM alone does not change the profile.

The global --config option selects a native configuration file for one invocation. The selection is preserved through elevation, AUR coordinators, and bootstrap operations. Explicitly unreadable configuration files or includes fail rather than silently using defaults.

Hook configuration adds HookDirMode = Append|Replace. Append remains the default. Replace uses only the listed directories, and an empty replacement list disables discovery. Both backends receive the resolved ordered list.

Devario keyring population uses the profile’s public bundle directory, with shelly-key --populate-from available to select another source. The new devario-devel metapackage supplies native and isolated build tools without making pacman or archlinux-keyring part of that metapackage.

Isolated builds and pinned dependencies

AUR packages can now be built in a fresh root before installation:

Terminal window
shelly -Ia --isolated <package>

Each package base gets its own root. Repository build dependencies stay in the guest; exported archives and their runtime dependencies are installed through the normal host transaction. The workflow supports --needed, split-package selection, and exact-commit --version installation.

Isolated provisioning uses the selected native backend. RLPM-only binaries provision an explicit userspace and build-tool set instead of requiring the usual base and base-devel baseline. A recipe can still declare pacman or libalpm as build dependencies when it needs them; an RLPM-only coordinator does not prohibit building software that uses libalpm.

The builder adds --resolve-dependencies and --dependency-plan for isolated environments. Resolution produces a versioned JSON plan containing the complete bootstrap and recipe package set, versions, repository locations, SHA-256 metadata, dependency relationships, and digests tying the plan to the reviewed inputs and configuration. Provisioning checks the selected versions and hashes against the plan before installation.

Missing repository dependencies and missing archive SHA-256 metadata produce distinct diagnostics. Incomplete plans stop provisioning, with unresolved requirements reported in stderr, logs, and JSON errors. Repository resolution does not assume a missing package can be obtained from the AUR.

Host configuration forwarding is corrected: review and provisioning use the selected host configuration, while the guest receives its generated local configuration instead of a host-only pathname.

Isolation still requires the relevant namespace and systemd-nspawn facilities. AUR-only build dependencies and signing with private keys inside the guest remain unsupported. --isolated cannot be combined with --chroot or dependency-only installation modes. See isolated builds.

Native builder improvements

  • Dynamic versions: valid changes from pkgver() update the PKGBUILD, reset pkgrel to 1, and refresh version-dependent metadata before building. Isolated builds validate the guest’s version/release edit before applying it to the original host file as the invoking user; concurrent changes prevent writeback.
  • SRCINFO generation: --makesrcinfo prepares sources and evaluates pkgver() when present, rather than retaining stale VCS metadata.
  • Large split packages: evaluated function definitions are carried into lifecycle execution through a private script, avoiding Linux’s per-argument size limit. Dynamically generated split-package functions remain available to the builder.
  • Source extraction: ordered archive overlays support replacing earlier regular entries while preserving source aliases, Git checkout trees, hardlink rules, and conflicting-type checks. This addresses source layouts used by packages such as VMware and Rust-related builds.
  • Source cache: destinations.sources is consistently exported as SRCDEST during metadata evaluation and lifecycle steps, including sandboxed builds.
  • Compression: --compression-level 1..5 and package.compression_level provide conservative through maximum-effort presets for Zstandard, gzip, xz, and bzip2. Omission retains library defaults; preset 3 is not a forced new default.
  • Output architecture: package.carch changes the architecture written into package metadata and filenames while preserving build.carch for PKGBUILD evaluation. Packages declaring any remain any. The setting also reaches isolated builds.
  • Source verification and parsing: fixes improve source-key handling, GPG forwarding, URL escaping, shell array expansion, and recognition of braces in shell command position.

See build configuration for compression mappings and output architecture settings.

Split packaging

New split recipes separate the application into shelly, shelly-cli, shelly-flatpak-backend, and shelly-notify, with matching -git variants where applicable. shelly-notify-none and its Git variant satisfy the tray dependency for users who want to omit the notification service.

The CLI package owns the command-line executables, completions, manual, and privileged-operation policy. The Flatpak implementation is packaged separately. The existing optional Flatpak backend architecture predates this release; 3.1.7 expands its packaging rather than introducing Flatpak support for the first time.

Arch and Devario recipes supply their respective path profiles, and their versioned dependency/provision metadata is updated for 3.1.7. Git recipes continue to follow the development branch and calculate their build version from Git history.

Interface and desktop changes

PKGBUILD review

The GTK PKGBUILD preview integrates Atoll-backed preview data, scan findings, and source-file information, including a retry path for scans. The CLI exposes the same scan flow through search aur --pkgbuild --scan-pkgbuild when the Atoll mirror is enabled, with text and JSON output. Scan findings supplement review; they are not a guarantee that a build is safe.

Standard search results gain links for AUR packages, and multi-selection gains additional context.

Flatpak permission explanations

CLI and GTK permission views group raw tokens into readable concerns such as network access, devices, files, and session services. Related entries are deduplicated and ordered by concern level. Filesystem access modes, denied permissions, and conditional tokens retain their meaning.

The backend reads the relevant metadata sections correctly. Unreadable or malformed permission data is no longer presented as if the application requested no permissions. Permission-dialog cleanup also releases copied rows correctly.

Accessibility and appearance

GTK controls gain accessible names and roles. Keyboard focus is restored after lockouts, navigation targets remain visible, first-run page changes are announced, and transaction progress and empty search results receive screen-reader feedback. New accessibility checks inspect populated UI structure and Orca announcements.

The Shelly icon setting now affects icon fetching and package views when changed. Translation work includes Polish, German, Italian, Brazilian Portuguese, and European Portuguese, alongside refreshed translation catalogs.

AppImage fixes

AppImages gain GTK installation and deep-link/file-association integration. Metadata synchronization handles relocation more carefully, updates desktop launch paths, preserves custom arguments and environment settings, and retains the prior integration when relocation fails.

Copying and rollback preserve executable permissions. This fixes cases where an installed or restored AppImage became non-executable and desktop menus hid its launcher because TryExec no longer pointed to an executable file.

Automatic file-size units

Enable automatic units in human-readable CLI output with:

Terminal window
shelly config set FileSizeDisplay Auto

Auto chooses B, KiB, MiB, GiB, or TiB and preserves negative size changes. Existing fixed-unit modes remain available, Megabytes remains the default, and structured output continues to use numeric byte counts.

Cleanup and other fixes

--aur-cache now deletes all contents of the invoking user’s Shelly cache, including checkouts, sources, build trees, archives, and metadata, including caches for packages no longer installed. Previously it targeted built archives and their signatures.

The command previews entries and asks for confirmation. It retains the cache root, removes symlinks without following their targets, and excludes output destinations outside Shelly’s cache. The GTK Clean Package Cache action also clears this entire cache; the repository retention count does not limit AUR cache cleanup.

Terminal window
shelly purify standard --cache --aur-cache --dry-run

Additional fixes make libalpm database/signature downloads advance together to the next mirror after a signature download failure, improve isolated dependency-error reporting, and make RLPM bootstrap stages and download processing more visible during long operations.

Upgrade considerations

  • Check the installed variant before choosing a backend: upstream dual-backend builds retain libalpm as the initial default, while the dedicated RLPM-only recipes cannot select libalpm.
  • Keep backend choice separate from path configuration. Selecting RLPM with the Arch profile continues to use the configured Arch database; selecting a Devario build does not migrate that database automatically.
  • Preserve the intended signature policy and populate the keyring selected by the profile or configuration. Removing libalpm does not remove the need for package trust configuration.
  • Treat interrupted native transactions as potentially partial. RLPM’s record journal helps recover database consistency, but it does not reverse every payload or scriptlet effect.
  • Review the expanded --aur-cache scope before using it when cached source trees or build results matter.
  • Ensure consumers accept any architecture chosen through package.carch; it changes package labeling, not the compiler target or the PKGBUILD’s build architecture.

Further RLPM details

v3.1.8 Latest

What’s Changed

Full Changelog: https://github.com/Seafoam-Labs/Shelly-ALPM/compare/v3.1.7...v3.1.8

© 2026 Seafoam LabsShelly Chel