https://github.com/user-attachments/assets/0840f496-575c-4ca6-83a8-87bb01a85c5f
## Components
- Widgets: [`Quickshell`](https://quickshell.outfoxxed.me)
- Window manager: [`Hyprland`](https://hyprland.org)
- Dots: [`caelestia`](https://github.com/caelestia-dots)
## 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](https://github.com/caelestia-dots/caelestia) 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](#manual-installation).
The shell is available from the AUR as `caelestia-shell`. You can install it with an AUR helper
like [`yay`](https://github.com/Jguer/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`:
```sh
nix run github:caelestia-dots/shell
```
Or add it to your system configuration:
```nix
{
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..default`, which can be added to your
`environment.systemPackages`, `users.users..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](https://github.com/caelestia-dots/shell?tab=readme-ov-file#home-manager-module)) that installs and configures the shell and the CLI.
### Manual installation
Dependencies:
- [`caelestia-cli`](https://github.com/caelestia-dots/cli)
- [`quickshell-git`](https://quickshell.outfoxxed.me) - this has to be the git version, not the latest tagged version
- [`ddcutil`](https://github.com/rockowitz/ddcutil)
- [`brightnessctl`](https://github.com/Hummer12007/brightnessctl)
- [`app2unit`](https://github.com/Vladimir-csp/app2unit)
- [`libcava`](https://github.com/LukashonakV/cava)
- [`networkmanager`](https://networkmanager.dev)
- [`lm-sensors`](https://github.com/lm-sensors/lm-sensors)
- [`fish`](https://github.com/fish-shell/fish-shell)
- [`aubio`](https://github.com/aubio/aubio)
- [`libpipewire`](https://pipewire.org)
- `glibc`
- `qt6-declarative`
- `gcc-libs`
- [`material-symbols`](https://fonts.google.com/icons)
- [`caskaydia-cove-nerd`](https://www.nerdfonts.com/font-downloads)
- [`swappy`](https://github.com/jtheoof/swappy)
- [`libqalculate`](https://github.com/Qalculate/libqalculate)
- [`bash`](https://www.gnu.org/software/bash)
- `qt6-base`
- `qt6-declarative`
Build dependencies:
- [`cmake`](https://cmake.org)
- [`ninja`](https://github.com/ninja-build/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`.
```sh
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:
>
> ```sh
> 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](https://wiki.hyprland.org/Configuring/Binds/#dbus-global-shortcuts).
If using the entire caelestia dots, the keybinds are already configured for you.
Otherwise, [this file](https://github.com/caelestia-dots/caelestia/blob/main/hypr/hyprland/keybinds.conf#L1-L39)
contains an example on how to use global shortcuts.
All IPC commands can be accessed via `caelestia shell ...`. For example
```sh
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`.
```sh
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.
Example
```json
{
"appearance": {
"anim": {
"durations": {
"scale": 1
}
},
"font": {
"family": {
"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": {
"apps": {
"terminal": ["foot"],
"audio": ["pavucontrol"]
},
"idle": {
"inhibitWhenAudio": true,
"lockTimeout": 180,
"dpmsTimeout": 300,
"sleepTimeout": 600
}
},
"background": {
"desktopClock": {
"enabled": false
},
"enabled": true,
"visualiser": {
"enabled": false,
"autoHide": true,
"rounding": 1,
"spacing": 1
}
},
"bar": {
"clock": {
"showIcon": true
},
"dragThreshold": 20,
"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
}
],
"persistent": true,
"scrollActions": {
"brightness": true,
"workspaces": true,
"volume": true
},
"showOnHover": true,
"status": {
"showAudio": false,
"showBattery": true,
"showBluetooth": true,
"showKbLayout": false,
"showMicrophone": false,
"showNetwork": true,
"showLockStatus": true
},
"tray": {
"background": false,
"iconSubs": [],
"recolour": false
},
"workspaces": {
"activeIndicator": true,
"activeLabel": "",
"activeTrail": false,
"label": " ",
"occupiedBg": false,
"occupiedLabel": "",
"perMonitorWorkspaces": true,
"showWindows": true,
"shown": 5
}
},
"border": {
"rounding": 25,
"thickness": 10
},
"dashboard": {
"enabled": true,
"dragThreshold": 50,
"mediaUpdateInterval": 500,
"showOnHover": true
},
"launcher": {
"actionPrefix": ">",
"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": "Transparency",
"icon": "opacity",
"description": "Change shell transparency",
"command": ["autocomplete", "transparency"],
"enabled": false,
"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": ["systemctl", "poweroff"],
"enabled": true,
"dangerous": true
},
{
"name": "Reboot",
"icon": "cached",
"description": "Reboot the system",
"command": ["systemctl", "reboot"],
"enabled": true,
"dangerous": true
},
{
"name": "Logout",
"icon": "exit_to_app",
"description": "Log out of the current session",
"command": ["loginctl", "terminate-user", ""],
"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": ["systemctl", "suspend-then-hibernate"],
"enabled": true,
"dangerous": false
}
],
"dragThreshold": 50,
"vimKeybinds": false,
"enableDangerousActions": false,
"maxShown": 7,
"maxWallpapers": 9,
"specialPrefix": "@",
"useFuzzy": {
"apps": false,
"actions": false,
"schemes": false,
"variants": false,
"wallpapers": false
},
"showOnHover": false,
"hiddenApps": []
},
"lock": {
"recolourLogo": false
},
"notifs": {
"actionOnClick": false,
"clearThreshold": 0.3,
"defaultExpireTimeout": 5000,
"expandThreshold": 20,
"expire": false
},
"osd": {
"enabled": true,
"enableBrightness": true,
"enableMicrophone": false,
"hideDelay": 2000
},
"paths": {
"mediaGif": "root:/assets/bongocat.gif",
"sessionGif": "root:/assets/kurukuru.gif",
"wallpaperDir": "~/Pictures/Wallpapers"
},
"services": {
"audioIncrement": 0.1,
"defaultPlayer": "Spotify",
"gpuType": "",
"playerAliases": [{ "from": "com.github.th_ch.youtube_music", "to": "YT Music" }],
"weatherLocation": "",
"useFahrenheit": false,
"useTwelveHourClock": false,
"smartScheme": true,
"visualiserBars": 45
},
"session": {
"dragThreshold": 30,
"enabled": true,
"vimKeybinds": false,
"commands": {
"logout": ["loginctl", "terminate-user", ""],
"shutdown": ["systemctl", "poweroff"],
"hibernate": ["systemctl", "hibernate"],
"reboot": ["systemctl", "reboot"]
}
},
"sidebar": {
"dragThreshold": 80,
"enabled": true
}.
"utilities": {
"enabled": true
}
}
```
### Home Manager Module
For NixOS users, a home manager module is also available.
home.nix
```nix
programs.caelestia = {
enable = true;
systemd = {
enable = false; # if you prefer starting from your compositor
target = "graphical-session.target";
environment = [];
};
settings = {
bar.status = {
showBattery = false;
};
paths.wallpaperDir = "~/Images";
};
cli = {
enable = true; # Also add caelestia-cli to path
settings = {
theme.enableGtk = false;
};
};
};
```
The module automatically adds Caelestia shell to the path with **full functionality**. The CLI is not required, however you have the option to enable and configure it.
## FAQ
### My screen is flickering, help pls!
Try disabling VRR in the hyprland config. You can do this by adding the following to `~/.config/caelestia/hypr-user.conf`:
```conf
misc {
vrr = 0
}
```
### I want to make my own changes to the hyprland config!
You can add your custom hyprland configs to `~/.config/caelestia/hypr-user.conf`.
### I want to make my own changes to other stuff!
See the [manual installation](https://github.com/caelestia-dots/shell?tab=readme-ov-file#manual-installation) section
for the corresponding repo.
### I want to disable XXX feature!
Please read the [configuring](https://github.com/caelestia-dots/shell?tab=readme-ov-file#configuring) section in the readme.
If there is no corresponding option, make feature request.
### How do I make my colour scheme change with my wallpaper?
Set a wallpaper via the launcher or `caelestia wallpaper` and set the scheme to the dynamic scheme via the launcher
or `caelestia scheme set`. e.g.
```sh
caelestia wallpaper -f
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](https://github.com/outfoxxed) for making Quickshell and the effort put into fixing issues
and implementing various feature requests.
Another special thanks to [@end_4](https://github.com/end-4) for his [config](https://github.com/end-4/dots-hyprland)
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](https://github.com/Axenide/Ax-Shell)
## Stonks 📈