userctx/config.toml

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

# "tasks" array must not be empty
# it tells userctx what to do (which apps
# should be actually managed)
tasks = [
  "sway",
  "gtk",
  "helix",
  "foot",
  "wofi",
  "mako",
]

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

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

# This section of config is intended to document
# what userctx can do. Assume we are 
# building a config for app "example"
[task.example]
# the default path to apply your context to is
# ~/.config/example (for app name "example")
# "target_path" overrides this.
# If set then $CONTEXT_DST env will hold this value and
# symlinks will be created relative to this specified 
# path.
target_path = "~/.config/example/configs"

# "actions" array defines which steps should be 
# executed to apply content from 
# context directory to users home 
# directory. If actions array is empty the default
# behaviour is to just symlink everything from
# $CONTEXT_SRC to $CONTEXT_DST
actions = [
  "symlinks", # do the symlinking as specified in "symlinks array below"
  "code", # execute shell script from object "code" below
  "commands", # run commands from "commands array below"
  "scripts", # run scripts from "scripts" array below
]

# "symlinks" array of mappings (inline tables of TOML) defines
# which files will be symlinked to users home
# directory. If "symlinks" key is present in
# "actions" above but this "symlinks" array is omitted
# then userctx treats all files in the context directory as 
# files that must be symlinked to users home.
symlinks = [
  # names of files in these mapping are relative to 
  # context directory and target directory
  # by default source is ~/.config/userctx/<context_name>/example for
  # task (app) named "example" 
  # default target directory is ~/.config/example for 
  # task (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
  {"context_file.conf" = "symlink_to_context_file.conf"},
  
  # this will link file to subdirectory inside destination dir
  # directory must be created beforehand 
  # $CONTEXT_SRC/other_file.conf -> $CONTEXT_DST/subdir/other_file.conf
  {"other_file.conf" = "subdir/other_file.conf" },
  # also possible option
  {"subdir/yet_another_file.conf" = "yet_another_file.conf" },
]

# "code" object let's you write
# a custom script that will apply contents of
# your context. Note that string is a multiline string
# strating and ending with three double-qoutes. 
# This string will be passed as is to $SHELL -c <string>
code = """
  # 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"
"""

# Another way in run something when applying context
# is to define "commands" array.
commands = [
  ['first_command', '--arg1', 'value', '--arg2', 'value2'],
  ['second_command', '--arg1', 'value', '--arg2', 'value2'],
]

# scripts array 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 "task.gtk section below")
scripts = [
  "script1.sh",
  "script2.sh",
]

# reload command (if set) will be executed after
# all actions
reload = ['echo', 'this is my reload command']

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

[task.niri]
target_path = "~/.config/niri/configs"
actions = [
  "symlinks",
  "code",
]

# 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 [task.niri] altogether.
code = """
  cat ~/.config/niri/configs/* > ~/.config/niri/config.kdl
"""

[task.helix]
actions = [
  "symlinks",
  "code",
]
# context must contain file named "helix.toml" which describes a theme.
symlinks = [
  # $CONTEXT_SRC/helix.toml -> $CONTEXT_DST/themes/current_theme.toml
  {"helix.toml" = "themes/current_theme.toml"}
]
code = """
  sed -i -E 's/^theme = (.+)/theme = "current_theme"/' ~/.config/helix/config.toml
"""
reload = ['pkill', '-USR1', 'hx']

[task.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 = ["scripts"]

[task.mako]
reload = ["makoctl", "reload"]

[task.sway]
reload = ["swaymsg", "reload"]

[task.kitty]
reload = ['pkill', '-USR1', 'kitty']

[task.waybar]
reload = ['pkill', '-USR2', 'waybar']

[task.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']