caelestia-cli

The main control script for the Caelestia dotfiles.

External dependencies

• libnotfy - sending notifications
• swappy - screenshot editor
• grim - taking screenshots
• dart-sass - discord theming
• wl-clipboard - copying to clipboard
• slurp - selecting an area
• gpu-screen-recorder - screen recording
• glib2 - closing notifications
• cliphist - clipboard history
• fuzzel - clipboard history/emoji picker

Installation

Arch linux

The CLI is available from the AUR as caelestia-cli. 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-cli-git. This is bleeding edge and likely to be unstable/have bugs. Regular users are recommended to use the stable package (caelestia-cli).

Nix

You can run the CLI directly via nix run:

nix run github:caelestia-dots/cli

Or add it to your system configuration:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

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

The package is available as caelestia-cli.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 CLI can then be used via the caelestia command.

[!TIP] The default package does not have the shell enabled by default, which is required for full functionality. To enable the shell, use the with-shell package. This is the recommended installation method, as the CLI exposes the shell via the shell subcommand, meaning there is no need for the shell package to be exposed.

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

Install all dependencies, then install python-build, python-installer, python-hatch and python-hatch-vcs.

e.g. via an AUR helper (yay)

yay -S libnotify swappy grim dart-sass wl-clipboard slurp gpu-screen-recorder glib2 cliphist fuzzel python-build python-installer python-hatch python-hatch-vcs

Now, clone the repo, cd into it, build the wheel via python -m build --wheel and install it via python -m installer dist/*.whl. Then, to install the fish completions, copy the completions/caelestia.fish file to /usr/share/fish/vendor_completions.d/caelestia.fish.

git clone https://github.com/caelestia-dots/cli.git
cd cli
python -m build --wheel
sudo python -m installer dist/*.whl
sudo cp completions/caelestia.fish /usr/share/fish/vendor_completions.d/caelestia.fish

Additional steps

Auto folder colour theming

For automatic Papirus folder icon colour syncing, you must have papirus-folders installed, and papirus-folders must to be able to run with sudo without a password prompt.

You can allow this by creating a sudoers file:

echo "$USER ALL=(ALL) NOPASSWD: $(which papirus-folders)" | sudo tee /etc/sudoers.d/papirus-folders
sudo chmod 440 /etc/sudoers.d/papirus-folders

Chromium-based browser theming

For live Chromium-based browser theming, the CLI must be allowed to create certain directories in /etc and write to them via sudo without a password prompt.

You can allow this by creating a sudoers file:

# Fish shell
for dir in /etc/chromium/policies/managed /etc/brave/policies/managed /etc/opt/chrome/policies/managed
    echo "$USER ALL=(ALL) NOPASSWD: $(which mkdir) -p $dir" | sudo tee -a /etc/sudoers.d/caelestia-chromium
    echo "$USER ALL=(ALL) NOPASSWD: $(which tee) $dir/caelestia.json" | sudo tee -a /etc/sudoers.d/caelestia-chromium
end
sudo chmod 440 /etc/sudoers.d/caelestia-chromium

# Bash/other shells
for dir in /etc/chromium/policies/managed /etc/brave/policies/managed /etc/opt/chrome/policies/managed; do
    echo "$USER ALL=(ALL) NOPASSWD: $(which mkdir) -p $dir" | sudo tee -a /etc/sudoers.d/caelestia-chromium
    echo "$USER ALL=(ALL) NOPASSWD: $(which tee) $dir/caelestia.json" | sudo tee -a /etc/sudoers.d/caelestia-chromium
done
sudo chmod 440 /etc/sudoers.d/caelestia-chromium

Usage

All subcommands/options can be explored via the help flag.

$ caelestia -h
usage: caelestia [-h] [-v] COMMAND ...

Main control script for the Caelestia dotfiles

options:
  -h, --help     show this help message and exit
  -v, --version  print the current version

subcommands:
  valid subcommands

  COMMAND        the subcommand to run
    shell        start or message the shell
    toggle       toggle a special workspace
    scheme       manage the colour scheme
    screenshot   take a screenshot
    record       start a screen recording
    clipboard    open clipboard history
    emoji        emoji/glyph utilities
    wallpaper    manage the wallpaper
    resizer      window resizer daemon
    install      install the Caelestia dotfiles
    update       update the Caelestia dotfiles

User templates

Custom user templates can be defined in ~/.config/caelestia/templates/.

Template syntax

{{ <color>.<format> }}

• <color> is a theme color role derived from the Material You color system (e.g. primary, secondary, background)
• <format> is the output format: hex or rgb

Examples

• {{ primary.hex }} outputs 3f4ba2
• {{ primary.rgb }} outputs rgb(193, 132, 207)

Output files are written to ~/.local/state/caelestia/theme/. You can symlink them to your desired locations.

Configuring

All configuration options are in ~/.config/caelestia/cli.json.

Example configuration

{
    "record": {
        "extraArgs": []
    },
    "wallpaper": {
        "postHook": "echo $WALLPAPER_PATH $SCHEME_NAME $SCHEME_FLAVOUR $SCHEME_MODE $SCHEME_VARIANT $SCHEME_COLOURS"
    },
    "theme": {
        "enableTerm": true,
        "enableHypr": true,
        "enableDiscord": true,
        "enableSpicetify": true,
        "enablePandora": true,
        "enableFuzzel": true,
        "enableBtop": true,
        "enableNvtop": true,
        "enableHtop": true,
        "enableGtk": true,
        "enableQt": true,
        "enableWarp": true,
        "enableChromium": true,
        "enableZed": true,
        "enableCava": true,
        "iconTheme": "Papirus-Dark",
        "iconThemeLight": "Papirus-Light",
        "iconThemeDark": "Papirus-Dark",
        "postHook": "echo $SCHEME_NAME $SCHEME_FLAVOUR $SCHEME_MODE $SCHEME_VARIANT $SCHEME_COLOURS"
    },
    "toggles": {
        "communication": {
            "discord": {
                "enable": true,
                "match": [{ "class": "discord" }],
                "command": ["discord"],
                "move": true
            },
            "whatsapp": {
                "enable": true,
                "match": [{ "class": "whatsapp" }],
                "move": true
            }
        },
        "music": {
            "spotify": {
                "enable": true,
                "match": [{ "class": "Spotify" }, { "initialTitle": "Spotify" }, { "initialTitle": "Spotify Free" }],
                "command": ["spicetify", "watch", "-s"],
                "move": true
            },
            "feishin": {
                "enable": true,
                "match": [{ "class": "feishin" }],
                "move": true
            }
        },
        "sysmon": {
            "btop": {
                "enable": true,
                "match": [{ "class": "btop", "title": "btop", "workspace": { "name": "special:sysmon" } }],
                "command": ["foot", "-a", "btop", "-T", "btop", "fish", "-C", "exec btop"]
            }
        },
        "todo": {
            "todoist": {
                "enable": true,
                "match": [{ "class": "Todoist" }],
                "command": ["todoist"],
                "move": true
            }
        }
    },
    "dots": {
        "url": "https://github.com/caelestia-dots/caelestia.git",
        "branch": "main"
    }
}