caelestia-shell
https://github.com/user-attachments/assets/0840f496-575c-4ca6-83a8-87bb01a85c5f
Components
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][dots-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:
Build dependencies:
[!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][dots-repo], 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][dots-repo], 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, iconSubsbar.workspaces: ignoredTags, specialWorkspaceIcons, windowIconsdashboard: mediaUpdateInterval, resourceUpdateIntervalgeneral: apps.*, battery.*, idle.*, logolauncher: actionPrefix, actions, enableDangerousActions, favouriteApps, hiddenApps, specialPrefix, useFuzzy.*, vimKeybindslock: enableFprint, enableHowdy, maxFprintTries, maxHowdyTries, triggerHowdyOnWakenexus: networkRescanIntervalnotifs: actionOnClick, defaultExpireTimeout, expire, fullscreen, fullscreenExpireTimeoutpaths: lyricsDir, wallpaperDirservices: audioIncrement, brightnessIncrement, dataUnits, defaultPlayer, gpuType, lyricsBackend, maxVolume, playerAliases, sensorUnits, smartScheme, useTwelveHourClock, visualiserBars, weatherLocation, weatherUnitsutilities.toasts: all except fullscreenutilities.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,
"showUnoccupied": true,
"showWindows": true,
"showWindowsOnSpecialWorkspaces": true,
"maxWindowIcons": 5,
"activeTrail": false,
"displayType": "shapes",
"label": " ",
"occupiedLabel": "",
"activeLabel": "",
"capitalisation": "preserve",
"specialWorkspaceIcons": [
{
"name": "steam",
"icon": "sports_esports"
}
],
"ignoredTags": [
"hide_in_bar",
"xwl_popup"
],
"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,
][discord]
Caelestia shell is an animated desktop shell for Linux: the visual layer of your desktop — bar, launcher, dashboard, notifications — rendered with Quickshell on top of the Hyprland window manager under Wayland.