Skip to content
Seafoam Labs

All versions since v3.1.4 A slice of builds

All versions

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

What’s Changed

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

v3.1.9

Shelly-ALPM v3.1.9 Release Notes

Shelly v3.1.9 adds file migration support to RLPM, allowing packages to take ownership of eligible existing files while preserving their contents. Devario gains automatic adoption of unowned files, and package authors can declare specific migrations for replacements and upgrades.

This release also fixes first-upgrade failures for AUR -git packages, preserves proxy settings during native builds, and improves repository refreshes and update previews.

📦 File migration with RLPM

Files installed by an installer or an earlier system setup can now become package-managed without being overwritten. RLPM can adopt existing regular files and symlinks, keeping their contents and attributes while recording the destination package as their owner.

Package authors can declare exact paths through the new shelly_migrate PKGBUILD array. Declarations support unowned files and files belonging to an accepted replacement or the previous version of the same package. They can also mark missing paths as optional and establish backup tracking for eligible files.

Shelly carries these declarations through generated .SRCINFO and package archives, including overrides for individual split packages. Explicit migrations can adopt files absent from the incoming archive; RLPM retains those ownership records across later upgrades until normal package payload handling takes over.

CLI and GTK transaction previews show which paths will be preserved, their source and destination, and whether the migration was declared or discovered automatically. Ownership and file-type checks still apply. See the migration guide for declaration syntax and lifecycle details.

⚙️ Automatic adoption on Devario

Devario builds enable automatic adoption of eligible unowned files that are also supplied by an incoming package. Once the package owns a file, later upgrades use normal extraction and backup rules. Files already owned by another package are not automatically adopted.

The setting lives under [options] in the native configuration file, /etc/shelly.conf on Devario:

[options]
AutoMigrateUnowned = true

Set it to false to disable automatic discovery. Explicit migration declarations remain available. The pacman path profile defaults to false; this feature requires the RLPM backend.

