System Upgrades, Rollbacks & Backups

Arch Linux is a fast-moving, rolling-release operating system. To manage system evolution safely, Shelly provides unified tools for coordinated multi-backend upgrades, interactive version rollbacks, package pinning, and declarative system state backups:

shelly upgrade - Synchronize and update official ALPM packages, AUR recipes, Flatpaks, and AppImages in a single coordinated action.
shelly downgrade - Interactively roll back packages to older versions using local caches or the Arch Linux Archive.
shelly mark - Control upgrade exclusions (IgnorePkg), prevent accidental removals (HoldPkg), and change install reasons.
shelly backup - Export your installed package state to reproducible TOML manifests and restore them on new systems.

Coordinated System Upgrades (`shelly upgrade`)

Instead of juggling separate commands for pacman, AUR helpers, and flatpak, Shelly coordinates updates across all active package managers.

Upgrading All Backends in One Command

Run shelly upgrade all (shortcode shelly -U or shelly -Ux) to build and execute a single coordinated upgrade plan:

shelly upgrade all

Shelly queries each package backend in parallel, presents an aggregated summary of available updates, and coordinates the transactions:

Targeted Upgrades & Filters

Synchronize repository databases and perform a standard ALPM system upgrade:

# Synchronize databases and upgrade official packages
shelly upgrade standard

# Or with shortcode:
shelly -Us

Check for newer AUR releases and rebuild VCS (-git) packages:

# Check AUR and rebuild VCS packages
shelly upgrade aur

# Or with shortcode:
shelly -Ua

Skip specific backends during a full system upgrade:

# Skip Flatpak and AppImage backends
shelly upgrade all --no-flatpak --no-appimage

# Skip checking VCS/development packages (-git):
shelly upgrade all --no-devel

Package Rollbacks (`shelly downgrade`)

If an upstream update introduces a bug or regression, shelly downgrade allows you to immediately roll back to a previous working version.

Shelly searches both your local package cache (/var/cache/pacman/pkg/) and the official Arch Linux Archive (ALA) to locate older package releases.

Interactive Downgrade

Run shelly downgrade followed by the package name:

shelly downgrade linux-cachyos

Looking for downgrade options for: linux-cachyos
Select Package
  1) linux-cachyos-7.0.11-1-x86_64.pkg.tar.zst (Remote: archive.cachyos.org)
  2) linux-cachyos-7.1.3-2-x86_64.pkg.tar.zst (Remote: archive.cachyos.org)
  3) linux-cachyos-7.1.6-1-x86_64.pkg.tar.zst (Remote: archive.cachyos.org)
  4) linux-cachyos-7.2.0-1-x86_64_v4.pkg.tar.zst (Remote: archive.cachyos.org)
  5) linux-cachyos-7.2.2-1-x86_64_v3.pkg.tar.zst (Remote: archive.cachyos.org)
  6) linux-cachyos-7.2.2-1-x86_64_v4.pkg.tar.zst (Remote: archive.cachyos.org)
  7) linux-cachyos-7.2.2-1-x86_64_v4.pkg.tar.zst (Local)
  8) linux-cachyos-7.2.3-1-x86_64_v3.pkg.tar.zst (Remote: archive.cachyos.org)
  9) linux-cachyos-7.2.3-1-x86_64_v4.pkg.tar.zst (Remote: archive.cachyos.org)
  10) linux-cachyos-7.2.3-1-x86_64_v4.pkg.tar.zst (Local)
  11) linux-cachyos-7.2.4-1-x86_64_v4.pkg.tar.zst (Local)
  12) linux-cachyos-7.2.4-2-x86_64_v3.pkg.tar.zst (Remote: archive.cachyos.org)
Select [1-12] (12):

Automated Downgrade & Version Pinning

To prevent the next system upgrade from immediately overwriting your downgraded package, pass -i (or --ignore) to automatically add it to IgnorePkg:

# Downgrade and pin the package in one step
shelly downgrade linux --ignore

You can also target specific versions directly without interactive prompts:

# Install an exact version
shelly downgrade mesa --target 24.3.3-1

# Select the oldest available version
shelly downgrade mesa --oldest

