GitHub - nitinbhat972/cwal: Blazing-fast pywal-like color palette generator written in C.

Introduction

cwal is a fast and lightweight command-line tool for generating dynamic color schemes from images. It extracts dominant colors from your chosen image and applies them to your terminal, applications, and other system components, providing a cohesive and visually appealing desktop experience.

Features

Dynamic Color Generation: Extracts a vibrant 16-color palette from any image
Surgical Config Injection: Update specific sections of your existing configuration files without losing manual edits
XDG Compliant: Follows the XDG Base Directory Specification for config, cache, and data
Advanced Backend Support: Utilizes ImageMagick or libimagequant for efficient color quantization
Lua Scripting Support: Create custom backends using Lua scripts for advanced color quantization
Extensive Customization: Fine-tune saturation, contrast, alpha transparency, and theme mode (dark/light)
Smart Template Engine: Generates color schemes for various applications with intelligent shade generation
Automatic Application Reloading: Seamlessly integrates with your system to apply changes instantly
Palette Preview: View the generated color palette directly in your terminal
Random Image Selection: Automatically pick a random image from a directory (remembers your last directory)
Theme Management: Load predefined themes or select random themes with automatic generation bypass
Shell Completions: Smart completion scripts for Bash, Zsh, and Fish

Showcase

Dark mode

Light mode

Installation

cwal requires ImageMagick 6 or 7, libimagequant, and LuaJIT as dependencies.

Prerequisites

Ensure the following libraries are installed on your system:

ImageMagick 6 or 7 (MagickWand)
libimagequant
LuaJIT

Ubuntu/Debian

sudo apt install libmagickwand-dev libimagequant-dev libluajit-5.1-dev

Arch Linux

sudo pacman -S imagemagick libimagequant luajit

Fedora/RHEL

sudo dnf install ImageMagick-devel libimagequant-devel luajit-devel

macOS

brew install imagemagick libimagequant luajit

Package Manager

Arch Linux (AUR)

yay -S cwal-git
# or
paru -S cwal-git

Homebrew

brew tap nitinbhat972/cwal
brew install cwal

Nix

Install (user profile)

nix profile install nixpkgs#cwal

NixOS (system-wide)

environment.systemPackages = with pkgs; [
  cwal
];

Building from Source

We use nob to build this project — a small, stb-style single-header build system developed by tsoding. The build scripts live in nob.c and src/nob.c, and everything is configured through config.h.

Clone the repository:

git clone https://github.com/nitinbhat972/cwal.git
cd cwal

Build:

./nob

nob incrementally compiles src/ in parallel (controlled by PROCS in config.h, 0 = auto). Use ./nob clean to wipe build artifacts.

Install:

./nob install

This installs the cwal binary, templates, themes, and shell completions into INSTALL_DIR, which is defined in config.h (default /usr). Since INSTALL_DIR is a system directory by default, elevated privileges are needed to write there:

sudo ./nob install    # or: doas ./nob install

If INSTALL_DIR points to a user-local directory, plain ./nob install suffices. To do that, change INSTALL_DIR in config.h to your .local directory. A leading ~ is expanded to your home directory, so:

#define INSTALL_DIR "~/.local"

is equivalent to:

#define INSTALL_DIR "/home/yourname/.local"

To remove an installed cwal, run ./nob uninstall (remember to use sudo/doas again if you installed into a system directory).

Build Configuration

The entire build is driven by config.h:

BUILD_TYPE — selects the build profile. DEBUG compiles with -g for debugging; RELEASE optimizes with -O3 -DNDEBUG and strips the final binary
PROCS — number of parallel compile jobs (0 = automatic)
CUSTOM_CC — your preferred compiler; otherwise cc is resolved automatically
INCLUDES — include directories, passed to the compiler as -I<dir>
CFLAGS — extra compiler flags appended to every compilation
LIBS / PKGS — libraries to link against and pkg-config packages to resolve
INSTALL_DIR — install prefix used by the install command
BUILD_DIR / GENERATED_DIR — where build artifacts are placed

nob Usage

Usage: ./nob <Command>

Commands:
  build         Builds the project at `BUILD_DIR`
  clean         Removes all of the files in `BUILD_DIR`
  install       Installs the cwal and its artifacts in `INSTALL_DIR` (optionally prefixed by `DESTDIR` env)
  uninstall     Uninstalls the cwal along with all of its artifacts
  help          Prints this help message

NOTE:
  This `nob` build is specific to `cwal` and may not work in your project.

Usage

Usage: cwal [OPTIONS] --img <image_path>

