Skip to Content
Matuwall

Hooks

Run matugen, pywal or any command after a wallpaper change

Hooks run after a successful apply. Use them for color generators or desktop refresh commands.

[hooks]
on_apply = [
  "matugen image {path}",
  "wal -i {path} -n",
]

{path} becomes the absolute wallpaper path, with symlinks resolved. Hooks start in the background. Matuwall does not wait for them.

No Shell

Each hook is split on whitespace and run directly. Wallpaper names can never become shell code.

These do not work:

  • Pipes | and redirects >
  • Globs like *.png
  • Variables like $HOME and ~
  • Shell quoting

{path} stays one argument, even with spaces in the filename.

Shell Logic in a Script

Put the logic in a script:

#!/bin/sh
set -eu

wallpaper=$1
matugen image "$wallpaper"
notify-send "Wallpaper changed"
chmod +x ~/.local/bin/matuwall-applied

Call it with an absolute path:

[hooks]
on_apply = ["/home/user/.local/bin/matuwall-applied {path}"]

Temporary Hooks

The first --hook replaces configured hooks. Later ones append:

matuwall --hook 'matugen image {path}' --hook 'wal -i {path} -n'

Disable all hooks once:

matuwall --no-hooks

Limits

LimitValue
Hooks16
Template length511 bytes before {path} expansion
Exit codesNot tracked

A hook that cannot start logs a warning.

On this page