Introduction

Theris is a tool that helps manage color schemes for different applications. It really shines when used with software that has a file based configuration.

Unfortunately it's impossible to make this in a "configuration free" manner as each application has it's own settings. Theris requires some work to be done but nothing too fancy. It can take few minutes and some minor changes on your environment to make it work with everything.

You should see Configuration to learn more about it. In short you will need to:

• Create some template files
• Define your color schemes
• Tell theris how to apply the theme

Installation

At the time being there are two ways of installing theris. Even tho both methods requires building from source, the process still easy.

Using Cargo

First thing you'll need is installing Rust and Cargo. Follow this and you should be good.

Then run:

cargo install --git https://github.com/marcos-brito/theris theris

Make sure ~/.cargo/bin is in your $PATH variable

Cloning the source

Assuming you have Git, Rust and Cargo installed, first clone the repository:

git clone https://github.com/marcos-brito/theris && cd theris

After that you'll need to compile the code:

cargo build --release

The final step is move the compiled binary to somewhere you can use:

cp ./target/release/theris ~/.local/bin

Configuration

Theris needs at least two files to work properly:

• themes.yaml
• appliers.yaml

The default path for both is ~/.config/theris, but you can provide another using the CLI. You can also create a templates directory within the same path to define your templates.

As theris modifies some possibly important files, it optionally creates backups using tar and gunzip to keep you safe. For that you'll need to create ~/.local/share/theris/backup.

Some warns will pop on your terminal if something is missing

If you are on a hurry, copy and paste this on your terminal:

mkdir -p ~/.config/theris/templates ~/.local/share/theris/backup &&
touch ~/.config/theris/themes.yaml ~/.config/theris/appliers.yaml

Themes

themes.yaml is where you list your themes. Each one of them has:

• A name
• A list of colors
• Some extra data (optional)

The file can look something like this:

- name: "gruvbox"
  colors:
    background: "#141617"
    foreground: "#ddc7a1"
    blue: "#7daea3"
  extra:
    wallpaper: "/home/you/.config/hypr/wallpapers/gruvbox.png"

- name: "catppuccin"
  colors:
    background: "#181724"
    foreground: "#ffffff"
    blue: "#89b4fa"
  extra:
    wallpaper: "/home/you/.config/hypr/wallpapers/catppuccin.png"

The keys for both the colors and extra data are up to you. One can define something like the following and proceed with no problems:

- name: "gruvbox"
  colors:
    joe: "#141617"
    doe: "#ddc7a1"
  extra:
    foo: "/home/you/.config/hypr/wallpapers/gruvbox.png"
    bar: "Hello world"

Be aware that the only difference between colors and extra for theris is the way they will be showed in the terminal by the list command. Using the same keys can arise unexpected behavior.

Templates

The templates are read from ~/.config/theris/templates by default. As you'll see in Appliers, it's also possible to use inline templates in appliers.yaml.

Theris uses a template engine named Tera. It has various features but you probably need just a basic usage. Here is an example:

bg = {{background}}
fg = {{foreground}}
accent = {{blue}}
font = {{font}}

Everything defined in the colors or extra field can be referenced directly using {{}}. For more complex rendering you should check Tera's documentation.

Appliers

appliers.yaml tells theris how to apply the theme for different applications. The file will look like this:

- name: kitty
  path: /home/you/.config/kitty/theme.conf
  method: !Template
    template: kitty

- name: eww
  path: /home/you/.config/eww/eww.scss
  method: !Delimiter
    template: eww
    start: "// theris start"
    end: "// theris end"

- name: tmux_hook
  path: ""
  method: !Script
    path: "/home/you/.config/theris/tmux.sh"

Every key is needed. Here is a description for each:

• name: The applier's name. It's relevant when using the CLI.
• path: It's the file that will be modified and consequently the file to be in the backup.
• method: This is what actually tells theris how to apply the theme. There are a few options. Each one is described right ahead.

!Template

It overwrites the whole file specified in path.

Parameters

• template: The file name of the template inside the templates directory

!Delimiter

It overwrites a portion of the file specified in path using delimiters. The delimiters are searched line by line and surrounding white space is ignored.

Parameters

• template: The file name of the template inside the templates directory or a inline template.
• start: A string that matches the start of the portion to be replaced
• end: A string that matches the end of the portion to be replaced

!ReplaceText

It replaces a text pattern in path with another.

Parameters

• target: A regular expression that matches the pattern to be replaced
• replacment: The text that will replace target. It can also be a inline template.

!Script

It runs a external executable. The theme being applied will be passed as a json to stdin.

Parameters

• path: The path to the executable file

Command line tool

Examples

There are some examples at the GitHub repository. You can check them here.