Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install wallrust

It will make the wallrust command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall wallrust uninstalls.

Back to the crate overview.

Readme

Wallrust

Extract color palettes from images and instantly rice any setup or config file. wallrust lets you blueprint your desired files, automatically populates them with colors and palettes, and saves them to your specified paths.

Why Wallrust?

Flexible Color Extraction: Effortlessly generate beautiful palettes with defaults, or dive deep with advanced custom color curves, brightness/fuzz etc.
Ultimate Ricing tool : Blueprint any config file/script and orgnize them. wallrust automatically populates your blueprints with extracted image colors and places the generated files where you specify. And even backup previous ones. (yes! you can keep all your dotfiles in one place!)
Visual Preview: Immediately view your generated color schemes on an auto-generated HTML preview page.
Performance:

Installation
Usage
Advanced Usage
- Fuzz
- Custom Curve
Custom Templates (Config File Blueprint)

Installation

Arch Linux

wallrust is available on the Arch User Repository (AUR).

Pre-built binary (recommended):
```
yay -Sy wallrust-bin
```
Build from source:
```
yay -Sy wallrust
```

Cargo

Install wallrust from crates.io:

cargo install wallrust

From Pre-built Binaries

You can download pre-compiled binaries directly from the releases page.

For example, for version 1.0.4 on Linux x86_64:

wget https://github.com/prime-run/wallrust/releases/download/v1.0.4/wallrust-1.0.4-linux-x86_64.tar.gz
tar -xvf wallrust-1.0.4-linux-x86_64.tar.gz
sudo mv wallrust-1.0.4-linux-x86_64/wallrust /usr/local/bin/wallrust
# Ensure /usr/local/bin is in your $PATH

*Note: Adjust the version and target architecture as needed.

From Source

Clone the repository:

git clone https://github.com/prime-run/wallrust.git
cd wallrust

Build and install using:
- Makefile (for release build):
```
make install # Installs to ~/.cargo/bin by default
```
- Cargo (for debug build):
```
cargo build
```
- Cargo Make: A cargo-make.toml file is also included for more complex build tasks if needed.
```
cargo make --list # To see available tasks
cargo make build # Example task
```

Usage

wallrust <OPTIONS> <IMAGE>
#
wallrust /path/to/image

By default, 3 color palette files ( .css , .dcol , .json) will be generated in the same directory as image. You can specify the output directory by passing -o /some/path/ or --output-dir /some/path/.

[!TIP] By default, Wallrust generates 4 Primary colors and 4 text colors to go with them. And also 9 accent colors (shades) for each primary. Also dark mode is set by default.

HTLM visuals

wallrust ./example.png --html --output-dir /path/to/my-dir/ --wallset --colors 4

here is an example HTML file generated from this image (with --wallset flag)

main-togo-screen-shot

Wallset flag

Extracts color palettes that closely match the overall average colors of your wallpaper, making the generated palette more faithful to what you actually see on your desktop. Additionally, this mode outputs and caches a .dcol file compatible with theme-switching scripts.

*Inspired by wallbash

[!NOTE] Technically, this mode analyzes a scaled-down version of your image and uses a hash-based filename for consistent results.

and more examples!

wallrust ~/Pictures/wallpaper.jpg --vibrant


# Extract 6 colors instead of default 4 <colors> Uint
wallrust ~/Pictures/wallpaper.jpg --colors 6

# Force regeneration (ignore cache)
# not recommended caching engine here is  smart! and reliable
wallrust ~/Pictures/wallpaper.jpg --force

# Generate thumbnails and hash-based dcol files
wallrust ~/Pictures/wallpaper.jpg --wallset

# Skip custom template (blueprint) generation
wallrust ~/Pictures/wallpaper.jpg --no-templates

# ADVANCED Custom color curve (9 points of brightness and saturation)
wallrust ~/Pictures/wallpaper.jpg --custom "10 99\n17 66\n24 49\n39 41\n51 37\n58 34\n72 30\n84 26\n99 22"

Command-Line Options

