WAL(1)

👑 WAL(1) — General Commands Manual, but make it a group chat 💅

okay so welcome to WAL(1), bestie. This is the General Commands Manual page and honestly it's a whole vibe. Sit down, grab a strawberry 🍓, and let's get into it.

---

✨ NAME ✨

wal — Generate colorschemes on the fly. That's it. That's the whole personality. 🎀

---

🦋 SYNOPSIS 🦋

wal [-hclnqrRstvwe] [-a alpha] [-b background] [--fg foreground]
[--backend [backend]] [--out-dir [out_dir]] [--theme /path/to/file or
theme_name] [--iterative] [--cols16 [method]] [--recursive] [--saturate
-1.0-1.0] [--preview] [--vte] [-i /path/to/img.jpg] [-o script_name] [-p
theme_name] [--contrast [1.0-21.0]]

yes that's the whole incantation, no cap. Copy it, don't retype it, i'm begging 🙈

---

💖 DESCRIPTION 💖

So wal is that girl 💅 — she generates a color palette from the dominant colors in an image and then she applies those colors system-wide, on-the-fly, in literally all of your favourite programs. Iconic behavior. Main character energy fr fr. 🔥

---

🌸 OPTIONS 🌸

okay the options section is long but we're getting through it together, one flag at a time 🫶

• -h, --help — prints a brief usage info to standard output and then dips out (exit).
• -a alpha — sets your terminal background transparency to alpha. Gotta be an integer from 0 to 100, no funny business. Only works in URxvt and terminals that implement the OSC-11 interface — so like, check before you yell at it 💀
• -b background — your custom background color goes here.
• --fg foreground — and this one's for the custom foreground color.
• --backend backend — which color backend you wanna use. Not sure? Run wal --backend and she'll list the backends for you ✨
• --out-dir /path/to/output dir — the directory where the built template files get output. By default wal exports the built templates to $XDG_CACHE_HOME/wal/. The output dir for the templates can also be set with the $PYWAL_CACHE_DIR env var — but using this flag overrides the internal CACHE_DIR variable, and that takes precedence over $PYWAL_CACHE_DIR. Precedence drama, we love to see it 👑
• -f, --theme /path/to/file or theme_name — which colorscheme file to use. Run wal --theme to list builtin and user themes, iykyk.
• --iterative — when pywal is given a directory as input and this flag is used: go through the images in order instead of shuffled. ordered, organized, that's the energy 🧚
• --cols16 method — use 16 color mode! This generates 16 color themes or converts 9 color themes to 16 colors. method is one of darken, lighten or dual — default: darken.
• --recursive — when pywal is given a directory as input and this flag is used: search for images recursively in subdirectories instead of the root only. dig deep bestie 🦋
• --saturate [-1.0-1.0] — set the color saturation. interpreted as percentage, ie: 1.00 = 100%, 0.50 = 50%. yes there's a lil trailing comma in the original, we're keeping it, consistency 💜
• --preview — prints the current color palette. vibes check ✅
• --vte — fixes the text-artifacts printed in VTE terminals. not the aesthetic we're going for 💀
• -c — deletes all cached colorschemes. gone. poof. 🎀
• -i /path/to/img.jpg — which image or directory to use.
• -l — generate a light colorscheme 🌈
• -n — skips setting the wallpaper. hands off, she's not touching it.
• -o script_name — external script to run after wal.
• -p theme_name — permanently saves the theme to $XDG_CONFIG_HOME/wal/colorschemes with the specified theme_name. committing to the bit 💍
• -q — quiet mode, doesn't print anything. shhh 🤫
• -r — wal -r is deprecated: use (cat ~/.cache/wal/sequences &) instead.
• -R — restores the previous colorscheme. we're going back 🕰️
• -s — skips changing colors in terminals.
• -t — skips changing colors in tty.
• -v — prints the wal version.
• -w — use the last used wallpaper for color generation.
• -e — skips reloading xrdb/i3/sway/polybar.
• --contrast [1.0-21.0] — specifies a minimum contrast ratio between the palette colors and the source image, per W3 contrast specs. Values between 1.5-4.5 typically work best ✨

---

🎀 CONFIGURATION 🎀

wal gets configured through a handful of ENV VARS, and here's the full roster:

