🪄 Soothing pastel theme manager (WIP)

  • By Catppuccin
  • Last update: Jan 7, 2023
  • Comments: 11

Catppuccin CLI

Catppuccin CLI

A work-in-progress CLI for Catppuccin themes.

It allows you to:

  • Install themes with one command
  • Uninstall themes with one command
  • Update themes with one command


  • You can download the executable for this project from the releases section. Download the release as per your OS.


  • The foremost requirement to develop is to make sure that go version 1.19 is installed.
  • Clone the repository and switch to the dev branch.
  • Make all the changes to dev branch. To build the executable run go build -o ctp.


  • You need to make sure that you set the environmental variable $ORG_OVERRIDE to catppuccin-rfc or the tool will search for .catppuccin.yaml in the catppuccin organisation which currently doesn't host the yaml files. This is a temporary measure to test the tool during its development.


  • Clone Template Repo
  • Interactive Setup
  • Custom Bubbletea UI
    • Theme Name
    • Interactive ctprc builder
      • Program Name
      • Operating Systems
      • Install Location
  • Handle inputs by renaming and editing files


Copyright © 2021-present Catppuccin Org




  • 1

    Rename package to ctp by changing locations

    Optional, but raising an issue since we spoke about it in Discord.

    Perhaps the current cmd directory could be moved to internal, and we could move main.go to cmd/ctp

    This would mean that building would no longer strictly require the -o flag, and go install would work out of the box.

  • 2

    Caching repos bug

    Error: repos.json does not exist. Caching JSON...Received repositories. Caching! Cannot open file.

    This happens when trying to search a catppuccin port.

  • 3

    Install command attempts to install even when no arguments are passed

    Describe the bug This is a trivial bug and more so a cleanup step then anything but when running ctp install without a specific input argument, the cli attempts to install rather than detect that there was no input and exit gracefully.

    Observed behaviour The issue I've seen is as follows:

    1. Install and build the cli.
    2. run ./ctp install
    3. ctp attempts to install packages and attempts to check for installed packages but outputs nothing.

    Expected behavior ctp returns an error indicating that for the install com

    Screenshots Screen Shot 2022-10-30 at 11 13 46 AM mand cannot have an empty arg.

    Device Information OS: MacOS

  • 4

    Why are we cloning repos to pwd?

    Wouldn't cloning repos to the pwd make it harder to check if something is already installed? If we're installing themes, are we installing them to a particular directory depending on the project? So, for example kitty themes we would want to install it at ~/.config/kitty/themes/ or something. Would it be worth having some confirmation of the default install location and you can provide an alternate location if you want?

  • 5

    Unclear error message when initializing a duplicate project

    Describe the bug When you try to create a new project with a name that conflict with an existing project, the error message is too vague to help debug.

    Expected behavior I believe the error message should state that a project with the name ____ already exists in insert location

    Screenshots error message

    Device Information MacOS Monterey go version go1.19 darwin/arm64

  • 6

    feat uninstall hook

    • build: add a makefile
    • style: some qol changes
    • build: just the little things
    • docs: add build instructions
    • chore: update gitignore
    • build: whoops i forgor
    • feat: uninstall hooks
  • 7

    feat: add JSON Schema

    There are a few extraneous commits in here, let me know if you want them removed or in another PR.

    1. Running https://github.com/mvdan/gofumpt changed a few things
    2. I opted to use https://github.com/matryer/is as an assertion library.

    Both mvdan/gofumpt and matryer/is are personal preferences, so feel free to veto them.
    Of note, mvdan/gofumpt is fully compatible with gofmt, so it shouldn't cause conflicts.

    And of course, the point of the PR, please take a look at the schema to make sure it makes sense. I followed the spec as closely as I could.


  • 8

    Major Internal Overhaul

    List of changes:

    • Installation now saves an extra file containing installed files
    • Removal now actually works and uses said file to uninstall properly
    • Utils has been split up into four files

    Took a lot of time and a lot of blood was shed.

  • 9

    Bug: Remove function removing wrong files

    Description The remove function needs a rewrite and as it currently stands, it does not yet handle flavours. But the function removes the top-level directory for most applications which is intended but this can cause issues with some electron based applications which store their user configuration in these top-level Directories (example: catppuccin/joplin or catppuccin/element). Invoking the remove command for such apps also removes the user configuration and usually logs the user out. This needs to be tackled.

    Possible approach This can be worked in tandem with #14 by saving the installation location of the config for an application and then reading this installed location to uninstall only the required files, thus not removing the top-level directory.

  • 10

    Suggestion: Save location instead of flavour name for easier uninstallation.

    This is more of a suggestion, not a bug

    An alternate implementation idea for saving flavours during install

    Currently, the half-working implementation saves the flavour the user enters and saves it to a file flavours.yaml at $XDG_DATA_HOME/catppuccin-cli/. This is a bit problematic since this also causes #13. An alternate way to tackle this was suggested by @DakshG07, where we can store the location where a new config is being installed and then this location can be used during installation.

  • 11

    Bug: Cli cannot detect already installed flavours if not on the first position in flavours.yaml file.

    Description of the issue

    • The cli cannot detect when the user reinstalls the same flavour again but its position is not first in flavours.yaml file.

    Current behaviour If the contents of the flavours.yaml file is:

    app_name: helix
        flavour: mocha
    app_name: helix
        flavour: latte

    and if the user tries to reinstall the latte variant, it should throw an error since latte is installed already but it instead throws the error:

    Error: yaml: unmarshal errors:
      line 4: mapping key "app_name" already defined at line 1
      line 7: mapping key "app_name" already defined at line 1
      line 5: mapping key "installed_flavour" already defined at line 2
      line 8: mapping key "installed_flavour" already defined at line 2
    --- snipped ---

    Expected behaviour The cli should detect that the latte variant is already installed and instead throw the error:

    Flavour latte already exists for helix
    exit status 1

    A good start approach in solving this would be to understandthe MakeFlavour function: https://github.com/catppuccin/cli/blob/b0a050535705e70f2493606fc8dd382ff87ae088/internal/utils/utils.go#L406

    Acceptance criteria Any changes should be made on the dev branch and the PRs should be opened against the dev branch itself.