{"id":28809892,"url":"https://github.com/caelestia-dots/cli","last_synced_at":"2026-03-02T16:01:27.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":"2025-10-04T01:45:06.000Z","size":641,"stargazers_count":58,"open_issues_count":6,"forks_count":42,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-10-04T03:36:03.714Z","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":"2025-10-04T01:57:31.000Z","dependencies_parsed_at":"2025-02-16T11:21:55.429Z","dependency_job_id":"10927f46-860b-477e-a702-8146626844c4","html_url":"https://github.com/caelestia-dots/cli","commit_stats":null,"previous_names":["soramanew/caelestia-scripts","caelestia-dots/scripts","caelestia-dots/cli"],"tags_count":2,"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":279007970,"owners_count":26084369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-03-02T16:01:27.800Z","avatar_url":"https://github.com/caelestia-dots.png","language":"Python","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\u003cdetails\u003e\u003csummary id=\"optional-dependencies\"\u003eOptional dependencies\u003c/summary\u003e\n\n-   [`papirus-folders`](https://github.com/PapirusDevelopmentTeam/papirus-folders) - automatic folder icon color syncing with theme\n\n\u003e [!NOTE]\n\u003e For automatic Papirus folder icon color syncing, `papirus-folders` needs to be able to run with `sudo` without a password prompt.\n\u003e \n\u003e **Recommended** - Create a sudoers file:\n\u003e ```fish\n\u003e # Fish shell\n\u003e echo \"$USER ALL=(ALL) NOPASSWD: \"(which papirus-folders) | sudo tee /etc/sudoers.d/papirus-folders\n\u003e sudo chmod 440 /etc/sudoers.d/papirus-folders\n\u003e ```\n\u003e ```sh\n\u003e # Bash/other shells\n\u003e echo \"$USER ALL=(ALL) NOPASSWD: $(which papirus-folders)\" | sudo tee /etc/sudoers.d/papirus-folders\n\u003e sudo chmod 440 /etc/sudoers.d/papirus-folders\n\u003e ```\n\u003e \n\u003e **Alternatively** - Edit the main sudoers file by running `sudo visudo` and adding at the end:\n\u003e ```\n\u003e your_username ALL=(ALL) NOPASSWD: /usr/bin/papirus-folders\n\u003e ```\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## 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## 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","funding_links":["https://github.com/sponsors/soramanew","https://ko-fi.com/soramane","https://buymeacoffee.com/soramane"],"categories":[],"sub_categories":[],"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"}