caelestia-shell

out.mp4

Components

• Widgets: Quickshell
• Window manager: Hyprland
• Dots: caelestia

Installation

Note

This repo is for Caelestia's desktop shell only. If you want installation instructions for the entire dotfiles (which include this shell), head to the main repo instead.

Arch Linux

Warning

If you want to make your own changes/tweaks to the shell, do NOT edit the files installed by the AUR package. Instead, follow the instructions in the manual installation section.

The shell is available from the AUR as caelestia-shell. You can install it with an AUR helper (recommended), like paru, or by manually downloading the PKGBUILD and running makepkg -si.

A package following the latest commit also exists as caelestia-shell-git. This is bleeding-edge and likely to be unstable/have bugs. Regular users are recommended to use the stable package (caelestia-shell).

Nix

You can run the shell directly via nix run:

nix run github:caelestia-dots/shell#with-cli

Or add it to your system configuration:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

    caelestia-shell = {
      url = "github:caelestia-dots/shell";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}

For full functionality, use caelestia-shell.packages.<system>.with-cli, which can be added to your environment.systemPackages, users.users.<username>.packages, home.packages if using home-manager, or a devshell. The default package does not include the CLI. You can then run the shell with caelestia-shell.

For home-manager, you can also use Caelestia's Home Manager module (explained in the configuration section), which installs and configures the shell and CLI.

Manual installation

Dependencies:

• caelestia-cli
• quickshell-git - this has to be the git version, not the latest tagged version
• glibc
• gcc-libs
• ddcutil
• brightnessctl
• libcava
• networkmanager
• lm_sensors
• aubio
• libpipewire
• libqalculate
• power-profiles-daemon
• ttf-material-symbols-variable
• ttf-rubik-vf
• ttf-cascadia-code-nerd
• qt6-base
• qt6-declarative
• qt6-imageformats
• swappy
• fish
• bash

Build dependencies:

• cmake
• ninja
• qt6-shadertools

Important

The commands below (and in the "Updating" section) assume $XDG_CONFIG_HOME is set. If it is unset, substitute it with the path to your config folder (typically ~/.config).

To install the shell manually, install all dependencies and clone this repo to $XDG_CONFIG_HOME/quickshell/caelestia. Then build and install using CMake.

cd $XDG_CONFIG_HOME/quickshell
git clone https://github.com/caelestia-dots/shell.git caelestia

cd caelestia
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/
cmake --build build
sudo cmake --install build

Tip

You can customise the installation location via the CMake flags INSTALL_LIBDIR, INSTALL_QMLDIR, and INSTALL_QSCONFDIR for the libraries (e.g. the version helper), QML plugin, and Quickshell config directories respectively. If you set the INSTALL_LIBDIR flag, the CAELESTIA_LIB_DIR variable must also be set to the same directory in your system's environment.

For example, installing to ~/.config/quickshell/caelestia for easy local changes:

mkdir -p ~/.config/quickshell/caelestia
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/ -DINSTALL_QSCONFDIR="$HOME/.config/quickshell/caelestia"
cmake --build build
sudo cmake --install build
sudo chown -R $USER ~/.config/quickshell/caelestia

Usage

