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`).
- **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 `~/.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.
6. Clean up the downloaded script after installation.

### Manual Usage

Alternatively, you can [download the script](https://git.rootiest.dev/rootiest/color-tool/releases/latest) 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 ~/.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.