🏗️ More reliable AUR builds

  • Fixed -git packages failing their first upgrade after upstream changes with ReviewedCheckoutChanged. Shelly now recognizes controlled pkgver and pkgrel updates made during metadata generation while continuing to reject unrelated changes to reviewed inputs. (#2081)
  • Fixed PKGBUILD parsing for negated and conditional brace groups, including constructs such as if ! { ...; }; then. (#2076)
  • Preserved standard HTTP, HTTPS, all-proxy, and no-proxy environment variables when elevated native builds return to the invoking user.
  • Improved AUR failure reporting so errors identify the affected package and retain the underlying cause.

🔄 Smoother updates and previews

  • Reuse repository databases already synchronized by the libalpm manager, avoiding a duplicate refresh during the same update flow. (#2066)
  • Keep root-run update previews in root’s own cache, preventing them from leaving root-owned database files in the regular user’s preview cache. (#2072)

🔧 Packaging and maintenance

  • Pin the affected source PKGBUILDs to Zig 0.16.0 and use the patched compiler package consistently in CI and release builds.
  • Build the stable Devario packages from the matching release tag; the separate shelly-git recipe continues to track development.
  • Update the AUR release helper to refresh checksums and .SRCINFO through Shelly, with package builds optional during release preparation.

🔄 Upgrade notes

File migration requires Shelly 3.1.9 with RLPM. Upgrade Shelly before deploying packages that depend on shelly_migrate. Shelly’s libalpm backend rejects installation of archives declaring these migration semantics; older Shelly releases and other package managers may ignore them.

RLPM may download package archives before final installation confirmation to prepare the migration preview. Cancelling at that confirmation leaves installed files and ownership unchanged.

🌍 Translations and thanks

This release updates German and Russian UI translations and Polish notification translations.

Thank you to Zoey Bauer (@ZoeyErinBauer), Rani Charradi (@treshaun), Hen_Ry (@Henry2o1o), Andrei Stepanov (@adem4ik), Julia (@juliazero), and Piotr Górski for their contributions.

Full Changelog: v3.1.8…d89a8338

v3.1.10

🐚 Shelly-ALPM v3.1.10 Release Notes

Shelly v3.1.10 improves AUR build reliability, resolves system upgrades and explicitly requested repository packages together, and makes RLPM failures easier to understand. The CLI gains a shell progress animation and package-name output for scripts and completions, while the desktop app gets better keyboard navigation and more accurate package lists.

Behind the scenes, Shelly moves to Zig 0.17.0, updates its build and packaging workflows, and removes Arch Linux news from Devario builds.

🧱 More reliable AUR builds

Build dependencies are now discovered and installed before prepare() runs, including when an AUR package needs other AUR packages to build. Dependency planning reads metadata without downloading sources, running lifecycle functions, or changing the reviewed PKGBUILD. Normal source preparation and version updates happen after dependencies are available. (#2110)

This release also improves compatibility with package recipes:

  • 🧩 Support prefix and suffix trimming on quoted indexed array elements, including expressions such as ${source[0]%%::*}, fixing UnsupportedArrayExpansion failures for these constructs.
  • 📝 Collapse whitespace in multiline pkgdesc values when writing .PKGINFO, keeping descriptions on one valid metadata line. (#2100)
  • 📥 Accept larger HTTP response headers during downloads, fixing failures involving GitHub security headers and redirects. (#2096)

🔄 Upgrades and package configuration

shelly install standard --upgrade now resolves the system upgrade and explicitly requested repository packages in one transaction. This fixes dependency failures when a requested package and its updated libraries need to move together, including explicit targets from another repository. The confirmation preview explains the combined operation. (#2105)

Changes to IgnorePkg now preserve the separation between the main configuration and included files. Adding or removing an entry no longer copies inherited entries into pacman.conf. (#2101)

🐛 Clearer RLPM errors and progress

RLPM reports more useful explanations for failures involving configuration, database locks, downloads, filesystem operations, hooks, and scriptlets. Diagnostics retain the underlying technical error and add relevant context, including action names and exit status when available.

File-conflict reporting carries the conflicting paths and package identities into the transaction diagnostics. Download verification and publication progress bars also clear when their work finishes, keeping subsequent hook output readable while other downloads continue.

🐚 A little more shell in your terminal

The new Shell progress style opens and closes a small ASCII shell as it advances along the bar. It becomes the default when no style is saved; existing style choices are preserved. To select it:

Terminal window
shelly config set ProgressBarStyle Shell

Blocks and Pacman remain available. Redirected output prints completed progress lines without animation.

The CLI also adds --names-only to standard and AUR package lists and standard searches. Each matching package name appears on its own line, and standard searches bypass pagination:

Terminal window
shelly list standard --names-only
shelly list aur --names-only
shelly search standard --names-only --show-hidden

Bash, Fish, and Zsh package completions now query Shelly directly, removing their dependency on pacman for those package lists.

🧭 Desktop navigation and package lists

  • ♿ Give pages an accessible focus stop so keyboard traversal reaches their content. The first-run wizard also moves focus into each new page, helping keyboard and screen-reader users follow the setup flow. (#2107)
  • 📦 Keep the Packages tab based on repository results, using installed-package data to annotate installation status. Foreign and local-only packages no longer appear there as repository packages with unsuitable actions. (#2108)

🌊 Devario defaults

Builds using the Devario path profile no longer fetch or display Arch Linux news during upgrades. News commands are omitted from help, generated manuals, and shell completions; explicitly invoking them reports that news is unavailable. This follows the build’s distribution profile, so selecting another runtime backend does not change it. Builds using the pacman path profile retain Arch news. (#2109)

📦 Build and packaging updates

  • ⚡ Move the native components and build recipes to Zig 0.17.0, with matching API and build-option updates. (#2117)
  • ✅ Install checksum-verified official Zig archives in CI for the runner’s architecture.
  • 🧩 Replace vendored dependency copies with upstream dependencies pinned by URL and content hash.
  • 📦 Add a dedicated CachyOS packaging directory and update Arch and Devario build workflows.

🚀 Upgrade notes

Source builds now require Zig 0.17.0. Populate the dependency cache before building offline with zig build --fetch=all in each component you intend to build.

install standard --upgrade cannot be combined with --build-deps; upgrade the system separately before installing build dependencies.

🌍 Translations and thanks

🇫🇷 This release updates the French UI translation.

❤️ Thank you to Zoey Bauer, VinnyQF, Anton Ždanov, Mohit Mishra, Tomás Arribas, and Thierry M for their contributions, and to everyone reporting issues and testing fixes.

📋 Full Changelog: v3.1.9…55a23eb0

🔀 Release pull request: #2120

🐚 Shelly-ALPM v3.2.0 — The Bug Bash Latest

🐚 Shelly-ALPM v3.2.0 — The Bug Bash

Shelly v3.2.0 is a bug bash: a round of fixes for the things that get between you and your packages. Since v3.1.10, we’ve tackled Flatpak failures, stubborn tray icons, missed restart detection, AUR build errors, and package information that wasn’t telling the whole story.

A few quality-of-life improvements came along too, including multi-package downgrades, AppImage update discovery, and a choice of terminal for updates.

🐛 Flatpak and permissions, untangled

Fixed the Flatpak regression affecting Arch Linux after v3.1.10. Elevated operations now hand work back to the invoking user with setpriv, preserving the login session context needed for Flatpak’s system-helper authentication.

User-cache handling also gets a cleanup. Shelly writes the invoking user’s cache using that user’s credentials, including when launched through supported privilege-elevation tools, and preserves absolute XDG_CACHE_HOME overrides.

Existing ownership problems can be repaired from your regular user session with:

Terminal window
shelly utility --fix-permissions

This repairs Shelly’s directories; it does not change ownership of the parent ~/.cache directory.

🔔 A tray icon that keeps up

  • 🔄 Stale update status: The notification service now watches package database changes and refreshes its status after package operations. (#2151)
  • 🔌 Endless reconnect loops: When DBUS_SESSION_BUS_ADDRESS is missing, Shelly falls back to $XDG_RUNTIME_DIR/bus. If neither provides a usable address, it reports the problem instead of retrying forever. (#2137)
  • 🖥️ Your terminal, your updates: Choose the terminal used to launch updates from the notification service. (#2148)

🔄 Restart detection, actually detecting

Post-upgrade restart and reboot checks were reading some /proc files as empty because those files report a size of zero. Shelly now reads their contents correctly, restoring the information those checks depend on.

The scan also stops treating a deleted /etc/ld.so.cache mapping as a stale shared library, avoiding misleading restart recommendations after ldconfig runs. (#2149)

🧱 AUR builds with fewer surprises

  • 🧩 Computed architecture lists: Fix InvalidArchitectureDirective failures when a PKGBUILD derives arch from an associative array. Unresolved values are validated after evaluation. (#2144)
  • 🌿 Git source races: Finish cached Git mirror maintenance before cloning build sources, preventing the two operations from racing. (#2123)
  • 📝 Useful metadata errors: Package-assembly failures now name the rejected metadata field, making broken recipes easier to diagnose. (#2113)
  • ⚙️ Clearer build configuration: Expanded shellybuild.conf documentation explains configuration precedence, compiler flags, and portable versus host-specific settings.

📦 Package information you can trust

Installed package versions now take priority in the UI and CLI search results, rather than being replaced by the repository version. RLPM also correctly reports installation status and dates. (#2044, #2143)

Upgrade previews now include repository package replacements, making it clearer what will change before you confirm. (#2119)

Behind the scenes, unnecessary RLPM database snapshot hashing has been removed, reducing repeated database work.

🧹 Cleaning up the cleanup

purify now recognises leftover pacman download-XXXXXX directories, including those containing partial downloads, and includes them in its cleanup plan. (#2150)

Removing a stale database lock from the desktop app also runs asynchronously, keeping the interface responsive while authentication completes. (#2142)

🖼️ AppImages, better connected

AppImage desktop integration now uses the application’s shipped desktop-file identity and removes superseded launcher entries during updates, addressing naming mismatches and duplicate menu entries. (#2134)

Update support gains embedded update-information discovery and .zsync control-file support. GitHub asset matching honours embedded filename patterns, and release selection receives additional fixes. (#2146, #2147)

✨ A few extras between the fixes

  • ⏪ Downgrade packages together: Select older versions of multiple installed packages and install them in one transaction. --target remains a single-package option. (#2132)
  • 🎨 Readable console output: The desktop transaction view gains ANSI colour and formatting support. (#2138)
  • 📥 Download speeds: CLI progress lines now show transfer speed. (#2139)
  • ✅ Recommended apps in batches: Select multiple applications from the Recommended page for installation.

🌍 Translations and thanks

🇻🇳 Added Vietnamese translations for the desktop UI and notifications.
🇦🇩 Updated the Catalan translation.

❤️ Thank you to everyone who reported a bug, supplied a reproduction, tested a fix, or contributed a patch. This bash was built around those reports.

© 2026 Seafoam LabsShelly Chel