You can start the shell by running caelestia shell -d (preferred) or qs -c caelestia -n -d. You may omit -d from the command to keep the shell attached to the current terminal if necessary, though you likely want it to be detached (so it doesn't close when the terminal is closed).

If using the Caelestia dotfiles, the shell will be autostarted on login via a hl.on("hyprland.start", ...) function in the Hyprland config.

Shortcuts/IPC

All keybinds are accessible via Hyprland global shortcuts. If using the Caelestia dotfiles, the keybinds are already configured for you. Otherwise, the keybinds.lua file contains an example of how to use global shortcuts.

All IPC commands can be accessed via caelestia shell ..., for example:

caelestia shell mpris getActive trackTitle

You can view the list of available IPC commands by running caelestia shell -s.

PFP/Wallpapers

The profile picture for the dashboard is read from the file ~/.face. You can set it by clicking it in the dashboard, or by manually copying or symlinking your image to the path.

The wallpapers for the wallpaper switcher are read from ~/Pictures/Wallpapers by default. To change it, modify paths.wallpaperDir in ~/.config/caelestia/shell.json.

To set the wallpaper, you can type >wallpaper in the launcher to open the wallpaper switcher. Alternatively, you can also use caelestia wallpaper -f <path_to_wallpaper> to set the wallpaper directly. Use caelestia wallpaper -h for more info about this command.

Updating

Packaged install (AUR)

If using the full dotfiles or the CLI, run caelestia update to perform a full system update and update the dots. Otherwise, if you installed the shell on its own, update your system using your AUR helper (e.g., paru).

Manual install

If you installed the shell manually by cloning the repo, you can update by pulling the changes from git in the local checkout.

For example, if you installed to $XDG_CONFIG_HOME/quickshell/caelestia:

cd $XDG_CONFIG_HOME/quickshell/caelestia
git pull

Configuring

All configuration options belong in ~/.config/caelestia/shell.json. This file is not created by default; you must create it manually. Options that you omit from the config file will use their default values.

Per-monitor configuration

You can configure per-monitor options in ~/.config/caelestia/monitors/<monitor_name>/shell.json. List the names of your available monitors by running:

hyprctl monitors -j | jq -r '.[].name'

Options set in these files will override the respective options in the global config. Any options not present in per-monitor configs will inherit their values from the global config.

For example, to automatically hide the bar on the monitor named DP-1:

~/.config/caelestia/monitors/DP-1/shell.json

{
    "bar": {
        "persistent": false
    }
}

Note

Not all options respect per-monitor overrides. Most notably, the following options will only read from the global config, and ignore the respective option in per-monitor config files.

Ignored options

• appearance: anim.*, transparency.*
• bar.tray: hiddenIcons, iconSubs
• bar.workspaces: perMonitorWorkspaces, specialWorkspaceIcons, windowIcons
• dashboard: mediaUpdateInterval, resourceUpdateInterval
• general: apps.*, battery.*, idle.*, logo
• launcher: actionPrefix, actions, enableDangerousActions, favouriteApps, hiddenApps, specialPrefix, useFuzzy.*, vimKeybinds
• lock: enableFprint, enableHowdy, maxFprintTries, maxHowdyTries, triggerHowdyOnWake
• nexus: networkRescanInterval
• notifs: actionOnClick, defaultExpireTimeout, expire, fullscreen, fullscreenExpireTimeout
• paths: lyricsDir, wallpaperDir
• services: audioIncrement, brightnessIncrement, defaultPlayer, gpuType, lyricsBackend, maxVolume, playerAliases, smartScheme, useFahrenheit, useFahrenheitPerformance, useTwelveHourClock, visualiserBars, weatherLocation
• utilities.toasts: all except fullscreen
• utilities.vpn: enabled, provider, selectedProvider

Example configuration

Warning

The example configuration includes ALL configuration options in shell.json. It is not recommended to copy and paste this entire configuration into shell.json, as options or their default values may change across updates, resulting in a stale config.

This is meant to serve as a reference of all the available options, and you should only add the ones you want to change to shell.json.

Example config

{
    "enabled": true,
    "appearance": {
        "deformScale": 1,
        "rounding": {
            "scale": 1
        },
        "spacing": {
            "scale": 1
        },
        "padding": {
            "scale": 1
        },
        "font": {
            "scale": 1,
            "clock": "Rubik",
            "workspaces": "Rubik",
            "headline": {
                "family": "GoogleSansFlex",
                "large": { "size": 32, "weight": 500, "italic": false, "vaxes": { "ROND": 25 } },
                "medium": { "size": 28, "weight": 500, "italic": false, "vaxes": { "ROND": 25 } },
                "small": { "size": 24, "weight": 500, "italic": false, "vaxes": { "ROND": 25 } }
            },
            "title": {
                "family": "GoogleSansFlex",
                "large": { "size": 22, "weight": 500, "italic": false, "vaxes": { "ROND": 25 } },
                "medium": { "size": 16, "weight": 500, "italic": false, "vaxes": { "ROND": 25 } },
                "small": { "size": 14, "weight": 500, "italic": false, "vaxes": { "ROND": 25 } }
            },
            "body": {
                "family": "GoogleSansFlex",
                "large": { "size": 16, "weight": 400, "italic": false, "vaxes": { "ROND": 25 } },
                "medium": { "size": 14, "weight": 400, "italic": false, "vaxes": { "ROND": 25 } },
                "small": { "size": 12, "weight": 400, "italic": false, "vaxes": { "ROND": 25 } }
            },
            "label": {
                "family": "GoogleSansFlex",
                "large": { "size": 14, "weight": 500, "italic": false, "vaxes": { "ROND": 25 } },
                "medium": { "size": 12, "weight": 500, "italic": false, "vaxes": { "ROND": 25 } },
                "small": { "size": 11, "weight": 400, "italic": false, "vaxes": { "ROND": 25 } }
            },
            "mono": {
                "family": "CaskaydiaCove NF",
                "large": { "size": 16, "weight": 400, "italic": false, "vaxes": {} },
                "medium": { "size": 14, "weight": 400, "italic": false, "vaxes": {} },
                "small": { "size": 12, "weight": 400, "italic": false, "vaxes": {} }
            },
            "icon": {
                "family": "Material Symbols Rounded",
                "extraLarge": { "size": 36, "weight": 400, "italic": false, "vaxes": {} },
                "large": { "size": 24, "weight": 400, "italic": false, "vaxes": {} },
                "medium": { "size": 18, "weight": 400, "italic": false, "vaxes": {} },
                "small": { "size": 15, "weight": 400, "italic": false, "vaxes": {} }
            }
        },
        "anim": {
            "durations": {
                "scale": 1
            }
        },
        "transparency": {
            "enabled": false,
            "base": 0.85,
            "layers": 0.4
        }
    },
    "general": {
        "logo": "",
        "showOverFullscreen": false,
        "mediaGifSpeedAdjustment": 300,
        "sessionGifSpeed": 0.7,
        "apps": {
            "terminal": ["foot"],
            "audio": ["pwvucontrol"],
            "playback": ["mpv"],
            "explorer": ["thunar"]
        },
        "idle": {
            "lockBeforeSleep": true,
            "inhibitWhenAudio": true,
            "inhibitWhenCharging": false,
            "timeouts": [
                {
                    "timeout": 180,
                    "idleAction": "lock",
                    "inhibitWhenAudio": false,
                    "inhibitWhenCharging": false,
                    "respectInhibitors": true
                },
                {
                    "timeout": 300,
                    "idleAction": "dpms off",
                    "returnAction": "dpms on"
                },
                {
                    "timeout": 600,
                    "idleAction": ["suspendThenHibernate"]
                }
            ]
        },
        "battery": {
            "warnLevels": [
                {
                    "level": 20,
                    "title": "Low battery",
                    "message": "You might want to plug in a charger",
                    "icon": "battery_android_frame_2"
                },
                {
                    "level": 10,
                    "title": "Did you see the previous message?",
                    "message": "You should probably plug in a charger <b>now</b>",
                    "icon": "battery_android_frame_1"
                },
                {
                    "level": 5,
                    "title": "Critical battery level",
                    "message": "PLUG THE CHARGER RIGHT NOW!!",
                    "icon": "battery_android_alert",
                    "critical": true
                }
            ],
            "criticalLevel": 3
        }
    },
    "background": {
        "enabled": true,
        "wallpaperEnabled": true,
        "desktopClock": {
            "enabled": false,
            "scale": 1.0,
            "position": "bottom-right",
            "invertColors": false,
            "background": {
                "enabled": false,
                "opacity": 0.7,
                "blur": true
            },
            "shadow": {
                "enabled": true,
                "opacity": 0.7,
                "blur": 0.4
            }
        },
        "visualiser": {
            "enabled": false,
            "autoHide": true,
            "blur": false,
            "rounding": 1,
            "spacing": 1
        }
    },
    "bar": {
        "persistent": true,
        "showOnHover": true,
        "dragThreshold": 20,
        "scrollActions": {
            "workspaces": true,
            "volume": true,
            "brightness": true
        },
        "popouts": {
            "activeWindow": true,
            "tray": true,
            "statusIcons": true
        },
        "workspaces": {
            "shown": 5,
            "activeIndicator": true,
            "occupiedBg": false,
            "showWindows": true,
            "showWindowsOnSpecialWorkspaces": true,
            "maxWindowIcons": 5,
            "activeTrail": false,
            "perMonitorWorkspaces": true,
            "label": "  ",
            "occupiedLabel": "󰮯",
            "activeLabel": "󰮯",
            "capitalisation": "preserve",
            "specialWorkspaceIcons": [
                {
                    "name": "steam",
                    "icon": "sports_esports"
                }
            ],
            "windowIcons": [
                {
                    "regex": "steam(_app_(default|[0-9]+))?",
                    "icon": "sports_esports"
                }
            ]
        },
        "activeWindow": {
            "compact": false,
            "inverted": false,
            "showOnHover": true
        },
        "tray": {
            "background": false,
            "recolour": false,
            "compact": false,
            "iconSubs": [],
            "hiddenIcons": []
        },
        "clock": {
            "background": false,
            "showDate": false,
            "showIcon": true
        },
        "statusIcons": [
            {
                "id": "lockStatus",
                "enabled": true
            },
            {
                "id": "audio",
                "enabled": false
            },
            {
                "id": "microphone",
                "enabled": false
            },
            {
                "id": "kbLayout",
                "enabled": false
            },
            {
                "id": "network",
                "enabled": true
            },
            {
                "id": "bluetooth",
                "enabled": true
            },
            {
                "id": "battery",
                "enabled": true
            }
        ],
        "entries": [
            {
                "id": "logo",
                "enabled": true
            },
            {
                "id": "workspaces",
                "enabled": true
            },
            {
                "id": "spacer",
                "enabled": true
            },
            {
                "id": "activeWindow",
                "enabled": true
            },
            {
                "id": "spacer",
                "enabled": true
            },
            {
                "id": "tray",
                "enabled": true
            },
            {
                "id": "clock",
                "enabled": true
            },
            {
                "id": "statusIcons",
                "enabled": true
            },
            {
                "id": "power",
                "enabled": true
            }
        ],
        "excludedScreens": []
    },
    "border": {
        "thickness": 10,
        "rounding": 25,
        "smoothing": 20
    },
    "dashboard": {
        "enabled": true,
        "showOnHover": true,
        "showDashboard": true,
        "showMedia": true,
        "showPerformance": true,
        "showWeather": true,
        "mediaUpdateInterval": 500,
        "resourceUpdateInterval": 1000,
        "dragThreshold": 50,
        "performance": {
            "showBattery": true,
            "showGpu": true,
            "showCpu": true,
            "showMemory": true,
            "showStorage": true,
            "showNetwork": true
        }
    },
    "launcher": {
        "enabled": true,
        "showOnHover": false,
        "maxShown": 7,
        "maxWallpapers": 9,
        "specialPrefix": "@",
        "actionPrefix": ">",
        "enableDangerousActions": false,
        "dragThreshold": 50,
        "vimKeybinds": false,
        "favouriteApps": [],
        "hiddenApps": [],
        "useFuzzy": {
            "apps": false,
            "actions": false,
            "schemes": false,
            "variants": false,
            "wallpapers": false
        },
        "actions": [
            {
                "name": "Calculator",
                "icon": "calculate",
                "description": "Do simple math equations (powered by Qalc)",
                "command": ["autocomplete", "calc"],
                "enabled": true,
                "dangerous": false
            },
            {
                "name": "Scheme",
                "icon": "palette",
                "description": "Change the current colour scheme",
                "command": ["autocomplete", "scheme"],
                "enabled": true,
                "dangerous": false
            },
            {
                "name": "Wallpaper",
                "icon": "image",
                "description": "Change the current wallpaper",
                "command": ["autocomplete", "wallpaper"],
                "enabled": true,
                "dangerous": false
            },
            {
                "name": "Variant",
                "icon": "colors",
                "description": "Change the current scheme variant",
                "command": ["autocomplete", "variant"],
                "enabled": true,
                "dangerous": false
            },
            {
                "name": "Random",
                "icon": "casino",
                "description": "Switch to a random wallpaper",
                "command": ["caelestia", "wallpaper", "-r"],
                "enabled": true,
                "dangerous": false
            },
            {
                "name": "Light",
                "icon": "light_mode",
                "description": "Change the scheme to light mode",
                "command": ["setMode", "light"],
                "enabled": true,
                "dangerous": false
            },
            {
                "name": "Dark",
                "icon": "dark_mode",
                "description": "Change the scheme to dark mode",
                "command": ["setMode", "dark"],
                "enabled": true,
                "dangerous": false
            },
            {
                "name": "Shutdown",
                "icon": "power_settings_new",
                "description": "Shutdown the system",
                "command": ["poweroff"],
                "enabled": true,
                "dangerous": true
            },
            {
                "name": "Reboot",
                "icon": "cached",
                "description": "Reboot the system",
                "command": ["reboot"],
                "enabled": true,
                "dangerous": true
            },
            {
                "name": "Logout",
                "icon": "exit_to_app",
                "description": "Log out of the current session",
                "command": ["logout"],
                "enabled": true,
                "dangerous": true
            },
            {
                "name": "Lock",
                "icon": "lock",
                "description": "Lock the current session",
                "command": ["loginctl", "lock-session"],
                "enabled": true,
                "dangerous": false
            },
            {
                "name": "Sleep",
                "icon": "bedtime",
                "description": "Suspend then hibernate",
                "command": ["suspendThenHibernate"],
                "enabled": true,
                "dangerous": false
            },
            {
                "name": "Settings",
                "icon": "settings",
                "description": "Configure the shell",
                "command": ["caelestia", "shell", "nexus", "open"],
                "enabled": true,
                "dangerous": false
            }
        ]
    },
    "lock": {
        "enabled": true,
        "useWallpaper": false,
        "recolourLogo": true,
        "enableFprint": true,
        "maxFprintTries": 3,
        "enableHowdy": true,
        "maxHowdyTries": 3,
        "triggerHowdyOnWake": true,
        "hideNotifs": false
    },
    "nexus": {
        "wallpapersPerRow": 4,
        "networkRescanInterval": 15000
    },
    "notifs": {
        "expire": true,
        "fullscreen": "on",
        "defaultExpireTimeout": 5000,
        "fullscreenExpireTimeout": 2000,
        "clearThreshold": 0.3,
        "expandThreshold": 20,
        "actionOnClick": false,
        "groupPreviewNum": 3,
        "openExpanded": false
    },
    "osd": {
        "enabled": true,
        "hideDelay": 2000,
        "enableBrightness": true,
        "enableMicrophone": false
    },
    "services": {
        "weatherLocation": "",
        "useFahrenheit": false,
        "useFahrenheitPerformance": false,
        "useTwelveHourClock": false,
        "gpuType": "",
        "visualiserBars": 60,
        "audioIncrement": 0.1,
        "brightnessIncrement": 0.1,
        "maxVolume": 1.0,
        "smartScheme": true,
        "defaultPlayer": "Spotify",
        "playerAliases": [{ "from": "com.github.th_ch.youtube_music", "to": "YT Music" }],
        "lyricsBackend": "Auto"
    },
    "session": {
        "enabled": true,
        "dragThreshold": 30,
        "vimKeybinds": false,
        "icons": {
            "logout": "logout",
            "shutdown": "power_settings_new",
            "hibernate": "downloading",
            "reboot": "cached"
        },
        "commands": {
            "logout": ["logout"],
            "shutdown": ["poweroff"],
            "hibernate": ["hibernate"],
            "reboot": ["reboot"]
        }
    },
    "sidebar": {
        "enabled": true,
        "showOnHover": false,
        "minHoverThreshold": 200,
        "dragThreshold": 80
    },
    "utilities": {
        "enabled": true,
        "maxToasts": 4,
        "toasts": {
            "fullscreen": "off",
            "configLoaded": true,
            "chargingChanged": true,
            "gameModeChanged": true,
            "dndChanged": true,
            "audioOutputChanged": true,
            "audioInputChanged": true,
            "capsLockChanged": true,
            "numLockChanged": true,
            "kbLayoutChanged": true,
            "kbLimit": true,
            "vpnChanged": true,
            "nowPlaying": false
        },
        "vpn": {
            "enabled": false,
            "provider": [
                {
                    "name": "wireguard",
                    "interface": "your-connection-name",
                    "displayName": "Wireguard (Your VPN)",
                    "enabled": false
                }
            ]
        },
        "quickToggles": [
            {
                "id": "wifi",
                "enabled": true
            },
            {
                "id": "bluetooth",
                "enabled": true
            },
            {
                "id": "mic",
                "enabled": true
            },
            {
                "id": "settings",
                "enabled": true
            },
            {
                "id": "gameMode",
                "enabled": true
            },
            {
                "id": "dnd",
                "enabled": true
            },
            {
                "id": "vpn",
                "enabled": false
            }
        ]
    },
    "paths": {
        "wallpaperDir": "~/Pictures/Wallpapers",
        "lyricsDir": "~/Music/lyrics/",
        "sessionGif": "root:/assets/kurukuru.gif",
        "mediaGif": "root:/assets/bongocat.gif",
        "noNotifsPic": "root:/assets/dino.png",
        "lockNoNotifsPic": "root:/assets/dino.png"
    }
}

Advanced configuration

Caution

Do NOT change any of these options unless you know what you are doing. These options control the tokens used internally within the shell, and can cause visual issues if modified incorrectly. The available options may change or be removed without notice across versions.

A separate ~/.config/caelestia/shell-tokens.json file allows editing the internal tokens without touching the source code of the shell. These tokens affect the dimensions and appearance of visual elements, including individual rounding, spacing, padding, font size, animation durations and curves, and the sizes of certain components. The appearance scale values in shell.json are multiplied against these base token values to produce the final computed values.

Per-monitor token overrides are also available at ~/.config/caelestia/monitors/<monitor_name>/shell-tokens.json.

Home Manager Module

For NixOS users, a Home Manager module is also available.

home.nix

programs.caelestia = {
  enable = true;
  systemd = {
    enable = false; # if you prefer starting from your compositor
    target = "graphical-session.target";
    environment = [];
  };
  settings = {
    bar.statusIcons = [
      { id = "lockStatus"; enabled = true; }
      { id = "network"; enabled = true; }
      { id = "bluetooth"; enabled = true; }
      { id = "battery"; enabled = false; }
    ];
    paths.wallpaperDir = "~/Images";
  };
  cli = {
    enable = true; # Also add caelestia-cli to path
    settings = {
      theme.enableGtk = false;
    };
  };
};

The module automatically adds the shell to the path with full functionality. The CLI is not required; however, you can enable and configure it.

FAQ

Need help or support?

You can join the Caelestia Discord server for assistance and discussion here.

I want to make my own changes to the Hyprland config!

Check out the configuring section on the dots repo.

I want to make my own changes to other stuff!

See the manual installation section for the corresponding repo.

I want to disable ___ feature!

Please read the configuring section. If there is no corresponding option, make a feature request.

How do I make my colour scheme change to match my wallpaper?

Set a wallpaper via >wallpaper in the launcher or caelestia wallpaper, and set the scheme to the dynamic scheme via >scheme in the launcher or caelestia scheme set, e.g.:

caelestia wallpaper -f <path_to_wallpaper>
caelestia scheme set -n dynamic

My wallpapers aren't showing up in the launcher!

The launcher pulls wallpapers from ~/Pictures/Wallpapers by default. You can change this in the config. Additionally, the launcher only shows an odd number of wallpapers at one time. If you only have 2 wallpapers, consider getting more (or just putting one).

Credits

Thanks to the Hyprland Discord community (especially the homies in #rice-discussion) for all the help and suggestions for improving these dots!

A special thanks to @outfoxxed for making Quickshell and the effort put into fixing issues and implementing various feature requests.

Another special thanks to @end_4 for his config which helped me a lot with learning how to use Quickshell.

Finally, another thank you to all the configs I took inspiration from (only one for now):

• Axenide/Ax-Shell

Stonks 📈