WAL(1)

NAME
wal - Generate colorschemes on the fly

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]]

DESCRIPTION
wal is a tool that generates a color palette from the dominant colors in an image. It then applies the colors system-wide and on-the-fly in all of your favourite programs.

OPTIONS

-h, --help
    Print brief usage information to standard output and exit.

-a alpha
    Set terminal background transparency to alpha. The value must be an integer between 0 and 100.
     *Only works in URxvt and terminals that implement the OSC-11 interface*

-b background
    Custom background color to use.

--fg foreground
    Custom foreground color to use.

--backend backend
    Which color backend to use. Use 'wal --backend' to list backends.

--out-dir /path/to/output dir
    Directory to output the built template files. By default wal will export 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, using this flag overrides the internal CACHE_DIR variable taking precedence over $PYWAL_CACHE_DIR.

-f, --theme /path/to/file or theme_name
    Which colorscheme file to use. Use 'wal --theme' to list builtin and user themes.

--iterative
    When pywal is given a directory as input and this flag is used: Go through the images in order instead of shuffled.

--cols16 method
    Use 16 color mode, this will generate 16 color themes or convert 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.

--saturate [-1.0-1.0]
    Set the color saturation. Interpret as percentage, ie: 1.00 = 100%, 0.50 = 50%,

--preview
    Print the current color palette.

--vte
    Fix text-artifacts printed in VTE terminals.

-c  Delete all cached colorschemes.

-i /path/to/img.jpg
    Which image or directory to use.

-l  Generate a light colorscheme.

-n  Skip setting the wallpaper.

-o script_name
    External script to run after "wal".

-p theme_name
    permanently save theme to $XDG_CONFIG_HOME/wal/colorschemes with the specified theme_name.

-q  Quiet mode, don't print anything.

-r  'wal -r' is deprecated: Use (cat ~/.cache/wal/sequences &) instead.

-R  Restore previous colorscheme.

-s  Skip changing colors in terminals.

-t  Skip changing colors in tty.

-v  Print "wal" version.

-w  Use last used wallpaper for color generation.

-e  Skip reloading xrdb/i3/sway/polybar

--contrast [1.0-21.0]
    Specify a minimum contrast ratio between palette colors and the source image according to W3 contrast specifications. Values between 1.5-4.5 typically work best.

CONFIGURATION

Wal is configured through a handful of ENV VARS, the following ones are used:

XDG_CONFIG_HOME
    Parent directory to the user wal/templates dir.

PYWAL_CACHE_DIR
    Explicitly set the cache dir for the built templates, this has precedence over the XDG_CACHE_HOME/wal dir.

NO_FUN
    One of the env variables that control the display 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.

EASTEREGGS
    One of the env vars that control the display of eastereggs, it is 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 control the display eastereggs, it acts as a switch, ie: 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.

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, leaving it unset or setting as 0 will allow the donations message to be displayed.

TEMPLATES

Wal supports user defined template files. What this means is that 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 spit out in this directory.

Subdirectories with templates are also supported inside the templates dir.

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

MISC

The section for other important information to using pywal16 that does not fit a specific section.

XDG_SESSION_TYPE, DISPLAY, WAYLAND_DISPLAY
    The XDG_SESSION_TYPE env var is needed to set the wallpaper when 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 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 setup may have the packages for (example) BOTH i3 and sway, so in previous releases swaybg had priority over feh and would be ran as wallpaper setter regardless of the user currently running i3 or sway, these checks allow us to follow the corresponding chain of possible wallpaper setters.

ImageMagick 7 Policy
    Back in about march 2024 ImageMagick 7 changed it's default policy to not allow writing to STDOUT, just locate the file /etc/ImageMagick-7/policy.xml (if that is 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.

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