💅 PyThemes

Simple CLI tool for update themes, with find/replace and execute commands

Description

I use a window manager WM, like dwm, so I need to manage my themes, colorschemes manually.

This script will take care of that. It's designed to handle system and application themes, including light dark mode switching, wallpaper settings, and command execution.

Usage

~ $ pythemes -h
Usage: pythemes [-h] [-m MODE] [-l] [-e] [-a APP] [-L] [-d] [-v] [--color] [--diff] [--verbose] [--no-global] [theme]

    Simple CLI tool for update themes files, with find/replace and execute commands.

Options:
    theme               Theme name
    -m, --mode MODE     Select a mode [light|dark]
    -e, --edit          Edit theme with $EDITOR
    -l, --list          List themes found
    -a, --app APP       Apply mode to app
    -L, --list-apps     List available apps in theme
    -D, --dry-run       Do not make any changes
    --diff              Show app diff
    --color             Enable color [always|never] (default: always)
    --no-global         Do not apply global configuration file
    -V, --version       Print version and exit
    -v, --verbose       Increase output verbosity
    -h, --help          Print this help message

Apply theme/mode

~ $ pythemes gruvbox -m dark
> gruvbox theme with (10 apps)
[app] bat applied
[app] rofi applied
[app] xresources applied
[app] fzf applied
[app] gtk2-mine no changes needed
[app] gtk3 applied
[app] newsboat applied
[app] nvim applied
[app] git applied
[app] zathura applied
[cmd] dunst executed
[cmd] xresources executed
[wal] my-dark-wallpaperjpg set
[sys] dwm restarted
[sys] st restarted
~ 10 apps updated ~

Apply theme/mode to single app

~ $ pythemes gruvbox -m dark -a fzf
[app] fzf applied

Show diff for single app

~ $ pythemes gruvbox -m light --app fzf --diff
[app] fzf has changes

- source "$DOTFILES/fzf/themes/gruvbox-dark.fzf"
?                                      ^^^^
+ source "$DOTFILES/fzf/themes/gruvbox-light.fzf"
?                                      ^^^^^

Installation

• Simple copy:

Copy the main script to your $PATH, and rename it as you want.

• Cloning repository:

# Clone repository
~ $ git clone "https://github.com/mateconpizza/pythemes"
~ $ cd pythemes

# Create virtual environment & source
~ $ python -m venv .venv & source .venv/bin/activate

# Install
(.venv) $ pip install .

• Using uv to install tool:

~ $ cd /path/to/cloned/pythemes
~ $ uv tool install .

• Using pipx to install tool:

~ $ pipx install /path/to/cloned/pythemes

Theme Configuration

The theme file, is an INI file that has 3 sections for now.

• program: section for programs settings
• wallpaper: section for wallpapers settings
• restart: section for restart settings

Program Section

[program_name]:
file:     path to the file to update
query:    the query to find in the file
light:    the theme to use for the light theme
dark:     the theme to use for the dark theme
cmd:      the command to execute (optional)

Command Section (WIP)

[cmd]:
...

Wallpaper section

[wallpaper]
light:    path to the wallpaper for the light theme
dark:     path to the wallpaper for the dark theme
random:   path to the directory with the wallpapers
cmd:      the command to execute

Restart section

Will search for PIDs _{process ids} that match the cmd and send the signal SIGUSR1

[restart]
cmd:      commands that will receive the signal SIGUSR1

Example

This is a example INI file for pythemes.

You can find the complete example here

; the script will read this file and find the `query` line and replace it with
; the `{theme}` value and then execute the `cmd` command if it  is set

[wallpaper]
light=~/wallpapers/my-light-wallpaper.png
dark=~/wallpapers/my-dark-wallpaper.png
random=~/dls/wallpapers/
cmd=nitrogen --save --set-zoom-fill

[bat]
file=~/.config/shell/some-envs.sh
query=export BAT_THEME="{theme}"
light=gruvbox-light
dark=gruvbox-dark

[rofi]
file=~/.config/rofi/config.rasi
query=@theme "{theme}"
light=gruvbox-light-hard
dark=gruvbox-dark

[restart]
cmd=dwm st

Global Configuration (Optional)

pythemes supports an optional global configuration file named global.ini.

If this file exists in the themes directory ($XDG_CONFIG_HOME/pythemes), it will be automatically applied after the selected theme.

This allows you to define shared behavior across all themes, such as:

• Global environment variables
• Application-wide dark/light flags
• Shared color variants
• System-level toggles

The global file follows the same INI structure as any theme file.

You can disable it using:

~ $ pythemes gruvbox -m dark --no-global

Example

[qutebrowser-darkmode]
file=~/.config/qutebrowser/settings/user.py
query=is_dark={theme},
light=False
dark=True

[env-global-theme]
file=~/.config/shell/theme.sh
query=export GLOBAL_THEME={theme}
light=light
dark=dark

[gtk3-prefer]
file=~/.config/gtk-3.0/settings.ini
query=gtk-application-prefer-dark-theme={theme}
light=0
dark=1

[github-cli]
file=~/.config/shell/gh.sh
query=export GLAMOUR_STYLE={theme}
light=light
dark=dark

[duf]
file=~/.config/shell/alias.sh
query=duf -hide special --theme={theme}'
light=light
dark=dark