Skip to content
Seafoam Labs

Shelly Configuration

Shelly configuration is divided by responsibility. The CLI and GUI have separate JSON preferences, while native package operations and package builds each have their own configuration:

  • ~/.config/shelly/config.json - CLI preferences, including NativePackageBackend.
  • ~/.config/shelly/settings.json - GUI and notification-service preferences.
  • /etc/pacman.conf or /etc/shelly.conf - Native repositories and package-manager options. The selected distribution path profile determines the default file; RLPM reads the configured native package settings.
  • /etc/shellybuild.conf - Settings for the separate shelly build package builder. It does not configure RLPM or native package transactions. See Building Packages.

The pacman path profile is the default. A distribution can build Shelly with the devario profile to use Shelly-owned system paths, including /etc/shelly.conf instead of /etc/pacman.conf. Backend selection (libalpm or RLPM) and path-profile selection are separate choices. See RLPM for the profile paths and backend details.

If a CLI or GUI preference file is broken, you can edit it directly. shelly config reset restores CLI defaults; removing config.json or settings.json allows Shelly to regenerate that preference file on start. This reset does not change the native package configuration or shellybuild.conf.

Configuration Files and Their Roles

Section titled “Configuration Files and Their Roles”

The files above configure different parts of Shelly and are not interchangeable. In particular, NativePackageBackend selects the native transaction engine; it does not select the distribution path profile. shellybuild.conf controls package compilation only and has no effect on repository transactions.

CLI Configuration (config.json)

Section titled “CLI Configuration (config.json)”

Below is the authoritative default configuration for the Shelly CLI (~/.config/shelly/config.json):

{
  "NativePackageBackend": "libalpm",
  "FileSizeDisplay": "Megabytes",
  "ParallelDownloadCount": 100,
  "DownloadAddressFamilyPolicy": "PreferIPv4",
  "ProgressBarStyle": "Blocks",
  "ProgressBarWidth": 24,
  "OutputMode": "singlepane",
  "AppImageInstallPath": null,
  "DisableAppImageUpdateCheck": false,
  "DisableFlatpakUpdateCheck": false,
  "AutoConfirmCacheClean": false,
  "DisableCacheClean": false,
  "CollapsePkgbuildDiff": true,
  "AurUrl": "https://aur.archlinux.org"
}

CLI Fields

Section titled “CLI Fields”

The following fields configure the CLI (shelly). Modifying these options affects only CLI operations.

  1. NativePackageBackend
    • Native package engine used for repository operations. "libalpm" selects the library behind pacman; "rlpm" selects Shelly’s own native engine. Takes effect on the next CLI invocation, and the GUI follows the CLI selection. See RLPM for the full comparison and the switch walk-through.
    • Options: "libalpm" (default) and "rlpm". RLPM-only builds accept only "rlpm".
    • Type: string (default: "libalpm").
  2. FileSizeDisplay
    • Display format for file and package sizes in CLI output.
    • Options: "Bytes", "Megabytes", "Gigabytes" (default: "Megabytes").
  3. ParallelDownloadCount
    • Maximum number of concurrent downloads used by the ALPM download engine. Setting this to 1 disables parallel downloads. Higher values can cause rate limiting from package mirrors.
    • Type: integer (default: 100).
  4. DownloadAddressFamilyPolicy
    • Network address resolution and connection policy used during package downloads.
    • Options:
      • "PreferIPv4" (default) - Prefers IPv4 connections.
      • "PreferIPv6" - Uses Happy Eyeballs connection racing with an IPv6 preference.
      • "IPv4Only" - Forces IPv4-only connections.
      • "IPv6Only" - Forces IPv6-only connections.
  5. ProgressBarStyle
    • Visual animation and layout style of download and transaction progress bars.
    • Options:
      • "Blocks" (default) - Renders solid Unicode block segments filling the progress bar width.
      • "Pacman" - Renders a Pac-Man animation eating power pellets, matching pacman’s ILoveCandy mode.
  6. ProgressBarWidth
    • Character column width of the progress bar in the CLI terminal output.
    • Type: integer (default: 24).
  7. OutputMode
    • Layout mode for terminal progress and log output.
    • Options: "singlepane" (default).
  8. AppImageInstallPath
    • Custom filesystem path where AppImage binaries are downloaded and integrated into the desktop environment. When set to null or omitted, defaults to ~/.local/bin ($XDG_BIN_HOME).
    • Type: string or null (default: null).
  9. DisableAppImageUpdateCheck
    • Skips the AppImage update check during aggregate upgrades (shelly upgrade all, or any upgrade command with --all). The --disable-appimage-update-check flag overrides this per invocation.
    • Type: boolean (default: false).
  10. DisableFlatpakUpdateCheck
    • Skips the Flatpak update check during aggregate upgrades (shelly upgrade all, or any upgrade command with --all). The --disable-flatpak-update-check flag overrides this per invocation.
    • Type: boolean (default: false).
  11. AutoConfirmCacheClean
    • Automatically answers yes to removing extra cache entries during aggregate upgrades (shelly upgrade all), without prompting for confirmation.
    • Type: boolean (default: false).
  12. DisableCacheClean
    • Skips removing extra cache entries during aggregate upgrades (shelly upgrade all, or any upgrade command with --all). AutoConfirmCacheClean instead auto-answers the removal prompt. The --disable-cache-clean flag overrides this per invocation.
    • Type: boolean (default: false).
  13. CollapsePkgbuildDiff
    • Collapses the PKGBUILD review diff to changed sections when a previous version of the recipe exists, instead of displaying the complete file.
    • Type: boolean (default: true).
  14. AurUrl
    • Base URL of the Arch User Repository (AUR) service used for Git clones and RPC requests. Can be overridden per command using the --aur-url option.
    • Type: string (default: "https://aur.archlinux.org").

