userctx/config.toml

[general]
# if dry run is set to true
# userctx will only validate config 
# and tell you what it will do to apply context
# tasks
dry_run = true

# "apps" array tells userctx what to do (which apps
# should be actually managed). If it is empty or not
# set, then userctx will do nothing.
# Uncomment apps below.
apps = [
  "niri",
  "fuzzel",
  "gtk",
  "helix",
  "kitty",
  "mako",
  "sway",
  "swaybg",
  "waybar",
  "wofi",
]

# target directory where managed configs
# are located 
# defaults to $XDG_CONFIG_HOME if specifically set
# or ~/.config if $XGD_CONFIG_HOME is not set
target_path = "~/.config"

# directory where contexts are stored
# default is "~/.config/userctx"
source_path = "~/.config/userctx"

# section that demonstrates all the available
# features of userctx
[apps.example]
# The default path to apply your context to is
# ~/.config/example (for app name "example")
# if not overridden with general.target_path.
# Setting "target_path" overrides this.
# $CONTEXT_DST env will hold  the actual destination path.
# symlinks will be created relative to this specified 
# path.
target_path = "~/.config/example/configs"

# "symlink" map defines
# which files will be symlinked to users home
# directory.
# Names of files in this mapping are relative to 
# context directory and target directory
# by default source is ~/.config/userctx/<context_name>/example 
# and target directory is ~/.config/example
# for app named "example" 
#
# this will link file from context dir to destination dir
# $CONTEXT_SRC/context_file.conf -> $CONTEXT_DST/symlink_to_context_file.conf
symlink."context_file.conf" = "symlink_to_context_file.conf"

# this will link file to subdirectory inside destination dir
# Note that destination subdir must be created beforehand.
# $CONTEXT_SRC/other_file.conf -> $CONTEXT_DST/subdir/other_file.conf
symlink."other_file.conf" = "subdir/other_file.conf"
symlink."subdir/yet_another_file.conf" = "yet_another_file.conf"

# If symlinks mapping is not empty then only instructions from the map
# will be applied. If you want to redefine linking rules only for single
# file and symlink others according to default rules then add the following
# rule as well. 
symlink."*" = "*"

# As a special case, providing the following mapping symlinks
# a SINGLE file (the first one found) from context directory
# to a specified name (see helix section below).
# This reads "symlinks ANY file you find to this path".
# symlink."*" = "some/destination.conf"


# "exec" let's you write a reload command or
# even a bigger custom script that will apply contents of
# your context. Note the triple double-qoutes for multiline
# strings (see TOML spec). 
# This string will be passed as is to $SHELL for execution.
exec = """
  # this is a normal shell script which will
  # be executed by user's $SHELL or 'bash' binary
  # if users $SHELL is empty

  # users envs are available
  echo "$HOME" 

  # additional envs are available 
  echo "$CONTEXT_SRC"
  echo "$CONTEXT_DST"
  echo "$CONTEXT_NAME"
"""

# if "script" array is not empty
# then userctx will try to find
# named files in $CONTEXT_SRC and 
# execute them with $SHELL <script>
# IMPORTANT: if array is empty
# and action "scripts" is present in 
# "actions" array above then all files
# in $CONTEXT_SRC will be treated as scripts
# (note the "apps.gtk section below")
script = [
  "script1.sh",
  "script2.sh",
]

# if "reload" is present, the command will be executed after everythong alse is done
reload = "pkill -USR1 example"

# "actions" array specifies the order of actions when
# applying context. If omitted, the default behaviour
# it to symlink, run scripts, run exec part then run reload
# command (if relevant actions are specified).
# If nothig has been customized in apps configuration here
# (no commands array, not symlinks mapping etc.) then userctx
# will just symlink anythong it finds to target_path.
# If actions array is declared empty (actions = []) then
# userctx will do nothig. 
actions = [
  "symlink",
  "exec",
  "script",
  "reload",
]

#########################
# settings for some
# commonly used apps
#########################

[apps.niri]
target_path = "~/.config/niri/configs"

# The snippet below is needed for niri 25.8 which did not
# support imports/includes in the config. I'm splitting
# config into several parts and them concatenating them 
# after applying changes to theme. The other parts are left intact.
# Also note the custom target path above. It instructs userctx to
# symlink configs found in the context dir to 
# ~/.config/niri/configs, which then get concatenated.
# For niri since 25.11 you can just put your includes
# into the context dir and omit [apps.niri] altogether.
exec = """
  cat ~/.config/niri/configs/* > ~/.config/niri/config.kdl
"""

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

[apps.gtk]
# To setup the look of GTK you may put a simple shell script
# into ~/.userctx/<context_name>/gtk/theme.sh with contents similar to: 
# gsettings set org.gnome.desktop.interface color-scheme 'default'
# gsettings set org.gnome.desktop.interface gtk-theme 'Yaru'
# gsettings set org.gnome.desktop.interface icon-theme 'Yaru'
actions = ["script"]

[apps.mako]
reload = "makoctl reload"

[apps.sway]
reload = "swaymsg reload"

[apps.kitty]
reload = 'pkill -USR1 kitty'

[apps.waybar]
reload = 'pkill -USR2 waybar'

[apps.swaybg]
# This config is for swaybg setup as s systemd service.
# Unit runs "swaybg -m fill -i "%h/.config/swaybg/wallpaper".
# ~/.config/userctx/<context>/swaybg/ contains single file 
# called "wallpaper" which gets symlinked to ~/.config/swaybg/wallpaper
target_path = '~/.config/swaybg'
reload = 'systemctl --user restart swaybg.service'