147 lines
5.7 KiB
Markdown
147 lines
5.7 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
## 🛠 Usage
|
|
|
|
```text
|
|
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:**
|
|
```bash
|
|
color-tool --pick --output hsl,rgb
|
|
```
|
|
|
|
**Convert a hex value with a visual swatch and color name:**
|
|
```bash
|
|
color-tool "#ff5500" --swatch --name
|
|
```
|
|
|
|
**Output all formats as JSON for a piped input:**
|
|
```bash
|
|
echo "rgba(255, 85, 0, 0.5)" | color-tool --output all --json
|
|
```
|
|
|
|
**Launch in "Silent" Desktop Mode (via terminal or launcher):**
|
|
```bash
|
|
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**.
|
|
|
|
```toml
|
|
[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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
./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](https://github.com/SASUPERNOVA/wl-colorpicker-plasma).
|
|
|
|
## ⚖️ 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](https://www.gnu.org/licenses/) for more details.
|