GUI Configuration (settings.json)

Section titled “GUI Configuration (settings.json)”

Below is the default configuration for the Shelly GUI and system tray service (~/.config/shelly/settings.json):

{
  "Culture": "",
  "NewInstall": true,
  "NoConfirm": false,
  "AurEnabled": false,
  "AurWarningConfirmed": false,
  "AppImageEnabled": false,
  "FlatPackEnabled": false,
  "RecommendedEnabled": true,
  "ShellyIconsEnabled": true,
  "ShellySearchEnabled": false,
  "WebviewEnabled": false,
  "DefaultPageDropDown": "packages",
  "NavMode": "sidebar",
  "WindowLastWidth": 0,
  "WindowLastHeight": 0,
  "PackageInstallView": "grid",
  "PackageManagementCascadeDelete": true,
  "PackageManagementRemoveConfigs": false,
  "PackageManagementRemoveOptionalDeps": true,
  "PackageInstallUpgrade": false,
  "PackageInstallShowHidden": false,
  "PackageInstallShowExplicitOnly": false,
  "PackageInstallShowDependsOnly": false,
  "PackageInstallShowDetailPane": false,
  "AurInstallUseChroot": false,
  "AurInstallRunChecks": false,
  "AurInstallShowDetailPane": false,
  "AurInstallDisableDevel": false,
  "AurRemoveCascadeDelete": true,
  "AurUpdateRunChecks": false,
  "AurUpdateShowHidden": false,
  "SearchShowDetailPane": false,
  "TrayEnabled": false,
  "TrayAutoStart": false,
  "TrayCheckIntervalHours": 72,
  "UseSymbolicTray": true,
  "TrayIconPath": "",
  "TrayUpdatesIconPath": "",
  "UseUiForUpdate": false,
  "UseWeeklySchedule": false,
  "DaysOfWeek": [],
  "Time": ""
}

GUI Fields

Section titled “GUI Fields”

The following fields configure the GUI (shelly-ui) and background notifications (shelly-notifications). Modifying these values does not alter CLI defaults.

General & Navigation

Section titled “General & Navigation”
  1. Culture
    • Language and locale code for UI localization (e.g., "" for system default, "en", "de_DE", "es", "fr_FR", "ja_JP", "ru_RU", "zh_CN").
    • Type: string (default: "").
  2. NewInstall
    • Indicates whether Shelly is running for the first time. When true, Shelly presents initial onboarding and feature setup prompts.
    • Type: boolean (default: true).
  3. NoConfirm
    • When true, automatically accepts confirmation dialogs without blocking for user interaction.
    • Type: boolean (default: false).
  4. ShellyIconsEnabled
    • Enables or disables displaying package icons throughout the user interface.
    • Type: boolean (default: true).
  5. ShellySearchEnabled
    • Enables or disables the Shelly Search view in the application.
    • Type: boolean (default: false).
  6. WebviewEnabled
    • Enables embedded web view functionality for displaying package details and documentation web pages.
    • Type: boolean (default: false).
  7. DefaultPageDropDown
    • Sets the default view/tab loaded when launching shelly-ui.
    • Options: "recommend", "packages", "aur", "flatpak", "app_image", "shelly_search", "update" (default: "packages").
  8. NavMode
    • Navigation layout mode for the graphical window.
    • Options: "sidebar" (vertical sidebar) or "topbar" (horizontal top bar) (default: "sidebar").
  9. WindowLastWidth / WindowLastHeight
    • Remembers the last window dimensions in pixels for restoration across sessions.
    • Type: integer (default: 0).

Package Sources & Ecosystems

Section titled “Package Sources & Ecosystems”
  1. AurEnabled
    • Enables or disables Arch User Repository (AUR) package management features.
    • Type: boolean (default: false).
  2. AurWarningConfirmed
    • Records whether the user has acknowledged the AUR usage and security disclaimer dialog.
    • Type: boolean (default: false).
  3. AppImageEnabled
    • Enables or disables AppImage integration and update tracking.
    • Type: boolean (default: false).
  4. FlatPackEnabled
    • Enables or disables Flatpak application management via libflatpak and the companion backend.
    • Type: boolean (default: false).
  5. RecommendedEnabled
    • Displays curated recommended software packages in the UI.
    • Type: boolean (default: true).

