caelestia
This is the main repo of the Caelestia dotfiles and contains user configs for various apps.
Important
The legacy install.fish script in this repo has been removed in favour
of the CLI's install command.
If you have an existing installation with the legacy script, please update the CLI and run the install command to complete the migration.
Important
We have switched to using Lua for the Hyprland config!
For everyone with a custom ~/.config/caelestia/hypr-user.conf
or ~/.config/caelestia/hypr-vars.conf, please convert it to Lua
either manually or using one of the available converters online.
For more information on using these files, see the Configuring section.
Installation (Arch Linux)
Install the CLI from the AUR, then run caelestia install.
For example:
paru -S caelestia-cli caelestia install
Manual installation
Clone this repo, then go through the manifest and install all packages from the components that you want to enable, then copy all the entries from those components.
e.g. for the hyprland component:
git clone https://github.com/caelestia-dots/caelestia.git cd caelestia sudo pacman -S --needed hyprland xdg-desktop-portal-hyprland xdg-desktop-portal-gtk ttf-jetbrains-mono-nerd mkdir -p $XDG_CONFIG_HOME/hypr cp -r hypr/. $XDG_CONFIG_HOME/hypr/
Updating
Use caelestia update to perform a full system update and update the dots.
Usage
Note
These dots do not contain a login manager (for now), so you must install a
login manager yourself unless you want to log in from a TTY. I recommend
greetd with
tuigreet; however, you can use
any login manager you want.
Configuring
Caution
You should never modify any files inside ~/.config/hypr/, as this will cause conflicts during updates to the dots.
Any personal changes should be made in ~/.config/caelestia/hypr-user.lua or hypr-vars.lua, as
the installation/update workflows never modify these files. Writing your own changes to files in ~/.config/hypr/
will prevent new updates from being applied, and you will have to reconcile conflicts every time you update manually.
hypr-vars.lua
Most default Hyprland values can be modified by overriding variables in ~/.config/caelestia/hypr-vars.lua. You can use this file to set
default apps, keybinds, mouse cursor, window decorations, and much more.
Use the variables.lua file as a reference for all available variables and their default values.
Example usage for hypr-vars.lua:
return { -- Changing default apps: browser = "zen-browser", -- Change default browser to Zen editor = "code", -- Change default editor to Code -- Changing window/decoration properties: blurEnabled = false, -- Disable window blur windowBorderSize = 3, -- Increase window border size (default: 1) -- Changing keybinds: kbTerminal = "SUPER + Return", -- Change the keybind for opening terminal }
hypr-user.lua
You can put any custom Hyprland configuration in ~/.config/caelestia/hypr-user.lua. This file is loaded at the end of the Hyprland
loading sequence. This allows you to customise the behavior of Hyprland outside of the premade configs, including monitor layout, additional
keybinds, and window rules. It is preferable to use hypr-vars.lua for changes to options that the dots already manage
(e.g. keybinds, window borders, etc.). Still, for configuration that isn't covered by dots or needs to be managed outside variables,
any changes should be made in hypr-user.lua.
You can read more about configuring Hyprland on their wiki.
Additional configuration
Caelestia is a multifaceted ecosystem comprising the dotfiles (this repo), the shell, and the CLI.
The shell’s configuration is managed by ~/.config/caelestia/shell.json, which modifies the shell’s behavior.
The CLI config file (~/.config/caelestia/cli.json) lets you adjust the CLI’s theming and handling of special workspaces.
You can find more information on configuring the shell and the CLI in their respective repos.
Default keybinds
Tip
All keybinds can be customised by overriding their corresponding variables in hypr-vars.lua (excluding the shell restart/kill binds).
See Configuring for more information.
Launcher
| Keybind | Action |
|---|---|
Super (press & release) |
Open launcher |
Workspaces
| Keybind | Action |
|---|---|
Super + 1~9, 0 |
Go to workspace 1~10 |
Super + Alt + 1~9, 0 |
Move window to workspace 1~10 |
Ctrl + Super + 1~9, 0 |
Go to workspace group (×10) |
Ctrl + Super + Alt + 1~9, 0 |
Move window to workspace group |
Super + Alt + S, Ctrl + Super + Shift + Up |
Move window to special workspace |
Ctrl + Super + Shift + Down |
Move window out of special workspace |
Super + Alt + Scroll Down, Super + Alt + Page_Down, Ctrl + Super + Shift + Right |
Move window to next workspace |
Super + Alt + Scroll Up, Super + Alt + Page_Up, Ctrl + Super + Shift + Left |
Move window to previous workspace |
Super + Scroll Down, Ctrl + Super + Right, Super + Page_Down |
Go to next workspace |
Super + Scroll Up, Ctrl + Super + Left, Super + Page_Up |
Go to previous workspace |
Ctrl + Super + Scroll Down |
Go to next workspace group |
Ctrl + Super + Scroll Up |
Go to previous workspace group |
Window groups
| Keybind | Action |
|---|---|
Alt + Tab |
Go to next window in group |
Shift + Alt + Tab |
Go to previous window in group |
Ctrl + Alt + Tab |
Go to next group |
Ctrl + Shift + Alt + Tab |
Go to previous group |
Super + U |
Move window out of group |
Super + Comma |
Toggle group |
Super + Shift + Comma |
Lock active group |
Window actions
| Keybind | Action |
|---|---|
Super + Minus, Super + Alt + Left |
Move window split left |
Super + Equal, Super + Alt + Right |
Move window split right |
Super + Shift + Minus, Super + Alt + Up |
Move window split up |
Super + Shift + Equal, Super + Alt + Down |
Move window split down |
Super + Left/Right/Up/Down |
Focus window in direction |
Super + Shift + Left/Right/Up/Down |
Move window in direction |
Super + LMB, Super + Z + LMB |
Move window (drag) |
Super + RMB, Super + X + LMB |
Resize window (drag) |
Ctrl + Super + Backslash |
Center window |
Ctrl + Super + Alt + Backslash |
Resize window to 55×70% of screen and center |
Super + Alt + Backslash |
Enable picture-in-picture mode for window |
Super + P |
Toggle pinned mode for window |
Super + F |
Toggle fullscreen mode for window |
Super + Alt + F |
Toggle maximised mode for window |
Super + Alt + Space |
Toggle floating mode for window |
Super + Q |
Close window |
Special workspace toggles
| Keybind | Action |
|---|---|
Super + S |
Toggle special workspace |
Ctrl + Shift + Escape |
Toggle system monitor workspace |
Super + M |
Toggle music workspace |
Super + D |
Toggle communication workspace |
Super + R |
Toggle todo workspace |
Applications
| Keybind | Action |
|---|---|
Super + T |
Terminal (default: foot) |
Super + W |
Browser (default: firefox) |
Super + C |
Editor (default: codium) |
Super + E |
File explorer (default: thunar) |
Ctrl + Alt + V |
Audio settings (default: pwvucontrol) |
Utilities
| Keybind | Action |
|---|---|
Print |
Screenshot |
Super + Shift + S |
Screenshot (freeze) |
Super + Shift + Alt + S |
Screenshot (region) |
Ctrl + Alt + R |
Record fullscreen |
Super + Alt + R |
Record with sound |
Super + Shift + Alt + R |
Record region |
Super + Shift + C |
Colour picker |
Media
| Keybind | Action |
|---|---|
Ctrl + Super + Space |
Play/pause |
Ctrl + Super + Equal |
Next track |
Ctrl + Super + Minus |
Previous track |
Ctrl + Super + Backspace |
Stop playback |
Super + Shift + M |
Mute volume |
Miscellaneous
| Keybind | Action |
|---|---|
Ctrl + Alt + Delete |
Open shell session menu |
Super + N |
Toggle shell sidebar |
Ctrl + Alt + C |
Clear shell notifications |
Super + K |
Show all shell panels |
Super + L |
Lock screen |
Super + Alt + L |
Restore shell lockscreen |
Super + Shift + L |
Run sleep command |
Clipboard / Emoji
| Keybind | Action |
|---|---|
Super + V |
Open clipboard history |
Super + Alt + V |
Open clipboard history (delete mode) |
Ctrl + Shift + Alt + V |
Paste latest clipboard entry |
Super + Period |
Open emoji picker |
Shell
| Keybind | Action |
|---|---|
Ctrl + Super + Alt + R |
Restart shell |
Ctrl + Super + Shift + R |
Kill shell |