Package Pinning & Marking (`shelly mark`)

shelly mark modifies package state flags and rules in your ALPM configuration.

1. Managing Upgrade Exclusions (`IgnorePkg`)

Packages added to IgnorePkg are skipped during shelly upgrade transactions.

shelly mark ignore --list
# Shortcode:
shelly -Mgl

shelly mark ignore --add linux linux-headers
# Shortcode:
shelly -Mga linux linux-headers

shelly mark ignore --remove linux linux-headers
# Shortcode:
shelly -Mgr linux linux-headers

2. Protecting Packages from Removal (`HoldPkg`)

Critical system packages (such as systemd or glibc) can be placed in HoldPkg to guard against accidental deletion:

# Add package to protection list
shelly mark hold --add base-devel

# List currently held packages
shelly mark hold --list

3. Changing Installation Reasons

ALPM tracks whether a package was installed explicitly by you or automatically as a dependency. This metadata determines whether shelly purify considers the package an orphan when other software is removed.

Mark as Explicit
Mark as Dependency

Convert a dependency into an explicitly installed package so it is never removed during orphan cleanups:

shelly mark explicit git
# Shortcode:
shelly -Me git

Convert an explicitly installed package into a dependency (eligible for orphan cleanup when no longer required by other packages):

shelly mark dependency libpng
# Shortcode:
shelly -Md libpng

Declarative System Backups (`shelly backup`)

Setting up a new machine or backing up your package configuration is seamless with shelly backup. It exports all explicitly installed packages across native ALPM, AUR, and Flatpak into a structured, portable TOML file.

1. Exporting Your System State

Export your installed packages to TOML:

shelly backup --export

By default, this writes a timestamped file such as 20260913103000_shelly.toml to $XDG_CACHE_HOME/Shelly/. You can customize the name and directory:

shelly backup --export --name workstation-setup --directory ~/dotfiles/

Example Backup File (`workstation-setup.toml`)

standard = [
  "base",
  "base-devel",
  "git",
  "kitty",
  "neovim",
  "pipewire",
  "zig",
]

aur = [
  "ccls-git",
  "visual-studio-code-bin",
  "zen-browser-bin",
]

flatpak = [
  "com.spotify.Client",
  "org.mozilla.Thunderbird",
  "org.signal.Signal",
]

2. Restoring on a New System

To replicate your environment on a fresh Arch installation:

shelly backup --import --name workstation-setup --directory ~/dotfiles/

--import requires --name so Shelly can locate the manifest.

Shelly reads the declarative manifest and coordinates the installation:

Installs all official repository packages via ALPM.
Clones, reviews, and compiles AUR packages.
Installs Flatpak applications from configured remotes.

Command Reference & Shortcodes

Summary of Shortcodes

Shelly shortcodes provide fast keyboard access for common administrative flows:

Action	Shortcode	Full Command Equivalent
Upgrade All	`shelly -U`	`shelly upgrade all`
Upgrade Standard	`shelly -Us`	`shelly upgrade standard`
Upgrade AUR	`shelly -Ua`	`shelly upgrade aur`
Upgrade Flatpaks	`shelly -Uf`	`shelly upgrade flatpak`
Downgrade	`shelly -D <pkg>`	`shelly downgrade <pkg>`
Downgrade & Pin	`shelly -Di <pkg>`	`shelly downgrade <pkg> --ignore`
List Ignored	`shelly -Mgl`	`shelly mark ignore --list`
Add Ignored	`shelly -Mga <pkgs>`	`shelly mark ignore --add <pkgs>`
Remove Ignored	`shelly -Mgr <pkgs>`	`shelly mark ignore --remove <pkgs>`
Mark Explicit	`shelly -Me <pkg>`	`shelly mark explicit <pkg>`
Mark Dependency	`shelly -Md <pkg>`	`shelly mark dependency <pkg>`
Export Backup	`shelly -Be`	`shelly backup --export`
Import Backup	`shelly -Bi`	`shelly backup --import`

System Upgrades, Rollbacks & Backups

Coordinated System Upgrades (shelly upgrade)

Upgrading All Backends in One Command

Targeted Upgrades & Filters

Package Rollbacks (shelly downgrade)