Whitebow: Created the caelestia-shell page

2026-05-27T13:49:34Z

Created the caelestia-shell page

New page

[https://github.com/caelestia-dots/shell Caelestia-Shell] is a desktop shell made for Wayland, specifically for the [[Hyprland]] compositor.

== Installation<ref>https://github.com/caelestia-dots/shell#nix</ref> ==
Caelestia is currently not available from nixpkgs. The only way to install Caelestia on NixOS is through [[Flakes]].
{{File|3={
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

caelestia-shell = {
url = "github:caelestia-dots/shell";
inputs.nixpkgs.follows = "nixpkgs";
};
};

outputs = inputs@{ self, nixpkgs, ... }: {
nixosConfigurations.example = nixpkgs.lib.nixosSystem {
specialArgs = { inherit inputs; };
modules = [
# ... other modules
./caelestia.nix
];
};
};
}|name=flakes.nix|lang=nix}}
Without home-manager, the shell can be installed using the system packages :
{{File|3={ pkgs, inputs, ... }:
{
environment.systemPackages = with pkgs; [
inputs.caelestia-shell.packages.${pkgs.stdenv.hostPlatform.system}.default
];
}|name=caelestia.nix|lang=nix}}
We can also use the [[Home Manager]] module :
{{File|3={ pkgs, inputs, ... }:
{
home-manager.users.foobar = {
# import the home manager module
imports = [
inputs.caelestia.homeModules.default
];

programs.caelestia = {
enable = true;
cli.enable = true; # Also adds caelestia-cli to path
};
};
}|name=caelestia.nix|lang=nix}}

== Configuration ==
Three options are available :

# '''Non-declarative''' : edit the <code>~/.config/caelestia/shell.json</code>file, following https://github.com/caelestia-dots/shell#example-configuration
# '''Home-manager''' : you can use <code>programs.caelestia.settings</code>to set each value through Nix, following the above schema. This can cause issues with the GUI settings.
# '''Symlink''' '''copy''' : You can link the previously mentioned <code>shell.json</code> file to your nix config directory with <code>mkOutOfStoreSymlink</code> :{{File|3=xdg.configFile."caelestia"={
source = config.lib.file.mkOutOfStoreSymlink "${dotfiles}/caelestia";
force = true;
recursive = true;
};|name=caelestia.nix|lang=nix}}

== Starting the shell ==
Once the shell is installed, you should be able to launch it by executing <code>caelestia shell -d</code>.

To launch it automatically, you can add the following to your Hyprland config :
{{File|3=hl.on("hyprland.start", function()
hl.exec_cmd("caelestia shell -d")
end)|name=hyprland.lua|lang=lua}}
Or, for Hyprland < 0.55 :
{{File|3=exec-once = caelestia shell -d|name=hyprland.conf|lang=hyprlang}}

== Troubleshooting ==
In some cases, the shell can become unresponsive or take a long time to load. If <code>systemd-analyze blame | head -10</code> doesn't show any blocking programs, it can be due to a large number of notifications. In order to clear them, you can run <code>caelestia shell notifs clear</code>.

Caelestia Shell - Revision history

Whitebow: Created the caelestia-shell page