color-tool/README.md

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 rich desktop notifications with visual color swatches.
• 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).
• ImageMagick (magick or convert): Required for generating visual color swatches in desktop notifications.

🚀 Installation

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

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

This will:

1. Move the script to ~/.local/share/color-tool/.
2. Symlink the binary to ~/.local/bin/color-tool.
3. Generate a sample configuration at ~/.config/color-tool/config.toml.
4. Create a .desktop entry so you can launch the picker from your application menu.
5. Verify and warn about any missing optional or required system dependencies.

🛠 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
  --get-config   Print the current configuration
  --set-config   Update the configuration (e.g. --set-config desktop --copy)
  --reset-config Restore the configuration file to its default values
  --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

You can also use the CLI to manage your configuration:

# View current config
color-tool --get-config

# Update specific keys (e.g., enable swatch by default)
color-tool --set-config defaults --swatch

# Set output format for desktop mode
color-tool --set-config desktop output=rgba

# Reset to factory defaults
color-tool --reset-config

🧪 Testing

The project includes a comprehensive test suite that verifies color conversion, configuration loading, and system integrations (clipboard/notifications) using mocks.

To run the tests:

./tests/run_tests.sh

The test script creates a temporary isolated environment, so it won't affect your system configuration or active clipboard.

🤝 Credits

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

⚖️ License

Copyright © 2026 Rootiest.

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.