Skip to content
Themis

Getting Started

This guide walks you through installing Themis and creating your first profile. Themis runs on Linux and macOS.

Installation

Section titled “Installation”

Homebrew (macOS / Linuxbrew)

Section titled “Homebrew (macOS / Linuxbrew)”
Terminal window
brew install twowells/tap/themis

This is the recommended path on macOS. It also works under Linuxbrew on Linux, though native Linux users may prefer the source or distro options below.

From Source

Section titled “From Source”

Requires Rust 1.70+.

Terminal window
git clone https://github.com/TwoWells/Themis.git
cd themis


# User install (no sudo, installs to ~/.local)
make install PREFIX=~/.local


# System install (requires sudo, installs to /usr/local)
sudo make install

For user installs, ensure ~/.local/bin is in your PATH.

Shell Completions

Section titled “Shell Completions”

System installs include shell completions automatically. For user installs, add to your shell rc file:

Terminal window
# Bash (~/.bashrc)
eval "$(themis completions bash)"


# Zsh (~/.zshrc)
eval "$(themis completions zsh)"


# Fish (~/.config/fish/config.fish)
themis completions fish | source

Initialize Configuration

Section titled “Initialize Configuration”

Create the configuration directory structure:

Terminal window
themis init

This creates:

~/.config/themis/
├── themis.yaml           # Main configuration
├── profiles/
│   └── example.yaml      # Sample profile
├── palettes/             # User palettes
└── templates/            # Jinja2 templates

Your First Profile

Section titled “Your First Profile”

1. Create a Profile

Section titled “1. Create a Profile”

Edit ~/.config/themis/profiles/dark.yaml:

vars:
  bg: "#1a1a2e"
  fg: "#eaeaea"
  accent: "#e94560"
  font_family: "JetBrains Mono"
  font_size: 12

2. Enroll an Application

Section titled “2. Enroll an Application”

Edit ~/.config/themis/themis.yaml to enroll kitty:

enroll:
  kitty:
    type: template
    input: "~/.config/themis/templates/kitty.j2"
    output: "~/.config/kitty/.themis.conf"

3. Create a Template

Section titled “3. Create a Template”

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

# Generated by Themis - do not edit
foreground {{ fg }}
background {{ bg }}
font_family {{ font_family }}
font_size {{ font_size }}

4. Include the Generated File

Section titled “4. Include the Generated File”

Add this line to ~/.config/kitty/kitty.conf:

include .themis.conf

5. Load the Profile

Section titled “5. Load the Profile”
Terminal window
# Preview first
themis load dark --dry-run


# Apply for real
themis load dark

Verify Your Setup

Section titled “Verify Your Setup”

Check that everything is configured correctly:

Terminal window
# Validate YAML syntax and references
themis verify


# Check that apps have the include patterns
themis doctor

Platform Notes

Section titled “Platform Notes”

Themis behaves the same on Linux and macOS. It honors the XDG Base Directory environment variables on both platforms, with $HOME-relative defaults — so a config directory ports between machines unchanged. See the Configuration Reference for the exact resolved paths and how to redirect them.

On macOS there is no ~/Library/Application Support special-casing: config lives under ~/.config and state under ~/.local/state unless you point XDG_CONFIG_HOME / XDG_STATE_HOME elsewhere.

The apps shown throughout these docs (waybar, hyprland, kitty, …) are Linux desktop applications. On macOS, Themis themes whatever has a config file it can render or symlink into — the integration types are the same; only the set of apps you enroll differs.

Next Steps

Section titled “Next Steps”