wallust(1)

📦 version 3.5.2, in nixos 26.05, nixpkgs unstable

🎀 NAME 🎀

okay bestie, meet wallust(1) — straight from the General Commands Manual — the little tool that will generate a 16 color scheme based on an image. literally that's the whole name, and it ate. 💅

✨ SYNOPSIS ✨

wallust [-I|--ignore-sequence] [-q|--quiet] [-s|--skip-sequences]
[-T|--skip-templates] [-u|--update-current] [-C|--config-file]
[-d|--config-dir] [--templates-dir] [-N|--no-config] [--no-hooks]
[-h|--help] [-V|--version] <subcommands>

🦋 DESCRIPTION 🦋

so here's the vibe: wallust splits the whole color-making situation into these methods, bestie:

  • Backends — how to extract the colors from the image (e.g. pywal uses convert).
  • Color Space — get the most prominent color, and sort them according to the palette, configurable with a threshold.
  • Palette — makes a scheme palette with the gathered colors (e.g. sets a light background).
Reminder: the options below can be used after the subcommand. for example: wallust --quiet run image.png is the same as wallust run --quiet image.png.

💅 OPTIONS 💅

one bullet per flag, no skipping, periodt:

  • -I, --ignore-sequence <IGNORE_SEQUENCE> — won't send these color sequences. possible values: background, foreground, cursor, color0, color1, color2, color3, color4, color5, color6, color7, color8, color9, color10, color11, color12, color13, color14, color15.
  • -q, --quiet — don't print anything.
  • -s, --skip-sequences — skip setting terminal sequences.
  • -T, --skip-templates — skip the templating process.
  • -u, --update-current — only update the current terminal.
  • -C, --config-file <CONFIG_FILE> — use CONFIG_FILE as the config file.
  • -d, --config-dir <CONFIG_DIR> — uses CONFIG_DIR as the config directory, which holds both wallust.toml and the templates files (if existent).
  • --templates-dir <TEMPLATES_DIR> — uses TEMPLATE_DIR as the template directory.
  • -N, --no-config — won't read the config and avoids creating its config path.
  • --no-hooks — ignore all hooks.
  • -h, --help — print help (see a summary with -h).
  • -V, --version — print version.

👑 SUBCOMMANDS 👑

  • wallust-run(1) — generate a palette from an image.
  • wallust-cs(1) — apply a certain colorscheme.
  • wallust-theme(1) — apply a custom built in theme.
  • wallust-migrate — migrate v2 config to v3.
  • wallust-debug — print information about the program and the environment it uses.
  • wallust-help — print this message or the help of the given subcommand(s).

🌈 TERMINAL COLORS 🌈

by default, wallust sends these sequences to all open terminals:

  • /dev/pts/ on Linux
  • /dev/ttys00 on MacOS.
  • ps to search active terminals[1] on OpenBSD
  • updates settings.json on Windows Terminal, to enable this scheme for the first time you will have to select it manually.

you can skip this with the -s or --skip-sequences flag.

when opening new terminals you will notice that the color sequences are not applied. to solve this you can send the sequences yourself when your shell opens. wallust will store the sequences in the cache directory as a file called sequences, the usual way is to cat ~/.cache/wallust/sequences in your .zshrc, .bashrc, etc.

🧚 TEMPLATE VARIABLES 🧚

🍓 COLORS 🍓

