{"id":28809892,"url":"https://github.com/caelestia-dots/cli","last_synced_at":"2026-05-07T11:35:04.805Z","repository":{"id":272873451,"uuid":"918024388","full_name":"caelestia-dots/cli","owner":"caelestia-dots","description":"The main control script for the Caelestia dotfiles","archived":false,"fork":false,"pushed_at":"2026-04-29T03:43:15.000Z","size":785,"stargazers_count":140,"open_issues_count":29,"forks_count":95,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-04-29T05:24:34.490Z","etag":null,"topics":["caelestia","dotfiles","hyprland","linux","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caelestia-dots.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"soramanew","patreon":null,"open_collective":null,"ko_fi":"soramane","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":"soramane","thanks_dev":null,"custom":null}},"created_at":"2025-01-17T05:18:35.000Z","updated_at":"2026-04-29T03:43:20.000Z","dependencies_parsed_at":"2025-12-20T07:00:18.268Z","dependency_job_id":null,"html_url":"https://github.com/caelestia-dots/cli","commit_stats":null,"previous_names":["soramanew/caelestia-scripts","caelestia-dots/scripts","caelestia-dots/cli"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/caelestia-dots/cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caelestia-dots%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caelestia-dots%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caelestia-dots%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caelestia-dots%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caelestia-dots","download_url":"https://codeload.github.com/caelestia-dots/cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caelestia-dots%2Fcli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32735318,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-07T02:14:30.463Z","status":"ssl_error","status_checked_at":"2026-05-07T02:14:29.405Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["caelestia","dotfiles","hyprland","linux","python"],"created_at":"2025-06-18T13:08:41.975Z","updated_at":"2026-05-07T11:35:04.769Z","avatar_url":"https://github.com/caelestia-dots.png","language":"Python","funding_links":["https://github.com/sponsors/soramanew","https://ko-fi.com/soramane","https://buymeacoffee.com/soramane"],"categories":[],"sub_categories":[],"readme":"# caelestia-cli\n\nThe main control script for the Caelestia dotfiles.\n\n\u003cdetails\u003e\u003csummary id=\"dependencies\"\u003eExternal dependencies\u003c/summary\u003e\n\n- [`libnotfy`](https://gitlab.gnome.org/GNOME/libnotify) - sending notifications\n- [`swappy`](https://github.com/jtheoof/swappy) - screenshot editor\n- [`grim`](https://gitlab.freedesktop.org/emersion/grim) - taking screenshots\n- [`dart-sass`](https://github.com/sass/dart-sass) - discord theming\n- [`app2unit`](https://github.com/Vladimir-csp/app2unit) - launching apps\n- [`wl-clipboard`](https://github.com/bugaevc/wl-clipboard) - copying to clipboard\n- [`slurp`](https://github.com/emersion/slurp) - selecting an area\n- [`gpu-screen-recorder`](https://git.dec05eba.com/gpu-screen-recorder/about) - screen recording\n- `glib2` - closing notifications\n- [`cliphist`](https://github.com/sentriz/cliphist) - clipboard history\n- [`fuzzel`](https://codeberg.org/dnkl/fuzzel) - clipboard history/emoji picker\n\n\u003c/details\u003e\n\n## Installation\n\n### Arch linux\n\nThe CLI is available from the AUR as `caelestia-cli`. You can install it with an AUR helper\nlike [`yay`](https://github.com/Jguer/yay) or manually downloading the PKGBUILD and running `makepkg -si`.\n\nA package following the latest commit also exists as `caelestia-cli-git`. This is bleeding edge\nand likely to be unstable/have bugs. Regular users are recommended to use the stable package\n(`caelestia-cli`).\n\n### Nix\n\nYou can run the CLI directly via `nix run`:\n\n```sh\nnix run github:caelestia-dots/cli\n```\n\nOr add it to your system configuration:\n\n```nix\n{\n  inputs = {\n    nixpkgs.url = \"github:nixos/nixpkgs/nixos-unstable\";\n\n    caelestia-cli = {\n      url = \"github:caelestia-dots/cli\";\n      inputs.nixpkgs.follows = \"nixpkgs\";\n    };\n  };\n}\n```\n\nThe package is available as `caelestia-cli.packages.\u003csystem\u003e.default`, which can be added to your\n`environment.systemPackages`, `users.users.\u003cusername\u003e.packages`, `home.packages` if using home-manager,\nor a devshell. The CLI can then be used via the `caelestia` command.\n\n\u003e [!TIP]\n\u003e The default package does not have the shell enabled by default, which is required for full functionality.\n\u003e To enable the shell, use the `with-shell` package. This is the recommended installation method, as\n\u003e the CLI exposes the shell via the `shell` subcommand, meaning there is no need for the shell package\n\u003e to be exposed.\n\nFor home-manager, you can also use the Caelestia's home manager module (explained in\n[configuring](https://github.com/caelestia-dots/shell?tab=readme-ov-file#home-manager-module)) that\ninstalls and configures the shell and the CLI.\n\n### Manual installation\n\nInstall all [dependencies](#dependencies), then install\n[`python-build`](https://github.com/pypa/build),\n[`python-installer`](https://github.com/pypa/installer),\n[`python-hatch`](https://github.com/pypa/hatch) and\n[`python-hatch-vcs`](https://github.com/ofek/hatch-vcs).\n\ne.g. via an AUR helper (yay)\n\n```sh\nyay -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\n```\n\nNow, clone the repo, `cd` into it, build the wheel via `python -m build --wheel`\nand install it via `python -m installer dist/*.whl`. Then, to install the `fish`\ncompletions, copy the `completions/caelestia.fish` file to\n`/usr/share/fish/vendor_completions.d/caelestia.fish`.\n\n```sh\ngit clone https://github.com/caelestia-dots/cli.git\ncd cli\npython -m build --wheel\nsudo python -m installer dist/*.whl\nsudo cp completions/caelestia.fish /usr/share/fish/vendor_completions.d/caelestia.fish\n```\n\n### Additional steps\n\n#### Auto folder colour theming\n\nFor automatic Papirus folder icon colour syncing, you must have [`papirus-folders`](https://github.com/PapirusDevelopmentTeam/papirus-folders)\ninstalled, and `papirus-folders` must to be able to run with `sudo` without a password prompt.\n\nYou can allow this by creating a sudoers file:\n\n```sh\necho \"$USER ALL=(ALL) NOPASSWD: $(which papirus-folders)\" | sudo tee /etc/sudoers.d/papirus-folders\nsudo chmod 440 /etc/sudoers.d/papirus-folders\n```\n\n#### Chromium-based browser theming\n\nFor live Chromium-based browser theming, the CLI must be allowed to create certain directories in `/etc`\nand write to them via `sudo` without a password prompt.\n\nYou can allow this by creating a sudoers file:\n\n```fish\n# Fish shell\nfor dir in /etc/chromium/policies/managed /etc/brave/policies/managed /etc/opt/chrome/policies/managed\n    echo \"$USER ALL=(ALL) NOPASSWD: $(which mkdir) -p $dir\" | sudo tee -a /etc/sudoers.d/caelestia-chromium\n    echo \"$USER ALL=(ALL) NOPASSWD: $(which tee) $dir/caelestia.json\" | sudo tee -a /etc/sudoers.d/caelestia-chromium\nend\nsudo chmod 440 /etc/sudoers.d/caelestia-chromium\n```\n\n```sh\n# Bash/other shells\nfor dir in /etc/chromium/policies/managed /etc/brave/policies/managed /etc/opt/chrome/policies/managed; do\n    echo \"$USER ALL=(ALL) NOPASSWD: $(which mkdir) -p $dir\" | sudo tee -a /etc/sudoers.d/caelestia-chromium\n    echo \"$USER ALL=(ALL) NOPASSWD: $(which tee) $dir/caelestia.json\" | sudo tee -a /etc/sudoers.d/caelestia-chromium\ndone\nsudo chmod 440 /etc/sudoers.d/caelestia-chromium\n```\n\n## Usage\n\nAll subcommands/options can be explored via the help flag.\n\n```\n$ caelestia -h\nusage: caelestia [-h] [-v] COMMAND ...\n\nMain control script for the Caelestia dotfiles\n\noptions:\n  -h, --help     show this help message and exit\n  -v, --version  print the current version\n\nsubcommands:\n  valid subcommands\n\n  COMMAND        the subcommand to run\n    shell        start or message the shell\n    toggle       toggle a special workspace\n    scheme       manage the colour scheme\n    screenshot   take a screenshot\n    record       start a screen recording\n    clipboard    open clipboard history\n    emoji        emoji/glyph utilities\n    wallpaper    manage the wallpaper\n    resizer      window resizer daemon\n```\n\n### User templates\n\nCustom user templates can be defined in `~/.config/caelestia/templates/`.\n\n#### Template syntax\n\n`{{ \u003ccolor\u003e.\u003cformat\u003e }}`\n\n- `\u003ccolor\u003e` is a theme color role derived from the Material You color system (e.g. `primary`, `secondary`, `background`)\n- `\u003cformat\u003e` is the output format: `hex` or `rgb`\n\n#### Examples\n\n- `{{ primary.hex }}` outputs `3f4ba2`\n- `{{ primary.rgb }}` outputs `rgb(193, 132, 207)`\n\nOutput files are written to `~/.local/state/caelestia/theme/`. You can symlink them to your desired locations.\n\n## Configuring\n\nAll configuration options are in `~/.config/caelestia/cli.json`.\n\n\u003cdetails\u003e\u003csummary\u003eExample configuration\u003c/summary\u003e\n\n```json\n{\n    \"record\": {\n        \"extraArgs\": []\n    },\n    \"wallpaper\": {\n        \"postHook\": \"echo $WALLPAPER_PATH\"\n    },\n    \"theme\": {\n        \"enableTerm\": true,\n        \"enableHypr\": true,\n        \"enableDiscord\": true,\n        \"enableSpicetify\": true,\n        \"enableFuzzel\": true,\n        \"enableBtop\": true,\n        \"enableGtk\": true,\n        \"enableQt\": true\n    },\n    \"toggles\": {\n        \"communication\": {\n            \"discord\": {\n                \"enable\": true,\n                \"match\": [{ \"class\": \"discord\" }],\n                \"command\": [\"discord\"],\n                \"move\": true\n            },\n            \"whatsapp\": {\n                \"enable\": true,\n                \"match\": [{ \"class\": \"whatsapp\" }],\n                \"move\": true\n            }\n        },\n        \"music\": {\n            \"spotify\": {\n                \"enable\": true,\n                \"match\": [{ \"class\": \"Spotify\" }, { \"initialTitle\": \"Spotify\" }, { \"initialTitle\": \"Spotify Free\" }],\n                \"command\": [\"spicetify\", \"watch\", \"-s\"],\n                \"move\": true\n            },\n            \"feishin\": {\n                \"enable\": true,\n                \"match\": [{ \"class\": \"feishin\" }],\n                \"move\": true\n            }\n        },\n        \"sysmon\": {\n            \"btop\": {\n                \"enable\": true,\n                \"match\": [{ \"class\": \"btop\", \"title\": \"btop\", \"workspace\": { \"name\": \"special:sysmon\" } }],\n                \"command\": [\"foot\", \"-a\", \"btop\", \"-T\", \"btop\", \"fish\", \"-C\", \"exec btop\"]\n            }\n        },\n        \"todo\": {\n            \"todoist\": {\n                \"enable\": true,\n                \"match\": [{ \"class\": \"Todoist\" }],\n                \"command\": [\"todoist\"],\n                \"move\": true\n            }\n        }\n    }\n}\n```\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaelestia-dots%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaelestia-dots%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaelestia-dots%2Fcli/lists"}