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-cliquickshell-git- this has to be the git version, not the latest tagged versionglibcgcc-libsddcutilbrightnessctllibcavanetworkmanagerlm_sensorsaubiolibpipewirelibqalculatepower-profiles-daemonttf-material-symbols-variablettf-rubik-vfttf-cascadia-code-nerdqt6-baseqt6-declarativeqt6-imageformatsqt6-m3shapes-gitswappyfishbash
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, 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,iconSubsbar.workspaces:ignoredTags,specialWorkspaceIcons,windowIcons,workspaceIconsdashboard: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,clockFormat,dataUnits,defaultPlayer,gpuType,lyricsBackend,maxVolume,playerAliases,sensorUnits,smartScheme,visualiserBars,weatherLocation,weatherUnitsutilities:toasts.*,vpn.*
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,
"perMonitor": true,
"showWindows": true,
"showWindowsOnSpecialWorkspaces": true,
"maxWindowIcons": 5,
"activeTrail": false,
"displayType": "shapes",
"specialDisplayType": "icons",
"label": " ",
"occupiedLabel": "",
"activeLabel": "",
"capitalisation": "preserve",
"workspaceIcons": [],
"specialWorkspaceIcons": [
{
"name": "special",
"icon": "star"
},
{
"name": "communication",
"icon": "forum"
},
{
"name": "music",
"icon": "music_cast"
},
{
"name": "todo",
"icon": "checklist"
},
{
"name": "sysmon",
"icon": "monitor_heart"
}
],
"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,
"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,
"enableSessionControls": true
},
"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": "",
"weatherUnits": "Auto",
"sensorUnits": "Celsius",
"dataUnits": "Binary",
"clockFormat": "Auto",
"gpuType": "Auto",
"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):