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

### Required Core Dependencies
These are mandatory for the script to run and perform basic color conversions:
- **Python 3:** Handles all color space math and conversions.
- **jq:** Powers JSON formatting and internal data parsing.

### Optional Feature Dependencies
These enable specific functionality and can be installed as needed:
- **KDE Plasma (Wayland):** Required for screen color picking (`--pick`).
- **Python 3 PyQt6:** Required for the KDE color picker DBus interface.
- **wl-clipboard** or **xclip:** Enables copying results to the system clipboard (`--copy`). `wl-clipboard` is strongly preferred on Wayland — `xclip` operates through XWayland and can be unreliable. `--check-deps` and `--install` will warn you if only `xclip` is found.
- **curl:** Required for fetching human-readable color names from the web (`--name`).
- **libnotify:** Enables desktop notifications (`--notify`).
- **ImageMagick:** Generates visual color swatch icons for notifications (`--swatch`).
- **Truecolor Terminal Emulator:** Required for accurate visual swatches in terminal output (`--swatch`).

> **Tip:** Use `color-tool --check-deps` to quickly see which dependencies are currently met on your system.

## 🚀 Installation

### Automatic Installation (Recommended)

You can download the script directly from the [latest release](https://git.rootiest.dev/rootiest/color-tool/releases/latest) and install it:

```bash
# Download and install the latest version of the color-tool script
curl -sSLO https://git.rootiest.dev/rootiest/color-tool/releases/download/latest/color-tool && bash color-tool --install && rm ./color-tool
```

This will:
1. Install the script to `$XDG_DATA_HOME/color-tool/` (default: `~/.local/share/color-tool/`).
2. Symlink the binary to `~/.local/bin/color-tool`.
3. Generate a sample configuration at `$XDG_CONFIG_HOME/color-tool/config.toml` (default: `~/.config/color-tool/config.toml`).
4. Create a `.desktop` entry in `$XDG_DATA_HOME/applications/` so you can launch the picker from your application menu.
5. Verify and warn about any missing optional or required system dependencies.
6. Clean up the downloaded script after installation.

### Manual Usage

Alternatively, you can [download the script](https://git.rootiest.dev/rootiest/color-tool/releases/download/latest/color-tool) manually.
Then run it from any location without installation:

```bash
# Make script executable
chmod +x color-tool
# Run script directly
./color-tool --pick --output hex,rgb
```

However, this will not add the script to your `$PATH` or create a desktop entry,
so you won't be able to launch it from the app menu or use it globally without specifying the path.

## 🛠 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
  --check-deps   Check system dependencies and environment support
  --install      Install to $XDG_DATA_HOME/color-tool/ 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 `$XDG_CONFIG_HOME/color-tool/config.toml` (default: `~/.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
swatch = true   # show color swatch in notification
```

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.