Cwal

Blazing-fast pywal-like color palette generator written in C.

Generate Convert Improve

Install / Use

/learn @nitinbhat972/Cwal

About this skill

Quality Score

0/100

README

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
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, libimagequant, and lua as dependencies.

Prerequisites

Ensure the following libraries are installed on your system:

imagemagick
libimagequant
lua (or liblua-dev)

Ubuntu/Debian:

sudo apt install imagemagick libimagequant-dev liblua5.4-dev

Arch Linux:

sudo pacman -S imagemagick libimagequant lua

Fedora/RHEL:

sudo dnf install ImageMagick-devel libimagequant-devel lua-devel

macOS

brew install imagemagick libimagequant lua

Arch Linux (AUR)

Install directly from the AUR:

yay -S cwal
# or
paru -S 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/
current_wallpaper = /home/user/Pictures/wall.png
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
colors-sway = ~/.config/sway/config | swaymsg 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 | | alpha_dec | Alpha transparency value (0.0-1.0) | 0.8 |

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

Related Skills

node-connect

334.5k

Diagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps

frontend-design

82.2k

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

openai-whisper-api

334.5k

Transcribe audio via OpenAI Audio Transcriptions API (Whisper).

commit-push-pr

82.2k

Commit, push, and open a PR