cnix/modules/home/services/quickshell/shell

caelestia-shell

https://github.com/user-attachments/assets/0840f496-575c-4ca6-83a8-87bb01a85c5f

Components

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

Installation

Note

This repo is for the desktop shell of the caelestia dots. If you want installation instructions for the entire dots, head to the main repo instead.

Package manager

Note

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-git. You can install it with an AUR helper like yay or manually downloading the PKGBUILD and running makepkg -si.

Manual installation

Dependencies:

• caelestia-cli
• quickshell-git - this has to be the git version, not the latest tagged version
• ddcutil
• brightnessctl
• app2unit
• cava
• networkmanager
• lm-sensors
• fish
• aubio
• libpipewire
• glibc
• qt6-declarative
• gcc-libs
• material-symbols
• jetbrains-mono-nerd
• grim
• swappy
• libqalculate

To install the shell manually, install all dependencies and clone this repo to $XDG_CONFIG_HOME/quickshell/caelestia. Then compile the beat detector and install it to /usr/lib/caelestia/beat_detector.

cd $XDG_CONFIG_HOME/quickshell
git clone https://github.com/caelestia-dots/shell.git caelestia
g++ -std=c++17 -Wall -Wextra -I/usr/include/pipewire-0.3 -I/usr/include/spa-0.2 -I/usr/include/aubio -o beat_detector caelestia/assets/beat_detector.cpp -lpipewire-0.3 -laubio
sudo mv beat_detector /usr/lib/caelestia/beat_detector

Usage

The shell can be started via the caelestia shell -d command or qs -c caelestia. If the entire caelestia dots are installed, the shell will be autostarted on login via an exec-once in the hyprland config.

Shortcuts/IPC

All keybinds are accessible via Hyprland global shortcuts. If using the entire caelestia dots, the keybinds are already configured for you. Otherwise, this file contains an example on how to use global shortcuts.

All IPC commands can be accessed via caelestia shell .... For example

caelestia shell mpris getActive trackTitle

The list of IPC commands can be shown via caelestia shell -s:

$ caelestia shell -s
target drawers
  function toggle(drawer: string): void
  function list(): string
target notifs
  function clear(): void
target lock
  function lock(): void
  function unlock(): void
  function isLocked(): bool
target mpris
  function playPause(): void
  function getActive(prop: string): string
  function next(): void
  function stop(): void
  function play(): void
  function list(): string
  function pause(): void
  function previous(): void
target picker
  function openFreeze(): void
  function open(): void
target wallpaper
  function set(path: string): void
  function get(): string
  function list(): string

PFP/Wallpapers

The profile picture for the dashboard is read from the file ~/.face, so to set it you can copy your image to there or set it via the dashboard.

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

To set the wallpaper, you can use the command caelestia wallpaper. Use caelestia wallpaper -h for more info about the command.

Updating

If installed via the AUR package, simply update your system (e.g. using yay).

If installed manually, you can update by running git pull in $XDG_CONFIG_HOME/quickshell/caelestia.

cd $XDG_CONFIG_HOME/quickshell/caelestia
git pull

Configuring

All configuration options are in ~/.config/caelestia/shell.json.

Example configuration

{
    "bar": {
        "workspaces": {
            "activeIndicator": true,
            "activeLabel": "󰮯 ",
            "activeTrail": false,
            "label": "  ",
            "occupiedBg": false,
            "occupiedLabel": "󰮯 ",
            "rounded": true,
            "showWindows": true,
            "shown": 5
        }
    },
    "border": {
        "rounding": 25,
        "thickness": 10
    },
    "dashboard": {
        "mediaUpdateInterval": 500,
        "visualiserBars": 45,
        "weatherLocation": "10,10"
    },
    "launcher": {
        "actionPrefix": ">",
        "enableDangerousActions": false,
        "maxShown": 8,
        "maxWallpapers": 9
    },
    "lock": {
        "maxNotifs": 5
    },
    "notifs": {
        "actionOnClick": false,
        "clearThreshold": 0.3,
        "defaultExpireTimeout": 5000,
        "expandThreshold": 20,
        "expire": false
    },
    "osd": {
        "hideDelay": 2000
    },
    "paths": {
        "mediaGif": "root:/assets/bongocat.gif",
        "sessionGif": "root:/assets/kurukuru.gif",
        "wallpaperDir": "~/Pictures/Wallpapers"
    },
    "session": {
        "dragThreshold": 30
    }
}

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 📈