userctx

Manage you configurations and themes with ease.

Installation

You just need to copy the file to a directory in your $PATH (for example: /usr/loca/bin) and copy/create a config file.

sudo install userctx.py /usr/local/bin/userctx
mkdir -p ~/.config/userctx
cp config.toml ~/.config/userctx

userctx basics

userctx manages configuration contexts. A context is a directory somewhere in your system which stores actual configuration files for your apps similar to what resides in ~/.config.

Typically a context directory looks like this.

/home/dmitry/.config/userctx/Goldfish
├── sway
│   └── theme.conf
└── wofi
    └── style.css

In the above example, context "Goldfish" contains configs for apps "sway" and "wofi". These configs will be applied when you apply context "Goldfish".

When a context is applied the app configs from context directory are symlinked you ~/.config/ folder for each managed app. Goldfish/wofi/style.css symlinks to ~/.config/wofi/style.css, Goldfish/sway/theme.conf symlinks to ~/.config/sway/theme.conf etc.

This default behaviour can be changed and specific actions or customizations can be configured on per-app basis by editing userctx config file. The default location for the config is ~/.config/userctx/config.toml.

userctx can also be configured to run scripts, trigger your apps to reload configs etc. For a detailed overview of all config options see below.

There are two commands userctx understands: list and apply.

• list lists available contexts in a manner suitable for dmenu-like menu apps
• apply <context> applies named context

To test your configuration run:

userctx --nop apply <context_name>

The program will then only output what it will do without changing anything in your home directory.

For a quickstart and simple examples jump to "Examples" section below.

Configuring userctx

TODO: full description of config options.

Examples

Basic usecase: we only need symlinks

Let's add configuration for "foot" terminal emulator, which will be applied when we apply context "Goldfish" assuming we would like to switch foot's visual theme when swithching context.

1. First we need to create a separate file for visuals config in out context directory.

mkdir ~/.config/userctx/Goldfish/foot/
vim ~/.config/userctx/Goldfish/foot/theme.ini

And put the awesome "Tempus Day" into theme.ini:

# -*- conf -*-
# theme: Tempus Day
# author: Protesilaos Stavrou (https://protesilaos.com)
# description: Light theme with warm colours (WCAG AA compliant)

[colors]
foreground = 464340
# original background
# background = f8f2e5
background = ffffff
regular0 = 464340
regular1 = c81000
regular2 = 107410
regular3 = 806000
regular4 = 385dc4
regular5 = b63052
regular6 = 007070
regular7 = e7e3d7
bright0 = 68607d
bright1 = b24000
bright2 = 427040
bright3 = 6f6600
bright4 = 0f64c4
bright5 = 8050a7
bright6 = 336c87
bright7 = f8f2e5

You could as well symlink any file (pre-existing theme for foot) to ~/.config/userctx/Goldfish/foot/theme.ini

2. To include this theme file from main foot config add the following line to $HOME/.config/foot/foot.ini (edit to match your user's homedir):

include=/home/dmitry/.config/foot/theme.ini

Do not forget to remove style settings from foot.ini so they do not conflict with separate theme.ini.

3. Finally, tell userctx to manage foot config for you. Edit ~/.config/userctx/config.toml and add "foot" to "apps" array in "general" section of the config.

[general]
apps = [
  "foot",
  "sway",
  "wofi",
]

4. Test you configuration

userctx --nop apply Goldfish

The --nop (no-op) flag tells userctx to perform a dry-run. It will just output what it is going to do when you actually apply context.

If all looks good - that's it. When you issue userctx apply Goldfish a symlink will be created in your homedir:

~/.config/foot/theme.ini -> ~/.config/userctx/Goldfish/foot/theme.ini

More advanced usecase: run command and hot-reload

Let's configure userctx to apply theme to helix editor.

1. Similar to the above section, create ~/.config/userctx/Goldfish/helix/helix.toml with the following contents:

inherits = "github_light"
"ui.background" = {}

Now edit ~/.config/userctx/config.toml.

Add the "helix" to "general" section.

[general]
apps = [
  "foot",
  "sway",
  "helix",
  "wofi",
]

2. Add "apps.helix" section:

[apps.helix]
symlink."*" = "themes/current_theme.toml"
exec = """sed -i -E 's/^theme = (.+)/theme = "current_theme"/' ~/.config/helix/config.toml"""
reload = "pkill -USR1 hx"

Here we instruct userctx to symlink any (single) file it finds in "helix" subdirectory of context folder to ~/.config/helix/themes/current_theme.toml

Then we run sed to change the config file. This part is not really necessare if helix is configured to use theme named "current_theme" and you're sure that config won't change. We could just replace the file and issue USR1. The sed part if for the case when config is changed by user or other app.

Finally we set the reload command which will tell helix to reload config.

3. Test your configuration,

userctx --nop apply Goldfish

See also template "config.toml" with numerous app settings.