Skip to Content
Matuwall

CLI Reference

Every command-line option

matuwall [options]

Options apply to one run and never edit the config. They are processed left to right. The last conflicting option wins.

General

OptionDescription
-h, --helpShow help
-V, --versionShow the version
--config PATHLoad another config file
--no-configStart from built-in defaults
--print-configPrint the resolved config as TOML and exit
-d, --directory DIRWallpaper directory. Repeat for several
--recursive, --no-recursiveInclude or skip subdirectories
--list FILERead wallpapers from a list file. - reads stdin
--favorites FILEFile the f key adds to
-b, --backend NAMEawww, sweetbg, plasma, command or auto
-o, --output NAMEOpen on one monitor, e.g. DP-1

Window

OptionDescription
-p, --position POScenter, left, right, top or bottom
--preview, --no-previewFull-screen preview
--close-on-focus-loss, --no-close-on-focus-lossClose when focus leaves
--close-on-apply, --no-close-on-applyClose after Enter applies
--background COLORPanel color. none draws no panel
-m, --margin NPanel padding
--edge-margin NGap to the monitor edge
--panel-radius NPanel corner radius

Quote colors, # starts a shell comment: --background '#181825cc'

Layout

OptionDescription
--carousel, --no-carouselCarousel or regular grid
--edge EDGEauto, clip, peek or fade
--sort SORTname or color
-c, --columns NMax columns or carousel tiles
-r, --rows NMax visible rows
-s, --spacing NTile spacing
--radius NTile corner radius
-w, --width NThumbnail width
--height NThumbnail height

Tile Style

Colors accept #rrggbb, #rrggbbaa or none. A width of 0 disables that effect.

OptionDescription
--tile COLORPlaceholder color
--border COLORBorder color
--border-width NBorder width
--shadow COLORShadow color
--shadow-width NShadow width
--ring COLORSelection ring color
--ring-width NSelection ring width
--spinner COLORLoading dot color

Animation

OptionDescription
--navigation-ms NNavigation time, 0..1000. 0 disables it
--zoom-percent NSelected tile growth, 0..10. 0 disables it

Backend

OptionDescription
--backend-arg ARGReplace, then append, backend flags. One per argument
--no-backend-argsClear backend flags
--backend-command CMDUse a custom command. Must contain {path}

Hooks

OptionDescription
--hook COMMANDReplace, then append, hooks
--no-hooksClear hooks

Without the Picker

Apply and exit. Use only one per run.

OptionDescription
--restoreApply the remembered wallpaper again
--randomApply a random wallpaper, never the current one
--nextApply the next wallpaper
--prevApply the previous wallpaper

Maintenance

OptionDescription
--diagnoseCheck config, paths, Wayland, backends, hooks, state and cache
--clear-cacheDelete cached thumbnails and exit

Exit Codes

CodeMeaning
0Success, or --diagnose with warnings only
1Failed apply, or a blocking --diagnose error
2Invalid CLI usage

Examples

From the demo video:

matuwall -d ~/Pictures/Wallpapers --preview --carousel -b sweetbg -c 5 -w 280 --height 150 -p bottom --background none
matuwall -d ~/Pictures/Wallpapers --preview --no-carousel -b sweetbg -c 3 -r 3 -w 380 --height 250 -p center --background none
matuwall -d ~/Pictures/Wallpapers --preview --carousel -b sweetbg -c 3 -w 380 --height 250 -p left

Clean temporary setup:

matuwall --no-config -d ~/Pictures/Wallpapers -b awww

Work profile on another monitor:

matuwall --config ~/.config/matuwall/work.toml -o HDMI-A-1

On this page