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

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

```bash
curl -sSLO https://git.rootiest.dev/rootiest/color-tool/releases/download/latest/color-tool
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

```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
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.