• XDG_CONFIG_HOME — the parent directory to the user wal/templates dir.
• PYWAL_CACHE_DIR — explicitly sets the cache dir for the built templates. This has precedence over the XDG_CACHE_HOME/wal dir. she said i go first 💅
• NO_FUN — one of the env variables that controls the display of eastereggs. It acts as a negative switch, ie: setting it to 1 will disable the display of eastereggs, while leaving this var unset or setting it to 0 will allow the display of eastereggs. no fun allowed mode 🙈
• EASTEREGGS — one of the env vars that controls the display of eastereggs. It's a switch type variable: setting it to 0 will disable the display of eastereggs, while setting it to 1 or leaving it unset will enable the display of eastereggs. 🥚✨
• SHITPOSTS — one of the env variables that controls the display of eastereggs, and it acts as a switch: setting it to 1 will enable the display of the shitpost type eastereggs, while leaving this var unset or setting it to 0 will disable the display of shitposts. This means, unlike the regular eastereggs, the shitposts are OPT-IN. you gotta want it 💀
• JOBLESS_FAT_BASTARD_STOP_BEGGING_FOR_MONEY — this is the env var to control the display of the donations message. It acts as a negative switch: setting it to 1 will disable the donations message completely, while leaving it unset or setting it to 0 will allow the donations message to be displayed. 😭

---

🧚 TEMPLATES 🧚

wal supports user defined template files, and here's what that means: similar to the export files in the $XDG_CACHE_HOME/wal/ directory, you can create your own files which will be processed by pywal and spat out in this directory. you're basically designing your own merch 🎀

Subdirectories with templates are also supported inside the templates dir. nesting, we love her 🦋

The user defined files are read from $XDG_CONFIG_HOME/wal/templates/ and are exported to $XDG_CACHE_HOME/wal/ under the same name. And using this feature you can also overwrite the default export files. yes, overwrite. powerful. 👑

---

⭐ MISC ⭐

This is the section for other important information about using pywal16 that doesn't fit a specific section. the miscellaneous drawer, if you will.

🌈 XDG_SESSION_TYPE, DISPLAY, WAYLAND_DISPLAY

The XDG_SESSION_TYPE env var is needed to set the wallpaper when you're running an environment consisting of a standalone x11 window manager or wayland compositor — i.e. not a full desktop environment. If XDG_SESSION_TYPE is not available, the DISPLAY and WAYLAND_DISPLAY vars are used as a fallback to detect the active display protocol. This avoids relying only on XDG_SESSION_TYPE, which may be set to "tty" on some setups (for example when starting X manually with startx) or not set at all. If WAYLAND_DISPLAY is set, the session is treated as Wayland. If DISPLAY is set (and WAYLAND_DISPLAY is not), the session is treated as X11. 🖥️

This is necessary because some setups may have the packages for (example) BOTH i3 and sway, so in previous releases swaybg had priority over feh and would be run as the wallpaper setter regardless of whether the user was currently running i3 or sway. These checks let us follow the corresponding chain of possible wallpaper setters. teamwork, but make it detection logic 🫶

💀 ImageMagick 7 Policy

Back in about march 2024, ImageMagick 7 changed its default policy to not allow writing to STDOUT. So just locate the file /etc/ImageMagick-7/policy.xml (if that's not the name in your distro, consult the package file list), then find the line:

<policy domain="path" rights="none" pattern="-"/>

and change rights="none" to rights="write".

For convenience you could use the following sed command:

sudo sed 's/policy domain="path" rights="none" pattern="-"/policy domain="path" rights="write" pattern="-"/' /etc/ImageMagick-7/policy.xml

Worth noting that in distros like debian and derivates, the ImageMagick policy is modified at packaging time to allow writes to STDOUT. so you might not even need this, lucky you 🍓

---

👑 ORIGINAL AUTHOR 👑

Dylan Araps — <dylan.araps at gmail.com>

🫶 MAINTAINER 🫶

eylles — <ed.ylles1997 at gmail.com>

🌟 CONTRIBUTORS 🌟

For a list of contributors, run git shortlog -s in the nsxiv git repository.

🔗 HOMEPAGE 🔗

Source code:

https://github.com/eylles/pywal16

---

and that's the page bestie 💖 this was pywal16, manual section WAL(1), stamped with the WAL(1) footer energy — go generate some colorschemes, you're gonna slay ✨🎀