1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
|
<h1 align=center>caelestia-shell</h1>
<div align=center>
[](https://ko-fi.com/soramane)
</div>
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.
### 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](#manual-installation).
The shell is available from the AUR as `caelestia-shell-git`. You can install it with an AUR helper
like [`yay`](https://github.com/Jguer/yay) or manually downloading the PKGBUILD and running `makepkg -si`.
### 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)
- [`cava`](https://github.com/karlstav/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)
- [`jetbrains-mono-nerd`](https://www.nerdfonts.com/font-downloads)
- [`grim`](https://gitlab.freedesktop.org/emersion/grim)
- [`swappy`](https://github.com/jtheoof/swappy)
- [`libqalculate`](https://github.com/Qalculate/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`.
```sh
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
```
> [!TIP]
> The beat detector can actually be installed anywhere. However, if it is not installed to the default
> location of `/usr/lib/caelestia/beat_detector`, you must set the environment variable `CAELESTIA_BD_PATH`
> to wherever you have installed the 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](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 are in `~/.config/caelestia/shell.json`.
<details><summary>Example configuration</summary>
```json
{
"background": {
"enabled": true
},
"bar": {
"dragThreshold": 20,
"persistent": true,
"showOnHover": true,
"status": {
"showAudio": false,
"showBattery": true,
"showBluetooth": true,
"showKbLayout": false,
"showNetwork": true
},
"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
},
"launcher": {
"actionPrefix": ">",
"dragThreshold": 50,
"vimKeybinds": false,
"enableDangerousActions": false,
"maxShown": 8,
"maxWallpapers": 9,
"useFuzzy": {
"apps": false,
"actions": false,
"schemes": false,
"variants": false,
"wallpapers": false
}
},
"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"
},
"services": {
"weatherLocation": "10,10",
"useFahrenheit": false
},
"session": {
"dragThreshold": 30,
"vimKeybinds": false,
"commands": {
"logout": ["loginctl", "terminate-user", ""],
"shutdown": ["systemctl", "poweroff"],
"hibernate": ["systemctl", "hibernate"],
"reboot": ["systemctl", "reboot"]
}
}
}
```
</details>
## 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 📈
<a href="https://www.star-history.com/#caelestia-dots/shell&Date">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=caelestia-dots/shell&type=Date&theme=dark" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=caelestia-dots/shell&type=Date" />
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=caelestia-dots/shell&type=Date" />
</picture>
</a>
|