Flag	Action
`-f`, `--force`	Force regeneration (ignore cache)
`-o`, `--output-dir <DIR>`	Set custom output directory
`--html`	Generate HTML visualization of the color palette
`--colors <N>`	Number of primary colors [default: 4]
`--fuzz <N>`	Color fuzziness percentage [default: 70]
`--detect-hyprland`	Detect current Hyprland wallpaper
`--wallset`	Generate thumbnails and dcol files compatible with wallbash scripts
`--no-templates`	Skip custom template generation
`-v`, `--vibrant`	Use vibrant color profile
`-p`, `--pastel`	Use pastel color profile
`-m`, `--mono`	Use monochrome profile
`-c`, `--custom <CURVE>`	Use custom color curve
`-d`, `--dark`	Force dark sort mode
`-l`, `--light`	Force light sort mode
`-h`, `--help`	Print help

Outputs

By default Wallrust generates these files in the output directory:

wallrust.dcol: Shell variables with color values
wallrust.css: CSS color variables
wallrust.json: Palette data in JSON format
Custom template outputs (if path is not set in templates)

When using the --wallset flag, additional files are generated:

Thumbnail in ~/.cache/wallrust/thumbs/{hash}.thmb
Hash-based dcol file in ~/.cache/wallrust/dcols/{hash}.dcol

Advanced Usage

fuzz

The --fuzz <N> flag controls how much Wallrust groups similar colors when extracting your palette.

Higher values (e.g., 90) group more similar colors together, resulting in a simpler palette with fewer, broader color groups.
Lower values (e.g., 30) keep more subtle color differences, resulting in a more detailed palette with more unique colors.
Default: 70 (good for most images)

Examples:

wallrust my.jpg --fuzz 90   # Fewer, broader color groups
wallrust my.jpg --fuzz 30   # More unique, detailed colors

ImageMagick: Color Quantization and Fuzz

custom curve

The --custom flag lets you pass your own color curve; A sequence of points, each written as <brightness> <saturation>, one per line. we smoothly interpolates between these points to create your palette.

Brightness: 0 (darkest) to 100 (brightest)
Saturation: 0 (gray) to 100 (most vivid)


#  built-in Mono Profile's custom curve:
wallrust my.jpg --custom "0 0\n100 0"


# below curve starts with a dark, slightly muted color (10 30), moves to a mid-brightness,
# even more  muted color (50 20), and ends with a very bright, very muted (almost gray) color (90 10).
# The result is a set of soft, pastel-like colors with low saturation throughout the brightness range
# (built-in pastel profile).

wallrust my.jpg --custom "10 30\n50 20\n90 10"


# Vivid to Muted Fade
# Starts vivid, fades to muted as brightness increases
wallrust my.jpg --custom "10 100\n50 60\n90 10"

Custom Templates (config file blueprint)

We use Tera syntax in templates (blueprints). If you have no idea what that is, Don't worry you don't have to! just make sure you read wallrust-template-toturial first.

Create template files in ~/.config/wallrust/templates/mytemplate.file using Tera syntax.

Available template variables:

Variable	Description
`mode`	`"dark"` or `"light"`
`wallpaper`	Path to target wallpaper/image
`primary`	Array of primary hex colors
`text`	Array of text hex colors
`accents`	2D array of accent hex colors by primary index
`primary_rgba`	RGBA versions of primary colors
`text_rgba`	RGBA versions of text colors
`accents_rgba`	RGBA versions of accent colors

Template Output Path and Backup Directives

You can control where a template's output is written and whether to back up the previous file by adding special directives at the top of your template:

Output Path: Write the rendered file to a specific location (supports ~ and environment variables):
```
{# output: ~/.config/kitty/colors.conf #}
#!output: ~/.config/kitty/colors.conf
```
If not specified, the output will be written to the default output directory.
Backup: If set to true, and the output file exists, it will be backed up to <output_path>.wr.bakup before being overwritten:
```
{# backup: true #}
#!backup: true
```
Default is false (no backup).

Example at the top of a template:

{# output: ~/.config/kitty/colors.conf #}
{# backup: true #}

For more information on templates, checkout Templating.

Requirements

ImageMagick
Optional: hyprctl (for Hyprland wallpaper detection)

Contributing

Contributions are welcome! Whether it's bug reports, feature suggestions, or code contributions, please feel free to open an issue or submit a PR.

Please ensure that any code contributions follow the existing style.

License

This project is licensed under MIT - see the LICENSE file for details.