Shell

<h1 align=center>caelestia-shell</h1> <div align=center>

</div>

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.

Arch linux

[!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. You can install it with an AUR helper like yay or 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

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";
    };
  };
}

The package is available as caelestia-shell.packages.<system>.default, which can be added to your environment.systemPackages, users.users.<username>.packages, home.packages if using home-manager, or a devshell. The shell can then be run via caelestia-shell.

[!TIP] The default package does not have the CLI enabled by default, which is required for full funcionality. To enable the CLI, use the with-cli package.

For home-manager, you can also use the Caelestia's home manager module (explained in configuring) that installs and configures the shell and the CLI.

Manual installation

Dependencies:

• caelestia-cli
• quickshell-git - this has to be the git version, not the latest tagged version
• ddcutil
• brightnessctl
• app2unit
• libcava
• networkmanager
• lm-sensors
• fish
• aubio
• libpipewire
• glibc
• qt6-declarative
• gcc-libs
• material-symbols
• caskaydia-cove-nerd
• swappy
• libqalculate
• bash
• qt6-base
• qt6-declarative

Build dependencies:

• cmake
• ninja

To install the shell manually, install all dependencies and clone this repo to $XDG_CONFIG_HOME/quickshell/caelestia. Then simply 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 (the beat detector), QML plugin and Quickshell config directories respectively. If changing the library directory, remember to set the CAELESTIA_LIB_DIR environment variable to the custom directory when launching the shell.

e.g. 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=~/.config/quickshell/caelestia
cmake --build build
sudo cmake --install build
sudo chown -R $USER ~/.config/quickshell/caelestia

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 should be put in ~/.config/caelestia/shell.json. This file is not created by default, you must create it manually.

Example configuration

[!NOTE] The example configuration only includes recommended configuration options. For more advanced customisation such as modifying the size of individual items or changing constants in the code, there are some other options which can be found in the source files in the config directory.

<details><summary>Example</summary>

{
    "appearance": {
        "mediaGifSpeedAdjustment": 300,
        "sessionGifSpeed": 0.7,
        "anim": {
            "durations": {
                "scale": 1
            }
        },
        "font": {
            "family": {
                "clock": "Rubik",
                "material": "Material Symbols Rounded",
                "mono": "CaskaydiaCove NF",
                "sans": "Rubik"
            },
            "size": {
                "scale": 1
            }
        },
        "padding": {
            "scale": 1
        },
        "rounding": {
            "scale": 1
        },
        "spacing": {
            "scale": 1
        },
        "transparency": {
            "enabled": false,
            "base": 0.85,
            "layers": 0.4
        }
    },
    "general": {
        "logo": "caelestia",
        "apps": {
            "terminal": ["foot"],
            "audio": ["pavucontrol"],
            "playback": ["mpv"],
            "explorer": ["thunar"]
        },
        "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!!"