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
| Option | Description |
|---|---|
-h, --help | Show help |
-V, --version | Show the version |
--config PATH | Load another config file |
--no-config | Start from built-in defaults |
--print-config | Print the resolved config as TOML and exit |
-d, --directory DIR | Wallpaper directory. Repeat for several |
--recursive, --no-recursive | Include or skip subdirectories |
--list FILE | Read wallpapers from a list file. - reads stdin |
--favorites FILE | File the f key adds to |
-b, --backend NAME | awww, sweetbg, plasma, command or auto |
-o, --output NAME | Open on one monitor, e.g. DP-1 |
Window
| Option | Description |
|---|---|
-p, --position POS | center, left, right, top or bottom |
--preview, --no-preview | Full-screen preview |
--close-on-focus-loss, --no-close-on-focus-loss | Close when focus leaves |
--close-on-apply, --no-close-on-apply | Close after Enter applies |
--background COLOR | Panel color. none draws no panel |
-m, --margin N | Panel padding |
--edge-margin N | Gap to the monitor edge |
--panel-radius N | Panel corner radius |
Quote colors, # starts a shell comment: --background '#181825cc'
Layout
| Option | Description |
|---|---|
--carousel, --no-carousel | Carousel or regular grid |
--edge EDGE | auto, clip, peek or fade |
--sort SORT | name or color |
-c, --columns N | Max columns or carousel tiles |
-r, --rows N | Max visible rows |
-s, --spacing N | Tile spacing |
--radius N | Tile corner radius |
-w, --width N | Thumbnail width |
--height N | Thumbnail height |
Tile Style
Colors accept #rrggbb, #rrggbbaa or none. A width of 0 disables that effect.
| Option | Description |
|---|---|
--tile COLOR | Placeholder color |
--border COLOR | Border color |
--border-width N | Border width |
--shadow COLOR | Shadow color |
--shadow-width N | Shadow width |
--ring COLOR | Selection ring color |
--ring-width N | Selection ring width |
--spinner COLOR | Loading dot color |
Animation
| Option | Description |
|---|---|
--navigation-ms N | Navigation time, 0..1000. 0 disables it |
--zoom-percent N | Selected tile growth, 0..10. 0 disables it |
Backend
| Option | Description |
|---|---|
--backend-arg ARG | Replace, then append, backend flags. One per argument |
--no-backend-args | Clear backend flags |
--backend-command CMD | Use a custom command. Must contain {path} |
Hooks
| Option | Description |
|---|---|
--hook COMMAND | Replace, then append, hooks |
--no-hooks | Clear hooks |
Without the Picker
Apply and exit. Use only one per run.
| Option | Description |
|---|---|
--restore | Apply the remembered wallpaper again |
--random | Apply a random wallpaper, never the current one |
--next | Apply the next wallpaper |
--prev | Apply the previous wallpaper |
Maintenance
| Option | Description |
|---|---|
--diagnose | Check config, paths, Wayland, backends, hooks, state and cache |
--clear-cache | Delete cached thumbnails and exit |
Exit Codes
| Code | Meaning |
|---|---|
0 | Success, or --diagnose with warnings only |
1 | Failed apply, or a blocking --diagnose error |
2 | Invalid 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 leftClean temporary setup:
matuwall --no-config -d ~/Pictures/Wallpapers -b awwwWork profile on another monitor:
matuwall --config ~/.config/matuwall/work.toml -o HDMI-A-1