wallust(1)

NAME
wallust - Generate a 16 color scheme based on an image.

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] [--no-templated-hooks] [-h|--help] [-V|--version] <subcommands>

DESCRIPTION
Methods | Description
Backends | How to extract the colors from the image (e.g. pywal uses convert).
Palette | Makes a scheme palette with the gathered colors (e.g. sets a light or dark 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

-I, --ignore-sequence <IGNORE_SEQUENCE>
    Won't send these colors 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 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 it's config path

--no-hooks
    Ignore all hooks

--no-templated-hooks
    Ignore templated 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-pywal(1)
    Drop-in CLI replacement for pywal

wallust-migrate
    Migrate config to v4

wallust-debug
    Print information about the program and the enviroment it uses

wallust-help
    Print this message or the help of the given subcommand(s)

TERMINAL COLORS
By default, wallust will send 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 selected 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 formated like as HEX rgb (e.g. '#0A0B0C') by default. However 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'). 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, foregroundand 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.

    palette
        Current **palette** being used.

    alpha
        Default 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 distincion from 'functions'.
Currently I haven't implemented any function because I haven't found a usecase (yet?).

UNSIGNED INT

    alpha_hexa
        Displays alpha value as 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 variable alpha 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 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 it's value is '100'.

    hexa
        Outputs the color in `hexa` format: e.g "#0A0B0CFF", where 'FF' is the alpha value. Note This, internally uses `alpha_hexa` filter from above.

    rgb Output the color in `rgb`, separated by comas. (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 references 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 results very useful! The syntax for indexing is basically the Python one.

    {# I'll hardcode a color based on the palette being used. #}
    {% if palette == "salience" %}
    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 supress 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
You can use wallust generated colors in a program by templating the colors in it's config file, like the following example:

    # 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).

PYWAL TEMPLATE COMPATIBILITY
You can enable pywal like syntax in the config file with `pywal = true', see wallust(5).
The syntax is simple, but more variables are added given that it's engine and spec doesn't support runtime evaluation functions.
While the implementation is simple enough to be added in wallust, it's use is discoraged.

Variables
    color0, color1, color2, color3, color4, color5, color6, color7, color8, color9, color10, color11, color12, color13, color14, color15, background, foreground, cursor, and it's .rgb, .rgba, .xrgba, .strip, .red, .green and .blue variants, just append it to the variable name (e.g. "color0.rgb", "background.blue" ...).
    wallpaper, alpha and alpha_dec are also avaliable, 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]

SEE ALSO
wallust(5), wallust-run(1), wallust-cs(1), wallust-theme(1), wallust-themes[7].

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
https://codeberg.org/explosion-mental/wallust