--img <image_path> Specify the image path (required)
--mode <dark|light> Set theme mode
--cols16-mode <darken|lighten> Set 16-color mode
--saturation <float> Overall saturation
--contrast <float> Contrast ratio
--alpha <float> Alpha transparency (0.0-1.0)
--out-dir <path> Output directory for generated files
--backend <name> Set image processing backend
--script <script_path> Run custom script after processing
--no-reload Disable reloading
--restore Re-apply the last used wallpaper (no image required)
--list-backends List available backends
--list-themes List all available themes
--quiet Suppress all output
--random [directory] Select random image (uses config default if directory omitted)
--theme <theme_name|random_all> Select a theme or a random one
--preview Preview palette
--skip-cursor Skip writing the cursor color sequence
--version Show version number
--help Help

Examples:

cwal --img /path/to/image.jpg
cwal --random ~/Pictures/wallpapers    # Use specific path and save it
cwal --random                          # Use the directory saved in config
cwal --theme random_all                # Pick a random predefined theme
cwal --img /path/to/image.jpg --alpha 0.8 --saturation 0.1
cwal --img /path/to/image.jpg --skip-cursor  # Skip OSC 12 cursor color sequence

Configuration

cwal follows the XDG Base Directory Specification.

The structured INI file is located at ${XDG_CONFIG_HOME:-~/.config}/cwal/cwal.ini.

[general]
out_dir = /home/user/.cache/cwal/
backend = cwal
script_path = /home/user/.local/bin/post-cwal.sh

[options]
alpha = 1.00
saturation = 0.00
contrast = 1.00
mode = dark
cols16_mode = darken
skip_cursor = false

[random]
random_dir = /home/user/Pictures/Wallpapers

[links]
# format: template_name = destination_path | reload_command
colors-waybar.css = ~/.config/waybar/colors.css | pkill -USR2 waybar

# Omit the command to only sync the file
colors-kitty.conf = ~/.config/kitty/current-theme.conf

# Omit the destination to only run a reload command.
# The template name is arbitrary use any alias.
_ = | pkill -USR2 waybar
mako = | makoctl reload

Surgical Injection (Placeholders)

Instead of overwriting an entire configuration file, you can add markers to your existing files. cwal will only replace the text between these markers:

# ~/.config/alacritty/alacritty.toml
[window]
padding = { x = 5, y = 5 }

# --- $CWAL_START ---
# (cwal will inject colors here)
# --- $CWAL_END ---

[font]
size = 12

Templates

cwal searches for templates in the following order:

${XDG_CONFIG_HOME:-~/.config}/cwal/templates (user config)
${XDG_DATA_HOME:-~/.local/share}/cwal/templates (user local)
${INSTALL_DIR:-/usr}/share/cwal/templates (system-wide, set at build time in config.h)

Supported apps: Terminal emulators (Alacritty, Kitty, Wezterm, Ghostty, Foot), window managers (i3, bspwm, Hyprland, Sway), system monitors (Btop), text editors (Vim, Neovim, VS Code), and more.

Color Formatting in Templates

cwal templates support various color formatting options. You can use these formats within your templates to customize the output for different applications.

Format Specifier	Description	Example Output (for color with R=255, G=128, B=0, Alpha=0.8)
`hex`	Hexadecimal color code (e.g., `#RRGGBB`)	`#ff8000`
`xhex`	Hexadecimal color code with `0x` prefix	`0xff8000`
`strip`	Hexadecimal color code without prefix	`ff8000`
`rgb`	RGB format (e.g., `rgb(R,G,B)`)	`rgb(255,128,0)`
`rgba`	RGBA format (e.g., `rgba(R,G,B,A)`)	`rgba(255,128,0,0.8)`
`hexa`	Hexadecimal color code with alpha (e.g., `#RRGGBBAA`)	`#ff8000cc`
`red`	Red component value (0-255)	`255`
`green`	Green component value (0-255)	`128`
`blue`	Blue component value (0-255)	`0`

In addition to color-specific formats, you can use these global placeholders anywhere in your template:

Placeholder	Description	Example Output
`{mode}`	Current theme mode (`dark` or `light`)	`dark`
`{wallpaper}`	Absolute path to the current wallpaper image	`/home/user/Pictures/wall.jpg`
`{alpha}`	Alpha transparency value (0.00 - 1.00)	`0.80`
`{alpha.hex}`	Alpha transparency in 2-digit hexadecimal format	`cc`
`{alpha.pct}`	Alpha transparency in percentage integer format	`80`
`{alpha.int}`	Alpha transparency in raw integer format (0-255)	`204`
`{alpha.dec}`	Alpha transparency in decimal float format	`0.80`

Example usage in a template:

# For color0 (background)
background = {color0.hex}
background_rgb = {color0.rgb}
background_alpha = {color0.rgba}

# For color1 (foreground)
foreground = {color1.strip}
foreground_red = {color1.red}

Themes

cwal searches for themes in the following order:

${XDG_CONFIG_HOME:-~/.config}/cwal/themes (user config)
${XDG_DATA_HOME:-~/.local/share}/cwal/themes (user local)
${INSTALL_DIR:-/usr}/share/cwal/themes (system-wide, set at build time in config.h)

Themes are *.cwal files in dark/ and light/ subdirectories. List with cwal --list-themes, load with cwal --theme <name> or cwal --theme random_all.

Creating Custom Themes

Create a *.cwal file in ${XDG_CONFIG_HOME:-~/.config}/cwal/themes/dark/ or light/:

mode=dark
color0=26,28,33
color1=197,95,95
# ... color2..color15
color15=220,220,220

Use colorN=R,G,B (0-255) and mode=dark|light. Place as mytheme.cwal then cwal --theme mytheme or cwal --list-themes will find it. See themes/dark/ for examples.

Advanced Usage

Check available backends: cwal --list-backends
Choose backend: cwal --img image.jpg --backend libimagequant
Post-process script: cwal --img image.jpg --script "~/.local/bin/update-theme.sh $current_wallpaper" (Note: You can use the $current_wallpaper placeholder in your script path or arguments, and cwal will automatically replace it with the path of the currently processed image).
Batch processing:

for img in ~/Pictures/wallpapers/*.{jpg,png,jpeg}; do
    cwal --img "$img" --quiet
done

Lua Scripting Support

cwal now supports custom backends using Lua scripts. This allows you to implement your own color quantization algorithms or image processing techniques.

To create a custom backend:

Create a Lua script with a Main(image_path) function that returns a table of 16 colors, each as {r, g, b} where r, g, b are integers 0-255.
Place the script in ${XDG_CONFIG_HOME:-~/.config}/cwal/backends/ (the directory will be created if it doesn't exist).
Use the backend by its name (script filename without .lua) with --backend <name>.

The script receives the image path and should process it to generate the palette.

Simple template:

function Main(image_path)
        -- Open the image from the path that cwal passed in.
        local image = open_image(image_path)

        -- Run your palette extraction or quantization code here.
        local palette = quantize_algorithm(image)

        return palette
end

This is pseudo-code. open_image and quantize_algorithm are placeholders for your own logic. The important part is that Main receives image_path and returns exactly 16 colors as {r, g, b} entries.

Save it as:

${XDG_CONFIG_HOME:-~/.config}/cwal/backends/mybackend.lua

Then run:

cwal --img ~/Pictures/wallpapers/forest.jpg --backend mybackend

image_path is the wallpaper path passed in by cwal. You can ignore it like this example does, or use it later when you want more custom logic.

Shell Completions

cwal includes comprehensive, XDG-compliant completion scripts for Bash, Zsh, and Fish. These scripts provide smart suggestions for flags, theme names, and image files.

Zsh: Ensure /usr/local/share/zsh/site-functions is in your $fpath.
Fish: Completions are installed to /usr/local/share/fish/vendor_completions.d/ and work automatically.
Bash: Ensure the bash-completion package is installed.

For manual installation, you can source the scripts located in the shell/ directory.

Name and Attribution

The name "cwal" is the official project name for the upstream repository: https://github.com/nitinbhat972/cwal

If you distribute modified versions of this project, please use a different name to avoid confusion with the original project.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on how to contribute and our commit message conventions.

Report issues, request features, or contribute via PRs. See the GitHub repository for more info.

License

Licensed under GNU GPL v3.0 — always free and open-source.

Star the project on GitHub if you find it useful!

Special Thanks

pywal by dylanaraps
pywal16 by eylles

Name		Name	Last commit message	Last commit date
.github		.github
include		include
shell		shell
src		src
templates		templates
themes		themes
.clang-format		.clang-format
.git-blame-ignore-revs		.git-blame-ignore-revs
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
VERSION		VERSION
config.h		config.h
nob.c		nob.c
nob.h		nob.h
nob_helper.h		nob_helper.h

Navigation Menu

Repository files navigation

Introduction

Table of Contents

Features

Showcase

Installation

Prerequisites

Package Manager

Nix

Install (user profile)

NixOS (system-wide)

Building from Source

Build Configuration

nob Usage

Usage

Configuration

Surgical Injection (Placeholders)

Templates

Color Formatting in Templates

Themes

Creating Custom Themes

Advanced Usage

Lua Scripting Support

Shell Completions

Name and Attribution

Contributing

License

Special Thanks

About

Releases

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Introduction

Table of Contents

Features

Showcase

Installation

Prerequisites

Package Manager

Nix

Install (user profile)

NixOS (system-wide)

Building from Source

Build Configuration

nob Usage

Usage

Configuration

Surgical Injection (Placeholders)

Templates

Color Formatting in Templates

Themes

Creating Custom Themes

Advanced Usage

Lua Scripting Support

Shell Completions

Name and Attribution

Contributing

License

Special Thanks

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Used by

Contributors

Languages