Standard Package Management

Section titled “Standard Package Management”
  1. PackageInstallView
    • Layout style for browsing repository packages.
    • Options: "grid" (card/grid layout) or "list" (tabular list layout) (default: "grid").
  2. PackageManagementCascadeDelete
    • When removing packages, recursively removes dependencies that are no longer required by any other installed package (-Rs).
    • Type: boolean (default: true).
  3. PackageManagementRemoveConfigs
    • When removing packages, removes configuration files and backups created by the package (-Rn).
    • Type: boolean (default: false).
  4. PackageManagementRemoveOptionalDeps
    • When removing packages, removes optional dependencies that were installed alongside the package.
    • Type: boolean (default: true).
  5. PackageInstallUpgrade
    • Performs a complete system database and package upgrade (-Syu) before installing new standard packages.
    • Type: boolean (default: false).
  6. PackageInstallShowHidden
    • Displays packages tagged as hidden or internal system components in package lists.
    • Type: boolean (default: false).
  7. PackageInstallShowExplicitOnly
    • Filters the installed packages list to display only explicitly installed packages.
    • Type: boolean (default: false).
  8. PackageInstallShowDependsOnly
    • Filters the installed packages list to display only packages installed as dependencies.
    • Type: boolean (default: false).
  9. PackageInstallShowDetailPane
    • Toggles the side detail pane in the standard package management view.
    • Type: boolean (default: false).

AUR Package Management

Section titled “AUR Package Management”
  1. AurInstallUseChroot
    • Builds AUR packages inside a clean systemd-nspawn / chroot container rather than on the host system.
    • Type: boolean (default: false).
  2. AurInstallRunChecks
    • Executes the check() test routines in PKGBUILD scripts during AUR package compilation.
    • Type: boolean (default: false).
  3. AurInstallShowDetailPane
    • Toggles the side detail pane in the AUR package view.
    • Type: boolean (default: false).
  4. AurInstallDisableDevel
    • Skips checking development and VCS packages (e.g., -git, -svn, -hg) during AUR update checks.
    • Type: boolean (default: false).
  5. AurRemoveCascadeDelete
    • Recursively removes unneeded dependencies when uninstalling AUR packages.
    • Type: boolean (default: true).
  6. AurUpdateRunChecks
    • Executes check() test routines during AUR package upgrades.
    • Type: boolean (default: false).
  7. AurUpdateShowHidden
    • Displays hidden packages in the AUR updates view.
    • Type: boolean (default: false).
Section titled “Search”
  1. SearchShowDetailPane
    • Toggles the side detail pane in search results.
    • Type: boolean (default: false).

System Tray & Background Updates

Section titled “System Tray & Background Updates”
  1. TrayEnabled
    • Enables and starts the Shelly system tray daemon (shelly-notifications).
    • Type: boolean (default: false).
  2. TrayAutoStart
    • Manages a systemd user service (shelly-tray.service) to start the background tray daemon automatically on session login.
    • Type: boolean (default: false).
  3. TrayCheckIntervalHours
    • Number of hours between automatic background package update checks.
    • Type: integer (default: 72).
  4. UseSymbolicTray
    • Uses monochrome symbolic icons for the system tray icon rather than colored icons.
    • Type: boolean (default: true).
  5. TrayIconPath
    • Absolute filesystem path to a custom idle tray icon. If left blank, the bundled Shelly tray icon is used.
    • Type: string (default: "").
  6. TrayUpdatesIconPath
    • Absolute filesystem path to a custom tray icon displayed when pending updates are detected. If left blank, the bundled update icon is used.
    • Type: string (default: "").
  7. UseUiForUpdate
    • When clicking an update notification:
      • true - Launches the graphical interface (shelly-ui --tray-updates).
      • false - Opens an interactive CLI update session (shelly) inside your desktop’s default terminal emulator.
    • Type: boolean (default: false).
  8. UseWeeklySchedule
    • Enables scheduled periodic update checks at specific days and times instead of interval-based checks.
    • Type: boolean (default: false).
  9. DaysOfWeek
    • Array of days of the week on which scheduled update checks run. Accepted day names: "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday" (or numeric indices 0–6).
    • Type: array of strings/integers (default: []).
  10. Time
    • Time of day (format "HH:MM" or "HH:MM:SS") when scheduled weekly update checks execute.
    • Type: string (default: "").

Environment Variables

Section titled “Environment Variables”

If you set the environment variable SHELLY_ELEVATOR, Shelly will use the designated privilege elevator in the CLI rather than detecting one in $PATH. Shelly falls back to sudo if nothing is detected. The natively detected elevators are currently doas, sudo, and run0 (evaluated in that order).

© 2026 Seafoam LabsShelly Chel