Shelly¶

ID: shelly
Links: Documentation · Repository
Upstream stars: ⭐ 1,171
Last commit: 2026-10-06
Version requirement: >= 3
Platforms: 🐧 Linux (Arch Linux, CachyOS, EndeavourOS, Manjaro Linux only)
Operations: installed · outdated · search · install · upgrade · upgrade_all · remove · sync · cleanup
purl types: pkg:alpm/ · pkg:shelly/
CLI name: shelly
Every call: shelly --no-confirm <command>
Issues and PRs: 📦 manager: pacman-based
Source: shelly.toml

Shelly is a package manager for Arch Linux driving libalpm directly (https://github.com/Seafoam-Labs/Shelly-ALPM).

Note

Only the standard half is wrapped, the ALPM repository packages pacman also reaches, so a host carrying both reports those packages twice under two ids. Shelly drives three more package universes behind their own type selector, aur, flatpak and appimage, and each answers a separate call: one operation is one command, so a definition cannot merge them into a single listing.

Caution

Shelly escalates on its own, calling sudo from inside every mutating operation, so mpm never wraps it: an escalated call would stack sudo on sudo. Off a terminal it answers sudo: a terminal is required to read the password and exits 1, so an unattended run needs a warm credential cache or a NOPASSWD policy. See Privilege escalation and sudo.

Parsing notes, verified by driving 3.1.1 and 3.0.0+9 on Arch Linux:

Every query reads --json and prints a flat top-level array of one object per package. installed and search carry the version under Version; list-updates splits it into CurrentVersion and NewVersion.
search standard <query> returns a bare object describing one exact package when no source modifier is passed, which no array parser can read. --available is what turns it into an array over the synchronization databases, so it is not optional here.
That search already matches descriptions, so --extended is its native behaviour and no flag narrows it back to names: mpm refilters instead.
--no-confirm sits in pre_args because every mutating verb prompts otherwise, and shelly accepts the flag before or after its subcommand.
upgrade standard is the whole-system path and update standard <packages> the per-package one, which is the split mpm needs. Neither reads the other’s arguments.
purify standard always plans corrupted archives, and --cache and --orphans add their own targets to that plan.

What `mpm` adds to `shelly`¶

Through mpm, shelly gains --exact and --extended search, to narrow to exact names or match descriptions.

Bigger still, mpm reaches across every manager at once: mpm installed and mpm outdated cover shelly alongside aura, dkp-pacman, pacaur, pacman, pamac, paru, pikaur, trizen, yay and any other manager you run in one table, mpm upgrade --all updates them together, and mpm sbom exports the whole machine as one bill of materials.

Every mpm command also gains --dry-run and --plan previews, cross-scheme version comparison and purl identifiers. See manager augmentations for how each one is built.

Your `shelly` commands, in `mpm`¶

You already know shelly: each operation maps one-to-one onto mpm, in an interface shared by every manager.

To…	With `shelly`	With `mpm`
List what’s installed	`shelly list standard --json`	`mpm --shelly installed`
List outdated packages	`shelly list-updates standard --json`	`mpm --shelly outdated`
Search for a package	`shelly search standard <query> --available --json`	`mpm --shelly search <query>`
Install a package	`shelly install standard <package_id>`	`mpm install pkg:shelly/<package_id>`
Upgrade one package	`shelly update standard <package_id>`	`mpm --shelly upgrade <package_id>`
Upgrade everything	`shelly upgrade standard`	`mpm --shelly upgrade --all`
Remove a package	`shelly remove standard <package_id>`	`mpm remove pkg:shelly/<package_id>`
Clear caches	`shelly purify standard --cache`	`mpm --shelly cleanup --cache`

Prefix any command above with --dry-run to simulate the underlying manager calls without touching the system: the safe way to watch what mpm would do before trusting it.

Operations¶

Operation	Supported	Notes
`installed`	✅
`outdated`	✅
`orphans`
`search`	✅	Exact and extended search backfilled by `mpm`.
`install`	✅	A package already installed as a dependency is marked explicit by `mpm`.
`upgrade`	✅
`upgrade_all`	✅
`remove`	✅
`sync`	✅
`cleanup`	✅	The `--orphans` flag runs the system-wide orphan sweep.
`doctor`

Configuration¶

Ignore shelly on the mpm CLI by passing the --no-shelly option.
Ignore it for every run in your configuration:
```
[mpm]
shelly = false
```
Raise the timeout of all shelly calls:
```
[mpm.overrides.shelly]
timeout = 900
```

Run mpm config-template shelly to print all overridable settings for your configuration file:

[mpm.overrides.shelly]
cli_names = [
    "shelly",
]
cli_search_path = []
dry_run = false
ignore_auto_updates = true
plan = false
post_args = []
pre_args = [
    "--no-confirm",
]
pre_cmds = []
requirement = ">=3.0.0"
stop_on_error = false
unmaintained = false
version_cli_options = [
    "--version",
]
version_regexes = [
    "(?P<version>\\d+\\.\\d+\\.\\d+\\S*)",
]

The arguments and environment variables listed in the box atop this page are forced on every shelly call, so runs stay quiet, non-interactive and reproducible: the defaults you would set in CI anyway.

Recipes¶

A few jobs you would otherwise script around shelly, one mpm command each:

Snapshot and clone a machine: mpm --shelly dump shelly.toml, then mpm restore shelly.toml on the next one.
Export a compliance SBOM: mpm --shelly sbom (CycloneDX by default, --spdx for SPDX).

Privilege escalation¶

Shelly runs sudo from inside its own commands: mpm never wraps it, keeps an already-warm credential cache alive for those internal escalations, and warns when a mutating call goes silent on a terminal with a cold cache and no prompt on screen, since a password prompt may be hiding in the stream.

See privilege escalation for the full policy.

Cooldown¶

State of Shelly’s release-age gating, from the cooldown support table:

Status: ❌ None (Arch ALPM front-end, like pacman )

A cooldown only pays off where a compromised release can be withdrawn while the clock runs, and can only be emulated where the registry dates its releases. From the retraction table:

Registry: Distro binary archives (pkg:deb, pkg:rpm, pkg:alpm, pkg:apk)
Retraction: Index revert: removal is an archive operation and the mirror is rebuilt without the package. Debian, for one, requires filing an RM: bug against ftp.debian.org (developers-reference)
Publish date: ❌ the version string is the distro maintainer’s build, carrying no upstream publication date

With --cooldown set, mpm skips this manager’s install and upgrade operations rather than run them unguarded (fail-closed); --cooldown best-effort opts back in.

Reference traces¶

A collection of raw native outputs captured from the manager’s own CLI and recorded in the bundled definition. If you know Shelly well and a transcript below looks wrong, or a newer release changed its output format, report it.

$ shelly list standard --json
[{"Name":"acl","Version":"2.4.0-1","Size":0,"Description":"Access control list utilities, libraries and headers","Url":"https://savannah.nongnu.org/projects/acl","Repository":"local","Replaces":[],"Licenses":["LGPL-2.1-or-later AND GPL-2.0-or-later"],"Groups":[],"Provides":["libacl.so=1-64"],"Depends":["glibc"],"OptDepends":[],"Conflicts":[],"PackageFile":null,"InstallReason":"Dependency","InstallDate":"2026-09-03T12:47:41","BuildDate":"2026-06-29T13:16:29","DownloadSize":0,"InstalledSize":353496,"RequiredBy":[],"OptionalFor":[]},{"Name":"zstd","Version":"1.5.7-3","Size":0,"Description":"Zstandard - Fast real-time compression algorithm","Url":"https://facebook.github.io/zstd/","Repository":"local","Replaces":[],"Licenses":["BSD-3-Clause","GPL-2.0-only"],"Groups":[],"Provides":["libzstd.so=1-64"],"Depends":["glibc","libgcc","libstdc++","zlib","xz","lz4"],"OptDepends":[],"Conflicts":[],"PackageFile":null,"InstallReason":"Dependency","InstallDate":"2026-09-03T12:47:49","BuildDate":"2026-02-15T16:43:11","DownloadSize":0,"InstalledSize":1610357,"RequiredBy":[],"OptionalFor":[]}]

$ shelly list-updates standard --json
[{"Name":"nyancat","CurrentVersion":"1.5.2-2","NewVersion":"1.5.2-3","DownloadSize":12111,"SizeDifference":-20240,"Description":"Nyancat rendered in your terminal.","Url":"https://nyancat.dakko.us/","Repository":"extra","InstalledSize":42691,"Depends":["glibc"],"OptDepends":[],"Licenses":["custom:NCSA"],"Provides":[],"Conflicts":[],"Groups":[]}]

$ shelly search standard {query} --available --json
[{"Name":"nyancat","Version":"1.5.2-3","Size":12111,"Description":"Nyancat rendered in your terminal.","Url":"https://nyancat.dakko.us/","Repository":"extra","Replaces":[],"Licenses":["custom:NCSA"],"Groups":[],"Provides":[],"Depends":["glibc"],"OptDepends":[],"OptDependsInstalled":[],"Conflicts":[],"PackageFile":null,"InstallReason":"Not Installed","InstallDate":null,"BuildDate":"2024-07-13T00:38:20","DownloadSize":12111,"InstalledSize":42691,"RequiredBy":[],"OptionalFor":[]}]

Version check¶

The version is probed by running:

$ shelly --version
3.1.1

and extracted with:

r"(?P<version>\d+\.\d+\.\d+\S*)"

Upstream project¶

Metrics	`Seafoam-Labs/Shelly-ALPM`
Activity
Popularity
Metadata

Changelog¶

8.1.2 (2026-10-12)
- Run sync and cleanup last and without a spinner on a cold sudo cache, so the tool’s own password prompt can be answered.
8.1.1 (2026-10-09)
- Run shelly after the concurrent batch and without a spinner when its own sudo may ask for a password, like the other managers that escalate on their own.
8.0.0 (2026-09-20)
- Mark a package already installed as a dependency as explicitly installed when mpm install or mpm restore names it, so mpm cleanup --orphans keeps it.
- Add the Shelly package manager with inventory, outdated, search, install, remove, upgrade, database sync and cache and orphan cleanup.