these types are formatted like HEX rgb (e.g. #0A0B0C) by default. but a color literal can be represented in multiple ways, like HEXA rgba (e.g. #0A0B0CFF, where FF is the transparency value) or HEX rgb without the leading # (0a0b0c).

the color variables are color0, color1, color2, color3, color4, color5, color6, color7, color8, color9, color10, color11, color12, color13, color14, color15, background, foreground and cursor.

colors — additionally, this variable returns a vector of all the presented colors in the following order: starts with color0 to color15, background, foreground and at the end (index 18 if starting from 0), cursor. see TEMPLATE SYNTAX for a practical guide.

🫶 MISCELLANEOUS 🫶

  • wallpaper — the full path to the current wallpaper, colorscheme file or the name of the theme in use.
  • backend — current backend being used.
  • colorspace — current colorspace being used.
  • palette — current palette being used.
  • alpha — defaults to 100, can be modified in the config file or with --alpha/-a.
  • alpha_dec — instead of 0 to 100, displays it from 0.00 to 1.00.

🔥 TEMPLATE FILTERS 🔥

the Jinja2 format calls them 'filters', making a distinction from 'functions'. currently I haven't implemented any function because I haven't found a usecase (yet?).

⭐ UNSIGNED INT ⭐

  • alpha_hexa — displays the alpha value as a hexadecimal color code[2] (e.g. {{ 100 | alpha_hexa }} outputs 'FF'). this can only be used with numbers from 0 to 100, so you are free to use the alpha variable with this filter.

💜 COLORS 💜

functions that only work with colors. these can be applied to a color, which can be the COLOR variables listed above (see TEMPLATE VARIABLES), or a literal color like "#0A0B0C". these functions return a color in the mentioned format (hex rgb, like "#000000"), unless written otherwise (like rgb, rgba, the other filters that explicitly say it's output format). this allows you to apply multiple filters at a time.

Note: if an alpha value is mentioned, it's defined in the config file, as a cli flag, and by default its value is 100.
  • hexa — outputs the color in hexa format: e.g. "#0A0B0CFF", where FF is the alpha value. Note: internally this uses the alpha_hexa filter from above.
  • rgb — output the color in rgb, separated by commas. (e.g. "10,11,12")
  • xrgb — output the color in xrgb, separated by slashes. (e.g. "0A/0B/0C")
  • strip — output the color in hex, just like by default, but removes the leading #. (e.g. "0A0B0C")
  • red — outputs only the red value. (e.g. "10")
  • green — outputs only the green value. (e.g. "11")
  • blue — outputs only the blue value. (e.g. "12")
  • complementary — returns the respective complementary color.
  • blend COLOR — takes another color as input, to blend it for the filtered color.
  • lighten amount — takes a float (decimal value) as input, from 0.1 to 1.0, that corresponds to the amount to lighten the color by.
  • darken amount — takes a float (decimal value) as input, from 0.1 to 1.0, that corresponds to the amount to darken the color by.
  • saturate amount — takes a float (decimal value) as input, from 0.1 to 1.0, that corresponds to the amount to saturate the color by.

🌸 TEMPLATE SYNTAX 🌸

you reference variables in the following syntax:

{{color0}}

for applying a filter you use the pipe character (|) like this:

{{background | strip}}

and if the filter requires an argument:

{{background | lighten(0.3)}}

remember that filters require a valid type to apply to; in these examples we are using colors, which can even be defined literally:

{{ "#4ff4ff" | lighten(0.3)}}

for both, being applied to or as an argument of a filter:

{{ color2 | blend("4ff4ff")}}

if you need to write a literal {{, that doesn't reference any variable, you can write literals inside the delimiters:

{{ "{{" }} {{ "}}" }}

you can also use control flow expressions with {% %} delimiters:

{% if backend == "wal" %}
I am using the '{{backend}}' backend, getting a pywal like scheme.
{% elif backend == "fastresize" %}
This backend is called "{{palette}}" and, uses SIMD optimizations and is so fast!
{% else %}
I don't care about any other backends. Be happy!
{% endif %}

or inline them:

{{ "I'm using the kmeans algo!" if backend == "kmeans" else "Some backend is in use" }}

since mostly everything can be represented as a string (we've seen how colors are represented), indexing is very useful! the syntax for indexing is basically the Python one.

{# I'll hardcode a color based on the palette being used. #}
{% if palette[:4] == "dark" %}
somevariable = "#eeffbb"
{% else %}
somevariable = "#aabbee"
{% endif %}

and yes, you can comment inside your template; the comments won't be rendered in the final target file:

{# This won't be visible! #}

there are more control flow instructions, like the for loop:

{# This will generate color0 = .. to color18,
since `colors` contains background, foreground and cursor variables #}
{% for c in colors %}
color{{- loop.index }} = {{c-}}
{% endfor %}

you can add a minus sign (-) at the start or the end of the delimiters to suppress vertical spacing[3].

the syntax comes from the library being used, which is minijinja, a subset of the template engine Jinja2.

you can read more at: Jinja2 official syntax[4] and contrast features with the supported syntax at Compatibility of minijinja[5].

🎨 TEMPLATE EXAMPLE 🎨

okay so you wanna use wallust-generated colors in a program? the move is templating the colors into its config file, like this, bestie:

# zathurarc config sample

# colors
set default-bg     "{{background}}"
set default-fg     "{{foreground}}"

# make it a bit lighter than background
set statusbar-bg   "{{background | lighten(0.3)}}"

# make it darken by blending to a darken color
set statusbar-fg   "{{foreground | blend("#eeeeee")}}"

# use it's complementary
set inputbar-bg    "{{background | complementary}}"

Then you can add this file to ~/.config/wallust/templates and use the config file to template it. For example, zathura.template = 'zathurarc', and then define a target field — see wallust(5) for that part 🫶.

🌈 PYWAL TEMPLATE COMPATIBILITY 🌈

You can enable pywal-like syntax in the config file with pywal = true — again, see wallust(5).

The syntax is simple, but more variables get added because its engine and spec don't support runtime evaluation functions.

And even though the implementation is simple enough to be added in wallust, using it is discouraged. like, it works, but maybe don't make it your whole personality 💅

🧃 Variables 🧃

  • color0, color1, color2, color3, color4, color5, color6, color7, color8, color9, color10, color11, color12, color13, color14, color15, background, foreground, cursor — plus their .rgb, .rgba, .xrgba, .strip, .red, .green, and .blue variants. Just append the variant to the variable name (e.g. "color0.rgb", "background.blue" …). slay.
  • wallpaper, alpha, and alpha_dec are also available — these don't support the variants from above.

✨ Syntax ✨

The syntax logic is simply “Find and Replace”, like:

somevariable = {color2}
anothervariable = {color8.rgb}

Don't forget to visit the full pywal spec[6] — it's linked in the notes below, iykyk 🫶.

🔗 SEE ALSO 🔗

go give these a lil look, bestie:

📝 NOTES 📝

  1. ps to search active terminals — https://github.com/dylanaraps/pywal/pull/510
  2. Hexadecimal color code — https://gist.github.com/lopspower/03fb1cc0ac9f32ef38f4
  3. White space contron with the minus sign (-) — http://jinja.pocoo.org/docs/templates/#whitespace-control
  4. Official Jinja2 documentation — https://jinja.palletsprojects.com/en/2.10.x/
  5. Compatibility of Minijinja with Jinja2 — https://github.com/mitsuhiko/minijinja/blob/main/COMPATIBILITY.md
  6. Full pywal template specification — https://github.com/dylanaraps/pywal/wiki/User-Template-Files
  7. Suggestions for new colorschemes returned by the themes subcommand should be filled here. — https://codeberg.org/explosion-mental/wallust-themes

🐛 BUGS 🐛

found a bug? it lives here, bestie:

https://codeberg.org/explosion-mental/wallust

wallust-3.5 · wallust(1) · footer date — byeeee 💖✨

📦 where this page comes from