README.md

May 10, 2026 · View on GitHub

Introduction

cwal showcase

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
Persistent Configuration: Remembers your preferred settings (alpha, mode, saturation, etc.) across sessions using a structured, XDG-compliant INI file
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

Run without installing

nix run github:nitinbhat972/cwal

Install (user profile)

nix profile install nixpkgs#cwal

NixOS (system-wide)

environment.systemPackages = with pkgs; [
  cwal
];

Building from Source

Clone the repository:

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

Build and install:

User-specific:

mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=$HOME/.local ..
make
make install

System-wide:

mkdir build && cd build
cmake ..
make
sudo make install

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

⚙️ Configuration

cwal follows the XDG Base Directory Specification.

The structured INI file is located at ${XDG_CONFIG_HOME:-~/.config}/cwal/cwal.ini. Most CLI flags are automatically saved to this file, so you don't have to provide them every time.

[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

[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 path to only run a reload command
colors-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_DATA_DIRS:-/usr/local/share:/usr/share}/cwal/templates (system-wide)
${XDG_DATA_HOME:-~/.local/share}/cwal/templates (user local)
${XDG_CONFIG_HOME:-~/.config}/cwal/templates (user config)

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)`
`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`

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}

🔧 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.

pywal by dylanaraps
pywal16 by eylles