2026-04-28 03:23:01 +00:00
1 changed files with 109 additions and 0 deletions
@@ -0,0 +1,109 @@
+# 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
+  --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]
+output = "hex"  # default output format(s)
+json   = false  # output in JSON format
+swatch = false  # show color swatch in terminal
+name   = false  # fetch color name
+copy   = false  # copy result to clipboard
+pick   = false  # auto-launch picker
+notify = false  # show desktop notification
+
+[desktop]
+output = "hex"
+json   = false
+name   = false
+copy   = true
+notify = true
+```
+
+## ⚖️ 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.