Files

T

refactor: remove references to legacy setting

The `--alpha` flag and `alpha = true/false` config file options remain
functional but references to them are removed as they are now superseded
by the output formats with alpha channels (rgba, hexa, hsla).
New users/configurations should use the relevant output formats. The
legacy flag/options remain active for backward-compatibility with older
configs/scripts.

2026-04-27 23:58:14 -04:00

4.8 KiB

Raw Blame History

color-tool

A feature-rich, portable CLI color utility for Linux, specializing in color picking, conversion, and formatting. Designed primarily for KDE Plasma on Wayland, color-tool provides a seamless bridge between your screen and your development environment.

🌈 Key Features

Advanced Color Picking: Integration with KWin's DBus ColorPicker for pixel-perfect selection on Wayland.
Robust Conversions: Support for HEX, RGB, HSL, and their Alpha-enabled counterparts (HEXA, RGBA, HSLA).
Format Flexibility: Request multiple formats at once, or use all for a complete breakdown.
Smart JSON Output: Generate machine-readable JSON tables for easy integration with other tools.
Color Naming: Resolve hex values to human-readable names via thecolorapi.com.
Visual Previews: Render color swatches directly in your terminal using truecolor ANSI escapes.
Desktop Integration: Built-in support for clipboard copying (wl-copy/xclip) and desktop notifications.
Highly Configurable: Separate configuration profiles for standard terminal usage and desktop/launcher mode.
Portable Design: The entire tool is contained within a single Bash script, with embedded Python helpers.

📋 Prerequisites

To utilize all features, ensure the following are installed:

KDE Plasma + Wayland: Required for the --pick functionality.
Python 3 + PyQt6: Required for the picker helper.
curl + jq: Required for color naming support.
wl-clipboard (Wayland) or xclip (X11): Required for clipboard support.
libnotify: Required for desktop notifications (notify-send).

🚀 Installation

Simply download the color-tool script and run the install command:

chmod +x color-tool
./color-tool --install

This will:

Move the script to ~/.local/share/color-tool/.
Symlink the binary to ~/.local/bin/color-tool.
Generate a sample configuration at ~/.config/color-tool/config.toml.
Create a .desktop entry so you can launch the picker from your application menu.

🛠 Usage

Usage: color-tool [OPTIONS] [COLOR ...]

Options:
  --[no-]pick    Open the KDE Plasma color picker
  --output FMT   Format(s): hex, rgb, hsl, rgba, hsla, hexa, all (comma-separated)
  --[no-]json    Output as a JSON table of selected formats
  --[no-]name    Fetch nearest color name from thecolorapi.com
  --[no-]swatch  Include a color swatch in the terminal output
  --[no-]copy    Copy result to clipboard
  --[no-]notify  Show desktop notification
  --desktop      GUI mode: pick → copy → notify
  --install      Install to ~/.local/share/ and symlink to ~/.local/bin/
  --help, -h     Show this help message

Examples

Pick a color and get HSL + RGB:

color-tool --pick --output hsl,rgb

Convert a hex value with a visual swatch and color name:

color-tool "#ff5500" --swatch --name

Output all formats as JSON for a piped input:

echo "rgba(255, 85, 0, 0.5)" | color-tool --output all --json

Launch in "Silent" Desktop Mode (via terminal or launcher):

color-tool --desktop --no-name

⚙️ Configuration

You can define your preferred defaults in ~/.config/color-tool/config.toml. The tool uses a priority hierarchy: CLI Flags > Desktop Config > Default Config.

[defaults]
# Set any option to true to enable it by default when using the terminal
output = "hex"  # default output format(s): hex, rgb, hsl, rgba, hsla, hexa, all
json   = false  # output in JSON format
swatch = false  # show color swatch in terminal
name   = false  # fetch color name from thecolorapi.com
copy   = false  # copy result to clipboard
pick   = false  # auto-launch color picker when invoked with no arguments
notify = false  # show desktop notification

[desktop]
# Defaults for --desktop mode (launched from the app menu; copy is always enabled by default)
output = "hex"  # format to copy
json   = false  # copy JSON format instead of plain text
name   = false  # fetch color name (requires network)
copy   = true   # copy result to clipboard
notify = true   # show desktop notification with the copied value

🤝 Credits

The wl-colorpicker-plasma integration is based on the original work by SASUPERNOVA.

⚖️ License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

4.8 KiB Raw Blame History