caelestia-cli/README.md

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
• app2unit - launching apps
• 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

Optional dependencies

• papirus-folders - automatic folder icon color syncing with theme

Note

For automatic Papirus folder icon color syncing, papirus-folders needs to be able to run with sudo without a password prompt.

Recommended - Create a sudoers file:

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

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

Alternatively - Edit the main sudoers file by running sudo visudo and adding at the end:

your_username ALL=(ALL) NOPASSWD: /usr/bin/papirus-folders

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 app2unit 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

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

Configuring

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

Example configuration

{
    "record": {
        "extraArgs": []
    },
    "wallpaper": {
        "postHook": "echo $WALLPAPER_PATH"  
    },
    "theme": {
        "enableTerm": true,
        "enableHypr": true,
        "enableDiscord": true,
        "enableSpicetify": true,
        "enableFuzzel": true,
        "enableBtop": true,
        "enableGtk": true,
        "enableQt": true
    },
    "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
            }
        }
    }
}