Integration Types

Themis supports four integration types for theming applications. Each type is suited for different scenarios.

Template

Renders Jinja2 templates with profile variables. This is the recommended approach for most applications.

enroll:
  kitty:
    type: template
    input: "~/.config/themis/templates/kitty.j2"
    output: "~/.config/kitty/.themis.conf"
    reload_cmd: "kill -SIGUSR1 $(pgrep kitty)" # optional
    reload_signal: SIGUSR1 # optional (uses pkill)

Template Syntax

Templates use Jinja2 syntax:

~/.config/themis/templates/kitty.j2

foreground {{ fg }}
background {{ bg }}
font_family {{ font_family }}
font_size {{ font_size }}

{% if transparency is defined %}
background_opacity {{ transparency }}
{% endif %}

Special Variables

Templates receive these additional variables:

• profile_name - Name of the loaded profile
• app_name - Name of the current app (e.g., “kitty”)

Reload Options

• reload_cmd - Shell command to reload the app
• reload_signal - Signal name (e.g., SIGUSR1, USR2) sent via pkill -<signal> <app_name>

Most apps with live reload only need one of these. Kitty, for example, watches its config files automatically and needs neither.

Symlink

Creates symlinks with variable interpolation in the source path. Useful for apps that need entire config files swapped.

enroll:
  alacritty:
    type: symlink
    source: "~/.config/themis/configs/alacritty-{{ mode }}.toml"
    target: "~/.config/alacritty/colors.toml"
    reload_cmd: "touch ~/.config/alacritty/alacritty.toml"

With a profile containing mode: dark, this creates:

~/.config/alacritty/colors.toml -> ~/.config/themis/configs/alacritty-dark.toml

Command

Executes shell commands with variable interpolation. Ideal for apps configured via CLI tools.

enroll:
  gtk:
    type: command
    commands:
      - "gsettings set org.gnome.desktop.interface gtk-theme '{{ gtk_theme }}'"
      - "gsettings set org.gnome.desktop.interface color-scheme '{{ color_scheme }}'"

Commands are executed sequentially. If one fails, subsequent commands still run (with a warning logged).

Common Use Cases

• GTK/GNOME settings via gsettings
• Plasma settings via kwriteconfig5
• Wallpaper changes via feh, swaybg, etc.

Script

Executes external scripts with environment variables. Best for complex logic that doesn’t fit in commands.

enroll:
  custom:
    type: script
    path: "~/.config/themis/scripts/custom.sh"
    args: ["--mode", "{{ mode }}"]
    env:
      CUSTOM_VAR: "value"

Environment Variables

All profile variables are passed as THEMIS_<VAR> environment variables:

#!/bin/bash
# All variables available as THEMIS_* env vars
echo "Background: $THEMIS_BG"
echo "Foreground: $THEMIS_FG"
echo "Mode: $THEMIS_MODE"

Array values are colon-delimited (Unix convention):

# Profile
vars:
  colors: ["#111", "#222", "#333"]

# In script
echo $THEMIS_COLORS  # "#111:#222:#333"

Choosing the Right Type

Scenario	Recommended Type
App supports config includes	Template
App watches config files	Template
App needs entire file replaced	Symlink
App configured via CLI tools	Command
Complex conditional logic	Script
Need to call other programs	Script

Integration Order

Apps are processed in the order they appear in themis.yaml. Use this to ensure dependencies are set up first:

enroll:
  # Set GTK theme first
  gtk:
    type: command
    commands: [...]

  # Then apps that might read GTK settings
  firefox:
    type: script
    path: [...]

Error Handling

When an integration fails:

1. The error is logged
2. Processing continues to the next app
3. A summary is shown at the end
4. Exit code is 1 if any apps failed

Use --dry-run to preview all changes before applying:

themis load my-profile --dry-run